hatch3r 1.2.0 → 1.4.0

package/dist/cli/index.js

@@ -12,7 +12,7 @@ import ora from "ora";
 import boxen from "boxen";
 
 // src/version.ts
-var HATCH3R_VERSION = "1.2.0";
+var HATCH3R_VERSION = "1.4.0";
 
 // src/cli/shared/ui.ts
 var CYAN = chalk.hex("#06b6d4");
@@ -132,7 +132,7 @@ import { execFileSync as execFileSync2 } from "child_process";
 import chalk3 from "chalk";
 
 // src/types.ts
-var TOOLS = ["cursor", "copilot", "claude", "opencode", "windsurf", "amp", "codex", "gemini", "cline", "aider", "kiro", "goose", "zed", "amazon-q"];
+var TOOLS = ["cursor", "copilot", "claude", "opencode", "windsurf", "amp", "codex", "gemini", "cline", "aider", "kiro", "goose", "zed", "amazon-q", "antigravity"];
 var VALID_TOOLS = new Set(TOOLS);
 var TOOL_CHOICES = TOOLS.join(", ");
 var MANAGED_BLOCK_START = "<!-- HATCH3R:BEGIN -->";
@@ -140,9 +140,10 @@ var MANAGED_BLOCK_END = "<!-- HATCH3R:END -->";
 var HATCH3R_PREFIX = "hatch3r-";
 var AGENTS_DIR = ".agents";
 var HatchError = class extends Error {
-  constructor(message, exitCode = 1) {
+  constructor(message, exitCode = 1, errorCode = "UNKNOWN_ERROR") {
     super(message);
     this.exitCode = exitCode;
+    this.errorCode = errorCode;
     this.name = "HatchError";
   }
 };
@@ -275,8 +276,8 @@ async function resolvePatterns(rootDir, patterns) {
 }
 function isInsideWorktree(dir) {
   try {
-    const stat5 = statSync(join(dir, ".git"));
-    return stat5.isFile();
+    const stat6 = statSync(join(dir, ".git"));
+    return stat6.isFile();
   } catch {
     return false;
   }
@@ -356,6 +357,9 @@ var ADAPTER_WORKTREE_PATTERNS = {
   ],
   "amazon-q": [
     { pattern: ".amazonq/", strategy: "copy", reason: "Amazon Q adapter output (rules, settings)" }
+  ],
+  antigravity: [
+    { pattern: ".antigravity/", strategy: "copy", reason: "Antigravity adapter output (rules, skills, settings)" }
   ]
 };
 async function generateWorktreeInclude(manifest, rootDir) {
@@ -535,7 +539,7 @@ async function worktreeSetupCommand(worktreePath, opts = {}) {
       error("Worktree path is required when running from the main repo.");
       console.log(chalk3.dim("  Usage: hatch3r worktree-setup <worktree-path>"));
       console.log(chalk3.dim("  Or run this command from inside a worktree.\n"));
-      throw new HatchError("Missing worktree path", 1);
+      throw new HatchError("Missing worktree path", 1, "VALIDATION_ERROR");
     }
     targetRoot = join3(cwd, worktreePath);
   }
@@ -547,7 +551,7 @@ async function worktreeSetupCommand(worktreePath, opts = {}) {
     if (err.code === "ENOENT") {
       error(`No ${WORKTREE_INCLUDE_FILE} found in ${mainRoot}`);
       console.log(chalk3.dim("  Run `hatch3r init` or `hatch3r sync` to generate it.\n"));
-      throw new HatchError(`Missing ${WORKTREE_INCLUDE_FILE}`, 1);
+      throw new HatchError(`Missing ${WORKTREE_INCLUDE_FILE}`, 1, "FS_ERROR");
     }
     throw err;
   }
@@ -610,8 +614,9 @@ async function worktreeSetupCommand(worktreePath, opts = {}) {
 }
 
 // src/cli/commands/config.ts
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { dirname as dirname9, join as join17 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import { readFile as readFile17 } from "fs/promises";
+import { dirname as dirname11, join as join21 } from "path";
 import chalk5 from "chalk";
 import inquirer2 from "inquirer";
 
@@ -627,7 +632,8 @@ import {
   access,
   rename,
   unlink as unlink2,
-  open
+  open,
+  copyFile as copyFile2
 } from "fs/promises";
 import { dirname as dirname3, basename } from "path";
 import { randomBytes as randomBytes2 } from "crypto";
@@ -774,7 +780,16 @@ var DENY_PATTERNS = [
   /override\s+(all\s+)?security/i,
   /(?:atob|Buffer\.from)\s*\([^)]*(?:eval|exec|require)/i,
   /(?:chmod|chown)\s+[0-7]{3,4}/i,
-  /(?:api[_-]?key|password|token|secret)\s*[:=]\s*.{8,}/i
+  /(?:api[_-]?key|password|token|secret)\s*[:=]\s*.{8,}/i,
+  // Prompt injection indicators
+  /ignore\s+(all\s+)?previous\s+instructions/i,
+  /disregard\s+(all\s+)?(previous|prior|above)/i,
+  /you\s+are\s+now\s+(?:a|an|the)\s/i,
+  /new\s+instructions\s*:/i,
+  /system\s+prompt\s*:/i,
+  /forget\s+(all\s+)?(previous|prior|above)\s+(instructions|rules|context)/i,
+  /act\s+as\s+(?:a|an)\s+(?:unrestricted|unfiltered|jailbroken)/i,
+  /do\s+not\s+follow\s+(?:any|the|your)\s+(?:previous|prior|above|original)\s/i
 ];
 var ZERO_WIDTH_CHARS = /[\u200B\u200C\u200D\uFEFF\u00AD]/g;
 var MAX_CUSTOMIZE_MD_BYTES = 10240;
@@ -966,6 +981,14 @@ async function atomicWriteFile(filePath, content) {
         throw err;
       }
     }
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOSPC") {
+      throw new Error(
+        `Not enough disk space to write ${filePath}. Free up space and re-run the command.`
+      );
+    }
+    throw err;
   } finally {
     try {
       await unlink2(tmpPath);
@@ -991,7 +1014,7 @@ async function safeWriteFile(filePath, content, options = {}) {
       return {
         path: filePath,
         action: "skipped",
-        warning: `Skipped ${filePath}: existing file without managed block. Run hatch3r init --force to overwrite.`
+        warning: `Skipped ${filePath}: managed block markers (HATCH3R:BEGIN/END) missing. To fix: restore the markers around hatch3r content, or move your custom content and re-run hatch3r update.`
       };
     }
     const customContent = extractCustomContent(existingContent);
@@ -1000,11 +1023,13 @@ async function safeWriteFile(filePath, content, options = {}) {
     try {
       merged = insertManagedBlock(existingContent, options.managedContent);
     } catch {
+      const bakPath = filePath + ".bak";
+      await copyFile2(filePath, bakPath);
       await atomicWriteFile(filePath, content);
       return {
         path: filePath,
         action: "updated",
-        warning: `Auto-repaired corrupted managed block in ${filePath}`
+        warning: `Auto-repaired corrupted managed block in ${filePath} (backup saved to ${bakPath})`
       };
     }
     await atomicWriteFile(filePath, merged);
@@ -1023,7 +1048,7 @@ async function safeWriteFile(filePath, content, options = {}) {
   return {
     path: filePath,
     action: "skipped",
-    warning: `Skipped ${filePath}: existing file without managed block. Run hatch3r init --force to overwrite.`
+    warning: `Skipped ${filePath}: managed block markers (HATCH3R:BEGIN/END) missing. To fix: restore the markers around hatch3r content, or move your custom content and re-run hatch3r update.`
   };
 }
 
@@ -1137,6 +1162,22 @@ function validateManifest(data) {
     if (!specs.paths.every((v) => typeof v === "string")) return false;
     if (specs.lastGenerated !== void 0 && typeof specs.lastGenerated !== "string") return false;
   }
+  if (obj.workspace !== void 0) {
+    if (typeof obj.workspace !== "object" || obj.workspace === null) return false;
+    const ws = obj.workspace;
+    if (typeof ws.rootPath !== "string") return false;
+    if (typeof ws.lastSync !== "string") return false;
+    if (typeof ws.syncVersion !== "string") return false;
+    if (typeof ws.workspaceChecksum !== "string") return false;
+    if (ws.excludedContent !== void 0) {
+      if (!Array.isArray(ws.excludedContent)) return false;
+      if (!ws.excludedContent.every((v) => typeof v === "string")) return false;
+    }
+    if (ws.localContent !== void 0) {
+      if (!Array.isArray(ws.localContent)) return false;
+      if (!ws.localContent.every((v) => typeof v === "string")) return false;
+    }
+  }
   return true;
 }
 async function readManifest(rootDir) {
@@ -1294,10 +1335,10 @@ async function ensureEnvMcp(rootDir, servers) {
 }
 
 // src/cli/commands/update.ts
-import { cp as cp2, mkdir as mkdir4, readdir as readdir6, stat } from "fs/promises";
+import { cp as cp3, mkdir as mkdir5, readdir as readdir7, stat as stat2 } from "fs/promises";
 import { execFileSync as execFileSync3 } from "child_process";
 import { fileURLToPath } from "url";
-import { dirname as dirname7, join as join15 } from "path";
+import { dirname as dirname8, join as join16 } from "path";
 import chalk4 from "chalk";
 import inquirer from "inquirer";
 
@@ -1397,7 +1438,7 @@ async function readGlobMd(baseDir, fileType) {
   let entries;
   try {
     const all = await readdir(baseDir, { recursive: true });
-    entries = all.filter((f) => f.endsWith(".md"));
+    entries = all.filter((f) => f.endsWith(".md")).sort();
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
     return [];
@@ -1433,7 +1474,7 @@ async function readGlobMd(baseDir, fileType) {
 async function readSkillSubdirs(baseDir) {
   let dirents;
   try {
-    dirents = await readdir(baseDir, { withFileTypes: true });
+    dirents = (await readdir(baseDir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
     return [];
@@ -1517,7 +1558,16 @@ Full protocol: \`hatch3r-agent-orchestration\` rule in \`/.agents/rules/\`.
 - Rules: \`/.agents/rules/\` \u2014 Agents: \`/.agents/agents/\` \u2014 Skills: \`/.agents/skills/\`
 - Commands: \`/.agents/commands/\` \u2014 MCP: \`/.agents/mcp/mcp.json\` \u2014 Policy: \`/.agents/policy/\`
 
-Do not edit \`hatch3r-\` prefixed files \u2014 managed by hatch3r, overwritten on update.`;
+Do not edit \`hatch3r-\` prefixed files \u2014 managed by hatch3r, overwritten on update.
+
+## Getting Started (staged introduction)
+
+New to hatch3r? Start here and expand as you go:
+
+**Day 1 \u2014 Core workflow:** Use the 4-phase pipeline above for any task. Start by invoking \`hatch3r-researcher\` for context, then \`hatch3r-implementer\` for changes.
+**Week 1 \u2014 Skills & commands:** Load skills from \`/.agents/skills/\` matching your task type. Try \`/hatch3r-feature\` or \`/hatch3r-bug-fix\` commands.
+**Week 2 \u2014 Board & team:** If using project management, run \`/hatch3r-board-init\` to set up your board. Use \`/hatch3r-board-pickup\` for structured delivery.
+**Ongoing \u2014 Customization:** Override agent behavior via \`.hatch3r/{type}/{id}.customize.yaml\`. Add project learnings to \`/.agents/learnings/\`.`;
 async function generateBridgeOrchestration(agentsDir) {
   const skills = await readSkillDirs(join8(agentsDir, "skills"));
   if (skills.length === 0) return BRIDGE_ORCHESTRATION;
@@ -1897,13 +1947,14 @@ var BaseAdapter = class {
    * Adapters that violate these invariants will produce broken output files or
    * corrupt user content during the merge phase.
    */
-  async generate(agentsDir, manifest) {
+  async generate(agentsDir, manifest, generationMode = "standard") {
     this.warnings = [];
     return this.doGenerate({
       agentsDir,
       manifest,
       features: manifest.features,
-      projectRoot: dirname4(agentsDir)
+      projectRoot: dirname4(agentsDir),
+      generationMode
     });
   }
   /**
@@ -1915,8 +1966,19 @@ var BaseAdapter = class {
     const outputs = await this.generate(agentsDir, manifest);
     return outputs.map((o) => o.path);
   }
-  async bridgeHeader(agentsDir, agentsPath = "/.agents/AGENTS.md") {
-    const orchestration = await generateBridgeOrchestration(agentsDir);
+  async bridgeHeader(ctx, agentsPath = "/.agents/AGENTS.md") {
+    const orchestration = await generateBridgeOrchestration(ctx.agentsDir);
+    if (this.isMinimal(ctx)) {
+      return [
+        "",
+        "# Hatch3r Agent Instructions",
+        "",
+        `Instructions: \`${agentsPath}\``,
+        "",
+        this.stripMinimal(orchestration),
+        ""
+      ];
+    }
     return [
       "",
       "# Hatch3r Agent Instructions",
@@ -1931,12 +1993,17 @@ var BaseAdapter = class {
     if (!ctx.features.rules) return [];
     const lines = [];
     const rules = await readCanonicalFiles(ctx.agentsDir, "rules");
+    const minimal = this.isMinimal(ctx);
     for (const rule of rules) {
       const { content, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, rule);
       this.warnings.push(...warnings);
       if (skip) continue;
       const desc = overrides.description ?? rule.description;
-      lines.push(`## ${rule.id}`, "", desc, "", content, "");
+      if (minimal) {
+        lines.push(`## ${rule.id}`, "", this.stripMinimal(content), "");
+      } else {
+        lines.push(`## ${rule.id}`, "", desc, "", content, "");
+      }
     }
     return lines;
   }
@@ -1944,6 +2011,7 @@ var BaseAdapter = class {
     if (!ctx.features.agents) return [];
     const lines = [];
     const agents = await readCanonicalFiles(ctx.agentsDir, "agents");
+    const minimal = this.isMinimal(ctx);
     for (const agent of agents) {
       const { content, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, agent);
       this.warnings.push(...warnings);
@@ -1953,7 +2021,11 @@ var BaseAdapter = class {
       const fmt = model ? (formatModel ?? defaultModelFormat)(model) : void 0;
       lines.push(`## Agent: ${agent.id}`);
       if (fmt && !fmt.after) lines.push(fmt.text);
-      lines.push("", desc, "", content);
+      if (minimal) {
+        lines.push("", this.stripMinimal(content));
+      } else {
+        lines.push("", desc, "", content);
+      }
       if (fmt?.after) lines.push("", fmt.text);
       lines.push("");
     }
@@ -2036,6 +2108,23 @@ ${wrapInManagedBlock(content)}`, content));
     if (!ctx.features.hooks) return [];
     return readHookDefinitions(ctx.agentsDir);
   }
+  /** Returns true when the adapter is running in minimal generation mode. */
+  isMinimal(ctx) {
+    return ctx.generationMode === "minimal";
+  }
+  /**
+   * Strip verbose content for minimal generation mode.
+   * Removes markdown comments, collapses excessive blank lines,
+   * strips decorative formatting, and trims descriptions.
+   */
+  stripMinimal(content) {
+    let result = content;
+    result = result.replace(/<!--[\s\S]*?-->/g, "");
+    result = result.replace(/^[-*_]{3,}\s*$/gm, "");
+    result = result.replace(/\n{3,}/g, "\n\n");
+    result = result.trim();
+    return result;
+  }
 };
 
 // src/adapters/aider.ts
@@ -2043,7 +2132,7 @@ var AiderAdapter = class extends BaseAdapter {
   name = "aider";
   async doGenerate(ctx) {
     const inner = [
-      ...await this.bridgeHeader(ctx.agentsDir),
+      ...await this.bridgeHeader(ctx),
       ...await this.inlineRules(ctx),
       ...await this.inlineAgents(ctx)
     ].join("\n");
@@ -2071,7 +2160,7 @@ var AmazonQAdapter = class extends BaseAdapter {
   async doGenerate(ctx) {
     const results = [];
     const inner = [
-      ...await this.bridgeHeader(ctx.agentsDir),
+      ...await this.bridgeHeader(ctx),
       ...await this.inlineRules(ctx),
       ...await this.inlineAgents(ctx)
     ].join("\n");
@@ -2083,7 +2172,7 @@ var AmazonQAdapter = class extends BaseAdapter {
     if (mcp && Object.keys(mcp).length > 0) {
       const entries = this.buildStdMcpEntries(mcp);
       if (Object.keys(entries).length > 0) {
-        results.push(output(".amazonq/settings.json", JSON.stringify({ mcpServers: entries }, null, 2)));
+        results.push(output(".amazonq/mcp.json", JSON.stringify({ mcpServers: entries }, null, 2)));
       }
     }
     return results;
@@ -2096,15 +2185,15 @@ var AmpAdapter = class extends BaseAdapter {
   async doGenerate(ctx) {
     const results = [];
     const inner = [
-      ...await this.bridgeHeader(ctx.agentsDir),
+      ...await this.bridgeHeader(ctx),
       ...await this.inlineRules(ctx),
       ...await this.inlineAgents(ctx, (m) => ({
         text: `**Recommended model:** \`${m}\`. Use Smart mode for Opus, Rush for Haiku, Deep for Codex.`
       }))
     ].join("\n");
-    results.push(output(".amp/AGENTS.md", wrapInManagedBlock(inner), inner));
+    results.push(output("AGENTS.md", wrapInManagedBlock(inner), inner));
     results.push(
-      ...await this.processSkillsRaw(ctx, (id) => `.amp/skills/${toPrefixedId(id)}/SKILL.md`)
+      ...await this.processSkillsRaw(ctx, (id) => `.agents/skills/${toPrefixedId(id)}/SKILL.md`)
     );
     const mcp = await this.readFilteredMcp(ctx);
     if (mcp && Object.keys(mcp).length > 0) {
@@ -2117,22 +2206,55 @@ var AmpAdapter = class extends BaseAdapter {
   }
 };
 
+// src/adapters/antigravity.ts
+var AntigravityAdapter = class extends BaseAdapter {
+  name = "antigravity";
+  async doGenerate(ctx) {
+    const results = [];
+    const inner = [
+      ...await this.bridgeHeader(ctx, ".agents/AGENTS.md"),
+      ...await this.inlineRules(ctx),
+      ...await this.inlineAgents(ctx)
+    ].join("\n");
+    results.push(output(".antigravity/rules.md", wrapInManagedBlock(inner), inner));
+    results.push(
+      ...await this.processSkillsRaw(ctx, (id) => `.antigravity/skills/${toPrefixedId(id)}/SKILL.md`)
+    );
+    const mcp = await this.readFilteredMcp(ctx);
+    if (mcp && Object.keys(mcp).length > 0) {
+      const entries = this.buildStdMcpEntries(mcp);
+      if (Object.keys(entries).length > 0) {
+        results.push(output(".antigravity/settings.json", JSON.stringify({ mcpServers: entries }, null, 2)));
+      }
+    }
+    return results;
+  }
+};
+
 // src/adapters/claude.ts
 var AGENT_TEAMS_SECTION = [
-  "## Agent Teams (Experimental)",
+  "## Agent Teams",
   "",
-  "This project uses hatch3r's 4-phase sub-agent pipeline (Research \u2192 Implement \u2192 Review \u2192 Quality)",
+  "This project uses hatch3r's 4-phase sub-agent pipeline (Research -> Implement -> Review -> Quality)",
   "which maps directly to Claude Code Agent Teams. Each phase becomes a teammate role.",
   "",
   "### Enabling Agent Teams",
   "",
-  "Agent Teams is experimental. Enable by setting `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your",
-  "environment or in `.claude/settings.json` under `env`. Once enabled, request a team in the prompt:",
+  "Agent Teams is enabled via `.claude/settings.json`. The env var `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`",
+  "is set automatically by hatch3r. Once enabled, request a team in the prompt:",
   "",
   "```",
   "Create an agent team for this task. Use the hatch3r 4-phase pipeline.",
   "```",
   "",
+  "### Teammate Display Modes",
+  "",
+  "Agent Teams supports two display modes configured via `teammateMode` in `.claude/settings.json`:",
+  "",
+  '- `"auto"` (default): uses split panes if inside tmux, in-process otherwise.',
+  '- `"in-process"`: all teammates run inside your main terminal. Use Shift+Down to cycle.',
+  '- `"tmux"`: each teammate gets its own pane. Requires tmux or iTerm2.',
+  "",
   "### Pipeline-to-Team Mapping",
   "",
   "| Phase | Teammate Role | hatch3r Agents | Delegation Notes |",
@@ -2183,6 +2305,20 @@ var AGENT_TEAMS_SECTION = [
   "- Assign explicit file boundaries to avoid edit conflicts between teammates.",
   "- Use the `hatch3r-agent-team` command (`/hatch3r-agent-team`) for guided team creation."
 ];
+var AGENT_TEAMS_SECTION_MINIMAL = [
+  "## Agent Teams",
+  "",
+  "Pipeline maps to Claude Code Agent Teams. Enable via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.",
+  "",
+  "| Phase | Role | Agents |",
+  "|-------|------|--------|",
+  "| Research | `researcher` | `hatch3r-researcher` |",
+  "| Implement | `implementer` | `hatch3r-implementer` |",
+  "| Review | `reviewer` | `hatch3r-reviewer`, `hatch3r-fixer` |",
+  "| Quality | `quality-*` | `hatch3r-test-writer`, `hatch3r-security-auditor`, + conditional |",
+  "",
+  "Use `/hatch3r-agent-team` for guided team creation."
+];
 var AGENT_TEAM_COMMAND = `# hatch3r Agent Team
 
 Create a Claude Code Agent Team that follows the hatch3r 4-phase pipeline.
@@ -2237,7 +2373,8 @@ Each quality teammate owns distinct files to avoid conflicts.
 
 ## Important
 
-- Use \`--teammate-mode tmux\` or \`--teammate-mode in-process\` based on your terminal
+- Teammate display mode is configured in \`.claude/settings.json\` via \`teammateMode\` (\`auto\`, \`in-process\`, or \`tmux\`)
+- Override for a single session: \`claude --teammate-mode in-process\`
 - Each teammate reads CLAUDE.md and inherits project rules automatically
 - Assign explicit file/directory boundaries to each teammate
 - The lead coordinates; it should NOT implement code itself (use delegate mode)
@@ -2288,8 +2425,20 @@ var ClaudeAdapter = class extends BaseAdapter {
   name = "claude";
   async doGenerate(ctx) {
     const results = [];
+    const minimal = this.isMinimal(ctx);
     const bridgeOrchestration = await generateBridgeOrchestration(ctx.agentsDir);
-    const innerContent = [
+    const teamsSection = minimal ? AGENT_TEAMS_SECTION_MINIMAL : AGENT_TEAMS_SECTION;
+    const innerParts = minimal ? [
+      "",
+      "# Hatch3r Project Instructions",
+      "",
+      "Instructions: `.agents/AGENTS.md`. Rules: `.claude/rules/`. Agents: `.claude/agents/`.",
+      "",
+      this.stripMinimal(bridgeOrchestration),
+      "",
+      ...teamsSection,
+      ""
+    ] : [
       "",
       "# Hatch3r Project Instructions",
       "",
@@ -2298,14 +2447,24 @@ var ClaudeAdapter = class extends BaseAdapter {
       "",
       bridgeOrchestration,
       "",
-      ...AGENT_TEAMS_SECTION,
+      ...teamsSection,
       "",
       "## Personal Settings",
       "",
       "Create `CLAUDE.local.md` for personal settings (not committed to git).",
       "Claude Code reads this file for user-specific preferences.",
+      "",
+      "## Getting Started with Claude Code",
+      "",
+      "New to this project's agent setup? Progress through these stages:",
+      "",
+      "**Start here:** Rules in `.claude/rules/` are loaded automatically. The orchestration bridge above guides your workflow.",
+      "**Next:** Use `/hatch3r-feature` or `/hatch3r-bug-fix` commands for guided workflows.",
+      "**Then:** Delegate to agents in `.claude/agents/` \u2014 use Agent Teams for parallel execution.",
+      "**Later:** Customize agent behavior via `.hatch3r/{type}/{id}.customize.yaml` without editing managed files.",
       ""
-    ].join("\n");
+    ];
+    const innerContent = innerParts.join("\n");
     results.push(output("CLAUDE.md", wrapInManagedBlock(innerContent), innerContent));
     if (ctx.features.rules) {
       const rules = await readCanonicalFiles(ctx.agentsDir, "rules");
@@ -2314,7 +2473,9 @@ var ClaudeAdapter = class extends BaseAdapter {
         this.warnings.push(...warnings);
         if (skip) continue;
         const desc = overrides.description ?? rule.description;
-        const body = `# ${rule.id}
+        const body = minimal ? `# ${rule.id}
+
+${this.stripMinimal(content)}` : `# ${rule.id}
 
 ${desc}
 
@@ -2330,23 +2491,33 @@ ${content}`;
         if (skip) continue;
         const agentId = toPrefixedId(agent.id);
         const model = resolveAgentModel(agent.id, agent, ctx.manifest, overrides);
-        const modelGuidance = model ? `
-
-## Recommended Model
-
-Preferred: \`${model}\`. Set via \`/model ${model}\` or env \`CLAUDE_CODE_SUBAGENT_MODEL=${model}\`.` : "";
         const desc = overrides.description ?? agent.description;
         const fm = `---
 description: ${desc}
 ---`;
-        const body = `${content}${modelGuidance}`;
-        results.push(output(`.claude/agents/${agentId}.md`, `${fm}
+        if (minimal) {
+          const modelNote = model ? `
+Model: \`${model}\`` : "";
+          const body = `${this.stripMinimal(content)}${modelNote}`;
+          results.push(output(`.claude/agents/${agentId}.md`, `${fm}
+
+${wrapInManagedBlock(body)}`, body));
+        } else {
+          const modelGuidance = model ? `
+
+## Recommended Model
+
+Preferred: \`${model}\`. Set via \`/model ${model}\` or env \`CLAUDE_CODE_SUBAGENT_MODEL=${model}\`.` : "";
+          const body = `${content}${modelGuidance}`;
+          results.push(output(`.claude/agents/${agentId}.md`, `${fm}
 
 ${wrapInManagedBlock(body)}`, body));
+        }
       }
     }
     const defaultAllow = ["Read", "Edit", "MultiEdit", "Write", "Grep", "Glob", "LS", "TodoRead", "TodoWrite"];
     const claudeConfig = ctx.manifest.claude;
+    const teammateMode = claudeConfig?.teammateMode ?? "auto";
     const settingsObj = {
       _hatch3r: {
         version: HATCH3R_VERSION,
@@ -2356,7 +2527,7 @@ ${wrapInManagedBlock(body)}`, body));
         allow: claudeConfig?.permissions?.allow ?? defaultAllow,
         deny: claudeConfig?.permissions?.deny ?? []
       },
-      teammateMode: claudeConfig?.teammateMode ?? "tool-using"
+      teammateMode
     };
     const hooksConfig = {};
     const hooks = await this.readHooks(ctx);
@@ -2387,7 +2558,9 @@ ${wrapInManagedBlock(body)}`, body));
       });
     }
     settingsObj.hooks = hooksConfig;
-    if (ctx.manifest.claude?.agentTeams !== false) {
+    const agentTeamsSetting = ctx.manifest.claude?.agentTeams;
+    if (agentTeamsSetting === "ga") {
+    } else if (agentTeamsSetting !== false) {
       settingsObj.env = { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1" };
     }
     results.push(output(".claude/settings.json", JSON.stringify(settingsObj, null, 2)));
@@ -2509,7 +2682,16 @@ ${content}`;
       "Canonical agent instructions live at `/.agents/AGENTS.md`.",
       "Rules and skills are managed in `.roo/rules/` and `.cline/skills/`.",
       "",
-      bridgeOrchestration
+      bridgeOrchestration,
+      "",
+      "## Getting Started with Roo Code",
+      "",
+      "New to this project's agent setup? Progress through these stages:",
+      "",
+      "**Start here:** Rules in `.roo/rules/` are loaded automatically. The orchestration bridge above guides your workflow.",
+      "**Next:** Use workflow commands in `.clinerules/workflows/` for guided task execution.",
+      "**Then:** Switch to custom modes (defined in `.roomodes`) for specialized agent behaviors.",
+      "**Later:** Customize agent behavior via `.hatch3r/{type}/{id}.customize.yaml` without editing managed files."
     ].join("\n");
     results.push(output(".roo/rules/hatch3r-bridge.md", wrapInManagedBlock(bridgeBody), bridgeBody));
     return results;
@@ -2660,6 +2842,15 @@ ${r.rule.description}
 
 ${r.content}`
       ),
+      "",
+      "## Getting Started with Copilot",
+      "",
+      "New to this project's agent setup? Progress through these stages:",
+      "",
+      "**Start here:** Instructions in `.github/instructions/` scope rules to specific file patterns. The orchestration bridge above guides your workflow.",
+      "**Next:** Use prompts in `.github/prompts/` and commands in `.github/copilot/commands/` for guided workflows.",
+      "**Then:** Delegate to agents in `.github/agents/` for specialized tasks.",
+      "**Later:** Customize agent behavior via `.hatch3r/{type}/{id}.customize.yaml` without editing managed files.",
       ""
     ].join("\n");
     results.push(output(".github/copilot-instructions.md", wrapInManagedBlock(innerContent), innerContent));
@@ -2806,7 +2997,7 @@ var CursorAdapter = class extends BaseAdapter {
         const lines = [`name: ${agent.id}`, `description: ${desc}`];
         if (model) lines.push(`model: ${model}`);
         if (agent.readonly) lines.push("readonly: true");
-        if (agent.background) lines.push("background: true");
+        if (agent.background) lines.push("is_background: true");
         const fm = `---
 ${lines.join("\n")}
 ---`;
@@ -2867,7 +3058,16 @@ Background subagents write output to \`~/.cursor/subagents/\` for later inspecti
 
 Cursor v2.6 added MCP Apps (interactive UIs in agent chats) and Team Marketplaces for plugins.
 If this project includes MCP servers that expose UI components, they will render inline as MCP Apps.
-Plugin configurations in \`.cursor/mcp.json\` are compatible with Team Marketplace distribution.`;
+Plugin configurations in \`.cursor/mcp.json\` are compatible with Team Marketplace distribution.
+
+## Getting Started with Cursor
+
+New to this project's agent setup? Progress through these stages:
+
+**Start here:** Rules in \`.cursor/rules/\` are loaded automatically. The orchestration bridge above guides your workflow.
+**Next:** Use \`/hatch3r-feature\` or \`/hatch3r-bug-fix\` commands in Cursor chat for guided workflows.
+**Then:** Delegate to agents in \`.cursor/agents/\` \u2014 Cursor supports up to 4 subagents in parallel.
+**Later:** Customize agent behavior via \`.hatch3r/{type}/{id}.customize.yaml\` without editing managed files.`;
     results.push(mdcOutput(".cursor/rules/hatch3r-bridge.mdc", bridgeFm, bridgeBody));
     if (ctx.manifest.tools.includes("cursor")) {
       const envConfig = {
@@ -2899,7 +3099,7 @@ var GeminiAdapter = class extends BaseAdapter {
   async doGenerate(ctx) {
     const results = [];
     const inner = [
-      ...await this.bridgeHeader(ctx.agentsDir, ".agents/AGENTS.md"),
+      ...await this.bridgeHeader(ctx, ".agents/AGENTS.md"),
       ...await this.inlineRules(ctx),
       ...await this.inlineAgents(ctx, (m) => ({
         text: `**Recommended model:** \`${m}\`. Set via \`gemini --model ${m}\` or select in Google AI Studio.`,
@@ -2958,11 +3158,12 @@ var GeminiAdapter = class extends BaseAdapter {
 };
 
 // src/adapters/goose.ts
+import { stringify as yamlStringify } from "yaml";
 var GooseAdapter = class extends BaseAdapter {
   name = "goose";
   async doGenerate(ctx) {
     const lines = [
-      ...await this.bridgeHeader(ctx.agentsDir),
+      ...await this.bridgeHeader(ctx),
       ...await this.inlineRules(ctx),
       ...await this.inlineAgents(ctx)
     ];
@@ -2988,8 +3189,108 @@ var GooseAdapter = class extends BaseAdapter {
         results.push(output(".goose/mcp.json", JSON.stringify(gooseMcp, null, 2)));
       }
     }
+    const agents = ctx.features.agents ? await readCanonicalFiles(ctx.agentsDir, "agents") : [];
+    const profile = await this.buildProfile(ctx, agents, mcp);
+    const profileYaml = yamlStringify(profile);
+    results.push(output(".goose/profiles/hatch3r.yaml", profileYaml));
     return results;
   }
+  /** Build a Goose profile that maps hatch3r content to Goose's recipe system. */
+  async buildProfile(ctx, agents, mcp) {
+    const extensions = this.buildExtensions(mcp);
+    const recipe = await this.buildRecipe(ctx, agents);
+    const capabilities = this.deriveAcpCapabilities(ctx, agents);
+    return {
+      name: "hatch3r",
+      description: `hatch3r-managed Goose profile for ${ctx.manifest.project || ctx.manifest.repo}. Provides agent pipeline, recipe interoperability, and ACP compatibility.`,
+      instructions: `Follow the canonical agent instructions at .agents/AGENTS.md. Use the hatch3r 4-phase pipeline: Research, Implement, Review, Quality.`,
+      ...extensions.length > 0 ? { extensions } : {},
+      recipes: [recipe],
+      acp: {
+        enabled: true,
+        version: "0.2",
+        capabilities
+      }
+    };
+  }
+  /** Map MCP servers to Goose extensions. */
+  buildExtensions(mcp) {
+    if (!mcp) return [];
+    const extensions = [];
+    for (const [name, entry] of Object.entries(mcp)) {
+      if (entry.command) {
+        extensions.push({
+          name,
+          type: "mcp",
+          config: {
+            command: entry.command,
+            args: entry.args || [],
+            ...entry.env && Object.keys(entry.env).length > 0 ? { env: entry.env } : {}
+          }
+        });
+      } else if (entry.url) {
+        extensions.push({
+          name,
+          type: "mcp",
+          config: { url: entry.url }
+        });
+      }
+    }
+    return extensions;
+  }
+  /** Build a Goose recipe from hatch3r's agent pipeline. */
+  async buildRecipe(ctx, agents) {
+    const steps = [];
+    const phaseMap = [
+      { phase: "Research", agentPattern: "researcher", fallback: "Gather context from the codebase. Identify affected files, patterns, and conventions. Do not modify any files." },
+      { phase: "Implement", agentPattern: "implementer", fallback: "Implement the requested changes following project conventions. Require plan approval before making changes." },
+      { phase: "Review", agentPattern: "reviewer", fallback: "Review all changes for correctness, style, security, and adherence to project rules. Report findings as Critical/Warning/Info." },
+      { phase: "Quality", agentPattern: "test-writer", fallback: "Write or update tests for the implemented changes. Run the test suite and verify all tests pass." }
+    ];
+    for (const { phase, agentPattern, fallback } of phaseMap) {
+      const matchingAgent = agents.find(
+        (a) => a.id.includes(agentPattern)
+      );
+      if (matchingAgent) {
+        const { skip, warnings } = await applyCustomization(ctx.projectRoot, matchingAgent);
+        this.warnings.push(...warnings);
+        if (!skip) {
+          const instruction = matchingAgent.description || fallback;
+          steps.push({
+            instruction: `[${phase}] ${instruction}`,
+            agent: toPrefixedId(matchingAgent.id)
+          });
+          continue;
+        }
+      }
+      steps.push({ instruction: `[${phase}] ${fallback}` });
+    }
+    return {
+      name: "hatch3r-pipeline",
+      description: "hatch3r 4-phase development pipeline: Research, Implement, Review, Quality.",
+      steps
+    };
+  }
+  /** Derive ACP capability advertisements from project configuration. */
+  deriveAcpCapabilities(ctx, agents) {
+    const capabilities = [
+      "code-generation",
+      "code-review"
+    ];
+    if (agents.some((a) => a.id.includes("test"))) {
+      capabilities.push("test-generation");
+    }
+    if (agents.some((a) => a.id.includes("security"))) {
+      capabilities.push("security-audit");
+    }
+    if (agents.some((a) => a.id.includes("docs"))) {
+      capabilities.push("documentation");
+    }
+    if (ctx.features.mcp) {
+      capabilities.push("tool-use");
+    }
+    return capabilities;
+  }
 };
 
 // src/adapters/kiro.ts
@@ -3006,7 +3307,7 @@ var KiroAdapter = class extends BaseAdapter {
   name = "kiro";
   async doGenerate(ctx) {
     const results = [];
-    const lines = [...await this.bridgeHeader(ctx.agentsDir)];
+    const lines = [...await this.bridgeHeader(ctx)];
     if (ctx.features.rules) {
       const rules = await readCanonicalFiles(ctx.agentsDir, "rules");
       for (const rule of rules) {
@@ -3139,7 +3440,7 @@ function isGlobPattern(scope) {
 function ruleTrigger(scope) {
   if (!scope) return "model_decision";
   if (scope === "always") return "always_on";
-  return "glob_pattern";
+  return "glob";
 }
 var WindsurfAdapter = class extends BaseAdapter {
   name = "windsurf";
@@ -3155,7 +3456,17 @@ var WindsurfAdapter = class extends BaseAdapter {
       "",
       bridgeOrchestration,
       "",
-      ...await this.inlineAgents(ctx)
+      ...await this.inlineAgents(ctx),
+      "",
+      "## Getting Started with Windsurf",
+      "",
+      "New to this project's agent setup? Progress through these stages:",
+      "",
+      "**Start here:** Rules in `.windsurf/rules/` are loaded automatically. The orchestration bridge above guides your workflow.",
+      "**Next:** Use commands in `.windsurf/workflows/` for guided workflows (e.g., feature development, bug fixes).",
+      "**Then:** Use parallel Cascade sessions for independent tasks to maximize throughput.",
+      "**Later:** Customize agent behavior via `.hatch3r/{type}/{id}.customize.yaml` without editing managed files.",
+      ""
     ].join("\n");
     results.push(output(".windsurfrules", wrapInManagedBlock(windsurfInner), windsurfInner));
     if (ctx.features.rules) {
@@ -3166,7 +3477,7 @@ var WindsurfAdapter = class extends BaseAdapter {
         if (skip) continue;
         const scope = overrides.scope ?? rule.scope;
         const trigger = ruleTrigger(scope);
-        const globScope = trigger === "glob_pattern" && scope ? isGlobPattern(scope) ? scope : `${scope}/**` : void 0;
+        const globScope = trigger === "glob" && scope ? isGlobPattern(scope) ? scope : `${scope}/**` : void 0;
         const fm = `---
 trigger: ${trigger}${globScope ? `
 globs: "${globScope}"` : ""}
@@ -3204,7 +3515,7 @@ var ZedAdapter = class extends BaseAdapter {
   name = "zed";
   async doGenerate(ctx) {
     const inner = [
-      ...await this.bridgeHeader(ctx.agentsDir),
+      ...await this.bridgeHeader(ctx),
       ...await this.inlineRules(ctx),
       ...await this.inlineAgents(ctx)
     ].join("\n");
@@ -3227,7 +3538,8 @@ var adapters = {
   kiro: new KiroAdapter(),
   goose: new GooseAdapter(),
   zed: new ZedAdapter(),
-  "amazon-q": new AmazonQAdapter()
+  "amazon-q": new AmazonQAdapter(),
+  antigravity: new AntigravityAdapter()
 };
 function getAdapter(tool) {
   const adapter = adapters[tool];
@@ -3250,7 +3562,8 @@ var ADAPTER_CAPABILITIES = {
   kiro: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false },
   aider: { agents: true, skills: true, rules: true, hooks: false, mcp: false, commands: false, prompts: false, githubAgents: false },
   goose: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false },
-  zed: { agents: true, skills: false, rules: true, hooks: false, mcp: false, commands: false, prompts: false, githubAgents: false }
+  zed: { agents: true, skills: false, rules: true, hooks: false, mcp: false, commands: false, prompts: false, githubAgents: false },
+  antigravity: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false }
 };
 function getUnsupportedFeatureWarnings(tool, manifest) {
   const caps = ADAPTER_CAPABILITIES[tool];
@@ -3349,7 +3662,7 @@ function validateIntegrityManifest(data) {
   for (const val of Object.values(obj.files)) {
     if (typeof val !== "string") return false;
   }
-  if ("checksum" in obj && typeof obj.checksum !== "string") return false;
+  if (typeof obj.checksum !== "string") return false;
   return true;
 }
 async function readIntegrityManifest(agentsDir) {
@@ -3370,12 +3683,10 @@ async function verifyIntegrity(agentsDir) {
     return [];
   }
   const results = [];
-  if (manifest.checksum !== void 0) {
-    const expected = createHash("sha256").update(JSON.stringify(manifest.files)).digest("hex");
-    if (manifest.checksum !== expected) {
-      results.push({ file: INTEGRITY_FILE, status: "tampered" });
-      return results;
-    }
+  const expected = createHash("sha256").update(JSON.stringify(manifest.files)).digest("hex");
+  if (manifest.checksum !== expected) {
+    results.push({ file: INTEGRITY_FILE, status: "tampered" });
+    return results;
   }
   const manifestFiles = new Set(Object.keys(manifest.files));
   for (const [filePath, expectedHash] of Object.entries(manifest.files)) {
@@ -3423,52 +3734,248 @@ async function verifyIntegrity(agentsDir) {
   return results;
 }
 
-// src/content/index.ts
-import { readFile as readFile12, readdir as readdir5, cp, mkdir as mkdir3, rm } from "fs/promises";
-import { join as join14, dirname as dirname6, normalize, isAbsolute } from "path";
-function assertSafePath(relativePath, label2) {
-  const normalized = normalize(relativePath);
-  if (normalized.startsWith("..") || isAbsolute(normalized)) {
-    throw new HatchError(`Unsafe path detected in ${label2}: ${relativePath}`, 1);
+// src/archive/index.ts
+import { access as access3, cp, mkdir as mkdir3, readFile as readFile12, readdir as readdir5, rm, stat, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname6, join as join14, sep } from "path";
+function toPosixPath(p) {
+  return sep === "\\" ? p.replaceAll("\\", "/") : p;
+}
+var ARCHIVE_DIR = ".hatch3r-archive";
+var TOOL_PATH_PREFIXES = {
+  cursor: [".cursor/"],
+  claude: [".claude/", "CLAUDE.md", ".mcp.json"],
+  copilot: [".github/copilot-instructions.md", ".github/workflows/copilot-setup-steps.yml", ".vscode/mcp.json"],
+  windsurf: [".windsurf/", ".windsurfrules"],
+  amp: [".amp/"],
+  codex: [".codex/"],
+  gemini: [".gemini/", "GEMINI.md"],
+  cline: [".roo/", ".roomodes"],
+  aider: ["CONVENTIONS.md", ".aider.conf.yml"],
+  kiro: [".kiro/"],
+  opencode: ["opencode.json"],
+  goose: [".goosehints"],
+  zed: [".rules"],
+  "amazon-q": [".amazonq/"],
+  antigravity: [".antigravity/"]
+};
+var PATH_PATTERNS = [
+  { pattern: /\/rules\/([^/]+)\.(mdc|md)$/, type: "rules" },
+  { pattern: /\/agents\/([^/]+)\.md$/, type: "agents" },
+  { pattern: /\/skills\/([^/]+)\/SKILL\.md$/, type: "skills" },
+  { pattern: /\/commands\/([^/]+)\.md$/, type: "commands" }
+];
+function parseOutputPath(filePath) {
+  for (const { pattern, type } of PATH_PATTERNS) {
+    const match = filePath.match(pattern);
+    if (match) {
+      let id = match[1];
+      if (id.startsWith(HATCH3R_PREFIX)) {
+        id = id.slice(HATCH3R_PREFIX.length);
+      }
+      id = sanitizeId(id);
+      if (id.length > 0) return { type, id };
+    }
   }
+  return null;
 }
-function extractContentReferences(content) {
-  const refs = /* @__PURE__ */ new Set();
-  const pattern = /`(hatch3r-[a-z0-9-]+)`/g;
-  let match;
-  while ((match = pattern.exec(content)) !== null) {
-    refs.add(match[1]);
+function stripFrontmatter(content) {
+  const trimmed = content.trimStart();
+  if (trimmed.startsWith("---")) {
+    const endIdx = trimmed.indexOf("\n---", 3);
+    if (endIdx !== -1) {
+      return trimmed.slice(endIdx + 4).trim();
+    }
   }
-  return [...refs];
+  return content.trim();
 }
-async function validateCrossReferences(contentRoot, index) {
-  const warnings = [];
-  const allIds = new Set(index.items.map((item) => item.id));
-  for (const item of index.items) {
+async function fileExists2(path) {
+  try {
+    await access3(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function collectToolFiles(rootDir, tool) {
+  const prefixes = TOOL_PATH_PREFIXES[tool];
+  if (!prefixes) return [];
+  const files = [];
+  for (const prefix of prefixes) {
+    const absPath = join14(rootDir, prefix);
+    if (prefix.endsWith("/")) {
+      try {
+        const entries = await readdir5(absPath, { recursive: true, withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isFile()) {
+            const parent = entry.parentPath ?? entry.path ?? absPath;
+            const relPath = toPosixPath(join14(prefix, parent.slice(absPath.length), entry.name));
+            files.push(relPath);
+          }
+        }
+      } catch {
+      }
+    } else if (await fileExists2(absPath)) {
+      files.push(prefix);
+    }
+  }
+  return files;
+}
+async function archiveToolOutputs(rootDir, tool) {
+  const filesToArchive = await collectToolFiles(rootDir, tool);
+  if (filesToArchive.length === 0) {
+    return { archivedFiles: [], migrations: [] };
+  }
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const archiveBase = join14(rootDir, ARCHIVE_DIR, tool, timestamp);
+  const archivedFiles = [];
+  const migrations = [];
+  for (const relPath of filesToArchive) {
+    const absPath = join14(rootDir, relPath);
+    if (!await fileExists2(absPath)) continue;
     let content;
     try {
-      const filePath = item.type === "skill" ? join14(contentRoot, item.relativePath, "SKILL.md") : join14(contentRoot, `${item.relativePath}`);
-      content = await readFile12(filePath, "utf-8");
+      content = await readFile12(absPath, "utf-8");
     } catch {
       continue;
     }
-    const refs = extractContentReferences(content);
-    for (const ref of refs) {
-      if (ref === item.id) continue;
-      if (!allIds.has(ref)) {
-        warnings.push(
-          `${item.type} "${item.id}" references "${ref}" which does not exist in the content index`
-        );
+    if (hasManagedBlock(content)) {
+      const customContent = stripFrontmatter(extractCustomContent(content));
+      if (customContent.length > 0) {
+        const parsed = parseOutputPath(relPath);
+        if (parsed) {
+          const customizePath = join14(rootDir, ".hatch3r", parsed.type, `${parsed.id}.customize.md`);
+          if (!await fileExists2(customizePath)) {
+            await mkdir3(dirname6(customizePath), { recursive: true });
+            await writeFile3(customizePath, customContent + "\n", "utf-8");
+            migrations.push({
+              from: relPath,
+              to: `.hatch3r/${parsed.type}/${parsed.id}.customize.md`,
+              type: parsed.type,
+              id: parsed.id
+            });
+          }
+        }
       }
     }
+    const archiveDest = join14(archiveBase, relPath);
+    await mkdir3(dirname6(archiveDest), { recursive: true });
+    await cp(absPath, archiveDest);
+    const srcStat = await stat(absPath);
+    const destStat = await stat(archiveDest);
+    if (destStat.size !== srcStat.size) {
+      throw new Error(`Archive copy size mismatch for ${relPath}: source=${srcStat.size}, dest=${destStat.size}`);
+    }
+    await rm(absPath);
+    archivedFiles.push(relPath);
   }
-  return { warnings };
+  await cleanEmptyDirs(rootDir, filesToArchive);
+  return { archivedFiles, migrations };
 }
-var ORCHESTRATION_REQUIRED_AGENTS = [
-  "hatch3r-researcher",
-  "hatch3r-implementer",
-  "hatch3r-reviewer",
-  "hatch3r-test-writer",
+async function cleanEmptyDirs(rootDir, paths) {
+  const dirs = /* @__PURE__ */ new Set();
+  for (const p of paths) {
+    let dir = dirname6(join14(rootDir, p));
+    while (dir !== rootDir && dir.length > rootDir.length) {
+      dirs.add(dir);
+      dir = dirname6(dir);
+    }
+  }
+  const sorted = [...dirs].sort((a, b) => b.length - a.length);
+  for (const dir of sorted) {
+    try {
+      const entries = await readdir5(dir);
+      if (entries.length === 0) {
+        await rm(dir, { recursive: true });
+      }
+    } catch {
+    }
+  }
+}
+function removeManagedFilesForPaths(manifest, paths) {
+  const pathSet = new Set(paths);
+  manifest.managedFiles = manifest.managedFiles.filter((f) => !pathSet.has(f));
+}
+var MAX_ARCHIVE_ENTRIES = 5;
+async function pruneArchives(rootDir) {
+  const archiveRoot = join14(rootDir, ARCHIVE_DIR);
+  const pruned = [];
+  let toolDirs;
+  try {
+    toolDirs = await readdir5(archiveRoot);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+  for (const toolDir of toolDirs) {
+    const toolPath = join14(archiveRoot, toolDir);
+    let entries;
+    try {
+      const s = await stat(toolPath);
+      if (!s.isDirectory()) continue;
+      entries = await readdir5(toolPath);
+    } catch {
+      continue;
+    }
+    entries.sort((a, b) => b.localeCompare(a));
+    for (const entry of entries.slice(MAX_ARCHIVE_ENTRIES)) {
+      const entryPath = join14(toolPath, entry);
+      await rm(entryPath, { recursive: true, force: true });
+      pruned.push(`${toolDir}/${entry}`);
+    }
+  }
+  return pruned;
+}
+
+// src/content/index.ts
+import { readFile as readFile13, readdir as readdir6, writeFile as writeFile4, cp as cp2, mkdir as mkdir4, rm as rm2 } from "fs/promises";
+import { join as join15, dirname as dirname7, normalize, isAbsolute } from "path";
+function assertSafePath(relativePath, label2) {
+  const sanitized = relativePath.replace(/\0/g, "");
+  const normalized = normalize(sanitized);
+  if (normalized.startsWith("..") || isAbsolute(normalized)) {
+    throw new HatchError(`Unsafe path detected in ${label2}: ${relativePath}`, 1, "FS_ERROR");
+  }
+  if (sanitized !== relativePath) {
+    throw new HatchError(`Unsafe path detected in ${label2}: ${relativePath}`, 1, "FS_ERROR");
+  }
+}
+function extractContentReferences(content) {
+  const refs = /* @__PURE__ */ new Set();
+  const pattern = /`(hatch3r-[a-z0-9-]+)`/g;
+  let match;
+  while ((match = pattern.exec(content)) !== null) {
+    refs.add(match[1]);
+  }
+  return [...refs];
+}
+async function validateCrossReferences(contentRoot, index) {
+  const warnings = [];
+  const allIds = new Set(index.items.map((item) => item.id));
+  for (const item of index.items) {
+    let content;
+    try {
+      const filePath = item.type === "skill" ? join15(contentRoot, item.relativePath, "SKILL.md") : join15(contentRoot, `${item.relativePath}`);
+      content = await readFile13(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+    const refs = extractContentReferences(content);
+    for (const ref of refs) {
+      if (ref === item.id) continue;
+      if (!allIds.has(ref)) {
+        warnings.push(
+          `${item.type} "${item.id}" references "${ref}" which does not exist in the content index`
+        );
+      }
+    }
+  }
+  return { warnings };
+}
+var ORCHESTRATION_REQUIRED_AGENTS = [
+  "hatch3r-researcher",
+  "hatch3r-implementer",
+  "hatch3r-reviewer",
+  "hatch3r-test-writer",
   "hatch3r-security-auditor"
 ];
 function validateOrchestrationDependencies(selection) {
@@ -3485,6 +3992,12 @@ function validateOrchestrationDependencies(selection) {
   }
   return warnings;
 }
+function typeIdKey(type, id) {
+  return `${type}:${id}`;
+}
+function getAllItemsById(index, id) {
+  return index.items.filter((item) => item.id === id);
+}
 var CONTENT_TYPE_CONFIGS = [
   { dir: "agents", type: "agent", strategy: "glob" },
   { dir: "commands", type: "command", strategy: "glob" },
@@ -3497,20 +4010,20 @@ var CONTENT_TYPE_CONFIGS = [
 async function buildContentIndex(contentRoot) {
   const items = [];
   for (const config of CONTENT_TYPE_CONFIGS) {
-    const dirPath = join14(contentRoot, config.dir);
+    const dirPath = join15(contentRoot, config.dir);
     if (config.strategy === "subdirectory") {
       let dirents;
       try {
-        dirents = await readdir5(dirPath, { withFileTypes: true });
+        dirents = (await readdir6(dirPath, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
       } catch (err) {
         if (err.code === "ENOENT") continue;
         throw err;
       }
       for (const dirent of dirents) {
         if (!dirent.isDirectory()) continue;
-        const skillPath = join14(dirPath, dirent.name, "SKILL.md");
+        const skillPath = join15(dirPath, dirent.name, "SKILL.md");
         try {
-          const raw = await readFile12(skillPath, "utf-8");
+          const raw = await readFile13(skillPath, "utf-8");
           const { metadata } = parseFrontmatter(raw);
           const id = metadata.id || metadata.name || dirent.name;
           items.push({
@@ -3519,7 +4032,7 @@ async function buildContentIndex(contentRoot) {
             description: metadata.description ?? "",
             tags: metadata.tags ?? [],
             protected: metadata.protected,
-            relativePath: join14(config.dir, dirent.name)
+            relativePath: join15(config.dir, dirent.name)
           });
         } catch (err) {
           if (err.code !== "ENOENT") throw err;
@@ -3528,15 +4041,15 @@ async function buildContentIndex(contentRoot) {
     } else {
       let entries;
       try {
-        const all = await readdir5(dirPath);
-        entries = all.filter((f) => f.endsWith(".md"));
+        const all = await readdir6(dirPath);
+        entries = all.filter((f) => f.endsWith(".md")).sort();
       } catch (err) {
         if (err.code === "ENOENT") continue;
         throw err;
       }
       for (const file of entries) {
-        const filePath = join14(dirPath, file);
-        const raw = await readFile12(filePath, "utf-8");
+        const filePath = join15(dirPath, file);
+        const raw = await readFile13(filePath, "utf-8");
         const { metadata } = parseFrontmatter(raw);
         const id = metadata.id || metadata.name || file.replace(/\.md$/, "");
         const item = {
@@ -3545,13 +4058,13 @@ async function buildContentIndex(contentRoot) {
           description: metadata.description ?? "",
           tags: metadata.tags ?? [],
           protected: metadata.protected,
-          relativePath: join14(config.dir, file)
+          relativePath: join15(config.dir, file)
         };
         if (config.type === "rule") {
           const mdcFile = file.replace(/\.md$/, ".mdc");
           try {
-            await readFile12(join14(dirPath, mdcFile), "utf-8");
-            item.companionPath = join14(config.dir, mdcFile);
+            await readFile13(join15(dirPath, mdcFile), "utf-8");
+            item.companionPath = join15(config.dir, mdcFile);
           } catch {
           }
         }
@@ -3561,18 +4074,36 @@ async function buildContentIndex(contentRoot) {
   }
   const byType = {};
   const byId = /* @__PURE__ */ new Map();
+  const byTypeAndId = /* @__PURE__ */ new Map();
+  const collisions = [];
   for (const item of items) {
     if (!byType[item.type]) byType[item.type] = [];
     byType[item.type].push(item);
+    byTypeAndId.set(typeIdKey(item.type, item.id), item);
     const existing = byId.get(item.id);
-    if (existing && existing.type !== item.type) {
-      console.warn(
-        `[hatch3r] Content ID collision: "${item.id}" exists as both ${existing.type} and ${item.type}. The ${item.type} entry will shadow the ${existing.type} entry in ID lookups.`
-      );
+    if (existing) {
+      const kind = existing.type !== item.type ? "cross-type" : "same-type";
+      collisions.push({
+        id: item.id,
+        kind,
+        existingType: existing.type,
+        existingPath: existing.relativePath,
+        duplicateType: item.type,
+        duplicatePath: item.relativePath
+      });
+      if (kind === "cross-type") {
+        console.warn(
+          `[hatch3r] Content ID collision: "${item.id}" exists as both ${existing.type} (${existing.relativePath}) and ${item.type} (${item.relativePath}). Use index.byTypeAndId for collision-safe lookup.`
+        );
+      } else {
+        console.warn(
+          `[hatch3r] Duplicate content ID: "${item.id}" found in ${existing.relativePath} and ${item.relativePath}. The later entry will shadow the earlier one in ID lookups.`
+        );
+      }
     }
     byId.set(item.id, item);
   }
-  return { items, byType, byId };
+  return { items, byType, byId, byTypeAndId, collisions };
 }
 var TYPE_TO_SELECTION_KEY = {
   agent: "agents",
@@ -3644,6 +4175,52 @@ function resolveSelection(preset, projectType, teamSize, index, customSelections
     items
   };
 }
+function countPresetExclusions(preset, index) {
+  if (preset.id === "custom") return 0;
+  if (preset.id === "full") return 0;
+  let count = 0;
+  for (const item of index.items) {
+    if (item.protected) continue;
+    if (preset.includeTags.length > 0) {
+      const includeSet = new Set(preset.includeTags);
+      if (item.tags.length > 0 && !item.tags.some((t) => includeSet.has(t))) {
+        count++;
+        continue;
+      }
+    }
+    if (preset.excludeTags.length > 0) {
+      const excludeSet = new Set(preset.excludeTags);
+      if (item.tags.every((t) => excludeSet.has(t))) {
+        count++;
+      }
+    }
+  }
+  return count;
+}
+function countProjectTypeExclusions(projectType, items) {
+  const opposite = projectType === "greenfield" ? "brownfield" : "greenfield";
+  let count = 0;
+  for (const item of items) {
+    if (item.protected) continue;
+    if (item.tags.includes(opposite) && !item.tags.some((t) => t !== opposite && t !== "team" && t !== "solo")) {
+      count++;
+    }
+  }
+  return count;
+}
+function countTeamSizeExclusions(teamSize, items) {
+  if (teamSize !== "solo") return 0;
+  let count = 0;
+  for (const item of items) {
+    if (item.protected) continue;
+    if (!item.tags.includes("team") && !item.tags.includes("board")) continue;
+    const hasOther = item.tags.some(
+      (t) => t !== "team" && t !== "board" && t !== "solo" && t !== "greenfield" && t !== "brownfield"
+    );
+    if (!hasOther) count++;
+  }
+  return count;
+}
 async function copySelectedContent(contentRoot, agentsDir, selection, index) {
   const copied = [];
   const selectedIds = /* @__PURE__ */ new Set();
@@ -3656,21 +4233,21 @@ async function copySelectedContent(contentRoot, agentsDir, selection, index) {
     if (item.companionPath) {
       assertSafePath(item.companionPath, "copySelectedContent companion");
     }
-    const srcPath = join14(contentRoot, item.relativePath);
-    const destPath = join14(agentsDir, item.relativePath);
+    const srcPath = join15(contentRoot, item.relativePath);
+    const destPath = join15(agentsDir, item.relativePath);
     if (item.type === "skill") {
-      await mkdir3(destPath, { recursive: true });
-      await cp(srcPath, destPath, { recursive: true, force: true });
+      await mkdir4(destPath, { recursive: true });
+      await cp2(srcPath, destPath, { recursive: true, force: true });
       copied.push(item.relativePath);
     } else {
-      await mkdir3(dirname6(destPath), { recursive: true });
-      await cp(srcPath, destPath, { force: true });
+      await mkdir4(dirname7(destPath), { recursive: true });
+      await cp2(srcPath, destPath, { force: true });
       copied.push(item.relativePath);
       if (item.companionPath) {
-        const mdcSrc = join14(contentRoot, item.companionPath);
-        const mdcDest = join14(agentsDir, item.companionPath);
+        const mdcSrc = join15(contentRoot, item.companionPath);
+        const mdcDest = join15(agentsDir, item.companionPath);
         try {
-          await cp(mdcSrc, mdcDest, { force: true });
+          await cp2(mdcSrc, mdcDest, { force: true });
           copied.push(item.companionPath);
         } catch (err) {
           if (err.code !== "ENOENT") throw err;
@@ -3678,19 +4255,34 @@ async function copySelectedContent(contentRoot, agentsDir, selection, index) {
       }
     }
   }
+  for (const config of CONTENT_TYPE_CONFIGS) {
+    if (config.strategy !== "glob") continue;
+    try {
+      const dirEntries = await readdir6(join15(contentRoot, config.dir), { withFileTypes: true });
+      for (const entry of dirEntries) {
+        if (!entry.isDirectory() || entry.name.startsWith("hatch3r-")) continue;
+        const subSrc = join15(contentRoot, config.dir, entry.name);
+        const subDest = join15(agentsDir, config.dir, entry.name);
+        await mkdir4(subDest, { recursive: true });
+        await cp2(subSrc, subDest, { recursive: true, force: true });
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
   try {
-    const checksSrc = join14(contentRoot, "checks");
-    const checksDest = join14(agentsDir, "checks");
-    await mkdir3(checksDest, { recursive: true });
-    await cp(checksSrc, checksDest, { recursive: true, force: true });
+    const checksSrc = join15(contentRoot, "checks");
+    const checksDest = join15(agentsDir, "checks");
+    await mkdir4(checksDest, { recursive: true });
+    await cp2(checksSrc, checksDest, { recursive: true, force: true });
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
   try {
-    const mcpSrc = join14(contentRoot, "mcp");
-    const mcpDest = join14(agentsDir, "mcp");
-    await mkdir3(mcpDest, { recursive: true });
-    await cp(mcpSrc, mcpDest, { recursive: true, force: true });
+    const mcpSrc = join15(contentRoot, "mcp");
+    const mcpDest = join15(agentsDir, "mcp");
+    await mkdir4(mcpDest, { recursive: true });
+    await cp2(mcpSrc, mcpDest, { recursive: true, force: true });
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
@@ -3707,16 +4299,16 @@ async function buildSelectionsFromDisk(agentsDir) {
     githubAgents: []
   };
   for (const config of CONTENT_TYPE_CONFIGS) {
-    const dirPath = join14(agentsDir, config.dir);
+    const dirPath = join15(agentsDir, config.dir);
     const key = TYPE_TO_SELECTION_KEY[config.type];
     if (!key) continue;
     if (config.strategy === "subdirectory") {
       try {
-        const dirents = await readdir5(dirPath, { withFileTypes: true });
+        const dirents = await readdir6(dirPath, { withFileTypes: true });
         for (const d of dirents) {
           if (!d.isDirectory()) continue;
           try {
-            const raw = await readFile12(join14(dirPath, d.name, "SKILL.md"), "utf-8");
+            const raw = await readFile13(join15(dirPath, d.name, "SKILL.md"), "utf-8");
             const { metadata } = parseFrontmatter(raw);
             items[key].push(metadata.id || metadata.name || d.name);
           } catch {
@@ -3726,9 +4318,9 @@ async function buildSelectionsFromDisk(agentsDir) {
       }
     } else {
       try {
-        const files = await readdir5(dirPath);
+        const files = await readdir6(dirPath);
         for (const f of files.filter((f2) => f2.endsWith(".md"))) {
-          const raw = await readFile12(join14(dirPath, f), "utf-8");
+          const raw = await readFile13(join15(dirPath, f), "utf-8");
           const { metadata } = parseFrontmatter(raw);
           items[key].push(metadata.id || metadata.name || f.replace(/\.md$/, ""));
         }
@@ -3748,20 +4340,20 @@ async function addContentItem(contentRoot, agentsDir, item) {
   if (item.companionPath) {
     assertSafePath(item.companionPath, "addContentItem companion");
   }
-  const srcPath = join14(contentRoot, item.relativePath);
-  const destPath = join14(agentsDir, item.relativePath);
+  const srcPath = join15(contentRoot, item.relativePath);
+  const destPath = join15(agentsDir, item.relativePath);
   try {
     if (item.type === "skill") {
-      await mkdir3(destPath, { recursive: true });
-      await cp(srcPath, destPath, { recursive: true, force: true });
+      await mkdir4(destPath, { recursive: true });
+      await cp2(srcPath, destPath, { recursive: true, force: true });
     } else {
-      await mkdir3(dirname6(destPath), { recursive: true });
-      await cp(srcPath, destPath, { force: true });
+      await mkdir4(dirname7(destPath), { recursive: true });
+      await cp2(srcPath, destPath, { force: true });
       if (item.companionPath) {
         try {
-          await cp(
-            join14(contentRoot, item.companionPath),
-            join14(agentsDir, item.companionPath),
+          await cp2(
+            join15(contentRoot, item.companionPath),
+            join15(agentsDir, item.companionPath),
             { force: true }
           );
         } catch (err) {
@@ -3773,7 +4365,8 @@ async function addContentItem(contentRoot, agentsDir, item) {
     if (err.code === "ENOENT") {
       throw new HatchError(
         `Content "${item.id}" (${item.type}) not found in package at ${item.relativePath}. It may have been renamed or removed in this hatch3r version.`,
-        1
+        1,
+        "FS_ERROR"
       );
     }
     throw err;
@@ -3784,13 +4377,13 @@ async function removeContentItem(agentsDir, item, options) {
   if (item.companionPath) {
     assertSafePath(item.companionPath, "removeContentItem companion");
   }
-  const destPath = join14(agentsDir, item.relativePath);
+  const destPath = join15(agentsDir, item.relativePath);
   if (item.type === "skill") {
-    await rm(destPath, { recursive: true, force: true });
+    await rm2(destPath, { recursive: true, force: true });
   } else {
-    await rm(destPath, { force: true });
+    await rm2(destPath, { force: true });
     if (item.companionPath) {
-      await rm(join14(agentsDir, item.companionPath), { force: true });
+      await rm2(join15(agentsDir, item.companionPath), { force: true });
     }
   }
   if (options?.rootDir) {
@@ -3802,10 +4395,10 @@ async function removeContentItem(agentsDir, item, options) {
     };
     const customDir = typeToDir[item.type];
     if (customDir) {
-      const yamlPath = join14(options.rootDir, ".hatch3r", customDir, `${item.id}.customize.yaml`);
-      const mdPath = join14(options.rootDir, ".hatch3r", customDir, `${item.id}.customize.md`);
-      await rm(yamlPath, { force: true });
-      await rm(mdPath, { force: true });
+      const yamlPath = join15(options.rootDir, ".hatch3r", customDir, `${item.id}.customize.yaml`);
+      const mdPath = join15(options.rootDir, ".hatch3r", customDir, `${item.id}.customize.md`);
+      await rm2(yamlPath, { force: true });
+      await rm2(mdPath, { force: true });
     }
   }
 }
@@ -3816,6 +4409,10 @@ function getAllContentIds(selection) {
   }
   return ids;
 }
+function estimatePresetItemCount(preset, projectType, teamSize, index) {
+  const selection = resolveSelection(preset, projectType, teamSize, index);
+  return Object.values(selection.items).reduce((sum, arr) => sum + arr.length, 0);
+}
 function countSelectionItems(selection) {
   return Object.values(selection.items).reduce((sum, arr) => sum + arr.length, 0);
 }
@@ -3833,40 +4430,40 @@ function selectionSummary(selection) {
 }
 
 // src/cli/commands/update.ts
-var __dirname = dirname7(fileURLToPath(import.meta.url));
+var __dirname = dirname8(fileURLToPath(import.meta.url));
 var CONTENT_DIRS = ["agents", "commands", "rules", "skills", "prompts", "github-agents", "mcp", "hooks"];
 var ALWAYS_COPY_FILES = /* @__PURE__ */ new Set(["mcp.json"]);
 async function copyHatch3rFiles(srcDir, destDir, insideHatch3rDir = false, selectedIds) {
   const copied = [];
   let entries;
   try {
-    entries = await readdir6(srcDir, { withFileTypes: true });
+    entries = await readdir7(srcDir, { withFileTypes: true });
   } catch (err) {
     if (err.code === "ENOENT") return [];
     throw err;
   }
   for (const entry of entries) {
-    const srcPath = join15(srcDir, entry.name);
-    const destPath = join15(destDir, entry.name);
+    const srcPath = join16(srcDir, entry.name);
+    const destPath = join16(destDir, entry.name);
     if (entry.isDirectory()) {
       if (selectedIds && entry.name.startsWith(HATCH3R_PREFIX)) {
         if (!selectedIds.has(entry.name)) continue;
       }
-      await mkdir4(destPath, { recursive: true });
+      await mkdir5(destPath, { recursive: true });
       const subCopied = await copyHatch3rFiles(
         srcPath,
         destPath,
-        entry.name.startsWith(HATCH3R_PREFIX),
+        insideHatch3rDir || !entry.name.startsWith(HATCH3R_PREFIX),
         selectedIds
       );
-      copied.push(...subCopied.map((p) => join15(entry.name, p)));
+      copied.push(...subCopied.map((p) => join16(entry.name, p)));
     } else if (entry.name.startsWith(HATCH3R_PREFIX) || insideHatch3rDir || ALWAYS_COPY_FILES.has(entry.name)) {
       if (selectedIds && entry.name.startsWith(HATCH3R_PREFIX)) {
         const baseId = entry.name.replace(/\.(md|mdc)$/, "");
         if (!selectedIds.has(baseId)) continue;
       }
-      await mkdir4(dirname7(destPath), { recursive: true });
-      await cp2(srcPath, destPath, { force: true });
+      await mkdir5(dirname8(destPath), { recursive: true });
+      await cp3(srcPath, destPath, { force: true });
       copied.push(entry.name);
     }
   }
@@ -3875,7 +4472,7 @@ async function copyHatch3rFiles(srcDir, destDir, insideHatch3rDir = false, selec
 async function runUpdate(rootDir, manifest, options = {}) {
   const offset = options.stepOffset ?? 0;
   const total = options.totalSteps ?? 4;
-  const agentsDir = join15(rootDir, AGENTS_DIR);
+  const agentsDir = join16(rootDir, AGENTS_DIR);
   let contentRoot = findPackageRoot(__dirname);
   const pm = await detectPackageManager(rootDir);
   const s0 = createSpinner(step(offset + 1, total, "Updating package..."));
@@ -3889,7 +4486,7 @@ async function runUpdate(rootDir, manifest, options = {}) {
     const msg = isTimeout ? "Package update timed out after 30s. Check network connectivity and retry." : err instanceof Error ? err.message : String(err);
     s0.fail(step(offset + 1, total, "Failed to update package"));
     error(msg);
-    throw new HatchError(msg, 1);
+    throw new HatchError(msg, 1, isTimeout ? "NETWORK_ERROR" : "UNKNOWN_ERROR");
   }
   s0.succeed(step(offset + 1, total, "Package updated"));
   const s1 = createSpinner(step(offset + 2, total, "Updating canonical files..."));
@@ -3903,16 +4500,16 @@ async function runUpdate(rootDir, manifest, options = {}) {
   }
   const copied = [];
   for (const dir of CONTENT_DIRS) {
-    const srcDir = join15(contentRoot, dir);
+    const srcDir = join16(contentRoot, dir);
     try {
-      const dirCopied = await copyHatch3rFiles(srcDir, join15(agentsDir, dir), false, selectedIds);
-      copied.push(...dirCopied.map((p) => join15(dir, p)));
+      const dirCopied = await copyHatch3rFiles(srcDir, join16(agentsDir, dir), false, selectedIds);
+      copied.push(...dirCopied.map((p) => join16(dir, p)));
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
     }
   }
   const canonicalAgentsMd = await generateCanonicalAgentsMd(agentsDir);
-  await safeWriteFile(join15(agentsDir, "AGENTS.md"), canonicalAgentsMd);
+  await safeWriteFile(join16(agentsDir, "AGENTS.md"), canonicalAgentsMd);
   s1.succeed(step(offset + 2, total, `Updated ${copied.length} canonical files`));
   const s2 = createSpinner(step(offset + 3, total, "Re-syncing adapter output..."));
   s2.start();
@@ -3925,7 +4522,7 @@ async function runUpdate(rootDir, manifest, options = {}) {
         warn(w);
       }
       for (const out of outputs) {
-        const fullPath = join15(rootDir, out.path);
+        const fullPath = join16(rootDir, out.path);
         if (out.managedContent) {
           await safeWriteFile(fullPath, out.content, {
             managedContent: out.managedContent
@@ -3947,7 +4544,7 @@ async function runUpdate(rootDir, manifest, options = {}) {
     }
     if (adapterFailures.length === manifest.tools.length) {
       s2.fail(step(offset + 3, total, "All adapters failed"));
-      throw new HatchError("All adapters failed", 1);
+      throw new HatchError("All adapters failed", 1, "ADAPTER_ERROR");
     }
   }
   s2.succeed(step(offset + 3, total, adapterFailures.length > 0 ? `Re-synced ${manifest.tools.length - adapterFailures.length}/${manifest.tools.length} tool(s)` : `Re-synced ${manifest.tools.length} tool(s)`));
@@ -3957,6 +4554,7 @@ async function runUpdate(rootDir, manifest, options = {}) {
   await writeManifest(rootDir, manifest);
   const integrityManifest = await generateIntegrityManifest(agentsDir, HATCH3R_VERSION);
   await writeIntegrityManifest(agentsDir, integrityManifest);
+  await pruneArchives(rootDir);
   s3.succeed(step(offset + 4, total, "Manifest updated"));
   return {
     copiedFiles: copied.length,
@@ -3969,35 +4567,40 @@ var MIGRATION_CHECKPOINTS = [
   {
     id: "content-selections-init",
     condition: async (manifest) => manifest.content === void 0,
-    execute: async (manifest, rootDir) => {
-      const agentsDir = join15(rootDir, AGENTS_DIR);
+    execute: async (manifest, rootDir, headless) => {
+      const agentsDir = join16(rootDir, AGENTS_DIR);
       const content = await buildSelectionsFromDisk(agentsDir);
-      const { projectType } = await inquirer.prompt([
-        {
-          type: "list",
-          name: "projectType",
-          message: "For content tracking \u2014 is this a greenfield or brownfield project?",
-          choices: [
-            { name: "Greenfield \u2014 new project", value: "greenfield" },
-            { name: "Brownfield \u2014 existing codebase", value: "brownfield" }
-          ],
-          default: "brownfield"
-        }
-      ]);
-      const { teamSize } = await inquirer.prompt([
-        {
-          type: "list",
-          name: "teamSize",
-          message: "Solo developer or team?",
-          choices: [
-            { name: "Solo", value: "solo" },
-            { name: "Team", value: "team" }
-          ],
-          default: "team"
-        }
-      ]);
-      content.projectType = projectType;
-      content.teamSize = teamSize;
+      if (headless) {
+        content.projectType = "brownfield";
+        content.teamSize = "team";
+      } else {
+        const { projectType } = await inquirer.prompt([
+          {
+            type: "list",
+            name: "projectType",
+            message: "For content tracking \u2014 is this a greenfield or brownfield project?",
+            choices: [
+              { name: "Greenfield \u2014 new project", value: "greenfield" },
+              { name: "Brownfield \u2014 existing codebase", value: "brownfield" }
+            ],
+            default: "brownfield"
+          }
+        ]);
+        const { teamSize } = await inquirer.prompt([
+          {
+            type: "list",
+            name: "teamSize",
+            message: "Solo developer or team?",
+            choices: [
+              { name: "Solo", value: "solo" },
+              { name: "Team", value: "team" }
+            ],
+            default: "team"
+          }
+        ]);
+        content.projectType = projectType;
+        content.teamSize = teamSize;
+      }
       return {
         manifest: { ...manifest, content },
         notices: ["Migrated to explicit content tracking (all existing items preserved)"]
@@ -4007,20 +4610,26 @@ var MIGRATION_CHECKPOINTS = [
   {
     id: "platform-selection",
     condition: async (manifest) => !manifest.platform,
-    execute: async (manifest) => {
-      const { platform } = await inquirer.prompt([
-        {
-          type: "list",
-          name: "platform",
-          message: "hatch3r now supports multiple platforms. Select your platform:",
-          choices: [
-            { name: "GitHub", value: "github" },
-            { name: "Azure DevOps", value: "azure-devops" },
-            { name: "GitLab", value: "gitlab" }
-          ],
-          default: "github"
-        }
-      ]);
+    execute: async (manifest, _rootDir, headless) => {
+      let platform;
+      if (headless) {
+        platform = "github";
+      } else {
+        const answer = await inquirer.prompt([
+          {
+            type: "list",
+            name: "platform",
+            message: "hatch3r now supports multiple platforms. Select your platform:",
+            choices: [
+              { name: "GitHub", value: "github" },
+              { name: "Azure DevOps", value: "azure-devops" },
+              { name: "GitLab", value: "gitlab" }
+            ],
+            default: "github"
+          }
+        ]);
+        platform = answer.platform;
+      }
       const updated = { ...manifest, platform };
       const notices = [];
       if (platform === "github") {
@@ -4048,12 +4657,12 @@ var MIGRATION_CHECKPOINTS = [
   {
     id: "customize-yaml-size",
     condition: async (_manifest, rootDir) => {
-      const agentsDir = join15(rootDir, AGENTS_DIR);
+      const agentsDir = join16(rootDir, AGENTS_DIR);
       try {
-        const entries = await readdir6(agentsDir, { recursive: true });
+        const entries = await readdir7(agentsDir, { recursive: true });
         for (const entry of entries) {
           if (typeof entry === "string" && entry.endsWith(".customize.yaml")) {
-            const s = await stat(join15(agentsDir, entry));
+            const s = await stat2(join16(agentsDir, entry));
             if (s.size > 10240) return true;
           }
         }
@@ -4062,14 +4671,14 @@ var MIGRATION_CHECKPOINTS = [
       }
       return false;
     },
-    execute: async (manifest, rootDir) => {
+    execute: async (manifest, rootDir, _headless) => {
       const notices = [];
-      const agentsDir = join15(rootDir, AGENTS_DIR);
+      const agentsDir = join16(rootDir, AGENTS_DIR);
       try {
-        const entries = await readdir6(agentsDir, { recursive: true });
+        const entries = await readdir7(agentsDir, { recursive: true });
         for (const entry of entries) {
           if (typeof entry === "string" && entry.endsWith(".customize.yaml")) {
-            const s = await stat(join15(agentsDir, entry));
+            const s = await stat2(join16(agentsDir, entry));
             if (s.size > 10240) {
               notices.push(`Large customize file detected: ${entry} (${Math.round(s.size / 1024)}KB) \u2014 consider splitting`);
             }
@@ -4088,18 +4697,24 @@ var MIGRATION_CHECKPOINTS = [
       const worktreeCapableTools = /* @__PURE__ */ new Set(["claude"]);
       return manifest.tools.some((t) => worktreeCapableTools.has(t));
     },
-    execute: async (manifest, rootDir) => {
-      const { enabled } = await inquirer.prompt([{
-        type: "confirm",
-        name: "enabled",
-        message: "hatch3r now supports worktree file isolation for parallel agent sessions. Enable it?",
-        default: true
-      }]);
+    execute: async (manifest, rootDir, headless) => {
+      let enabled;
+      if (headless) {
+        enabled = true;
+      } else {
+        const answer = await inquirer.prompt([{
+          type: "confirm",
+          name: "enabled",
+          message: "hatch3r now supports worktree file isolation for parallel agent sessions. Enable it?",
+          default: true
+        }]);
+        enabled = answer.enabled;
+      }
       const updated = { ...manifest, worktree: { enabled } };
       const notices = [];
       if (enabled) {
         const wtContent = await generateWorktreeInclude(updated, rootDir);
-        await safeWriteFile(join15(rootDir, WORKTREE_INCLUDE_FILE), wtContent, {
+        await safeWriteFile(join16(rootDir, WORKTREE_INCLUDE_FILE), wtContent, {
           appendIfNoBlock: true
         });
         notices.push("Worktree isolation enabled \u2014 .worktreeinclude generated");
@@ -4110,12 +4725,12 @@ var MIGRATION_CHECKPOINTS = [
     }
   }
 ];
-async function runMigrationCheckpoints(manifest, rootDir) {
+async function runMigrationCheckpoints(manifest, rootDir, headless = false) {
   let current = manifest;
   const allNotices = [];
   for (const checkpoint of MIGRATION_CHECKPOINTS) {
     if (await checkpoint.condition(current, rootDir)) {
-      const { manifest: updated, notices } = await checkpoint.execute(current, rootDir);
+      const { manifest: updated, notices } = await checkpoint.execute(current, rootDir, headless);
       current = updated;
       allNotices.push(...notices);
     }
@@ -4129,9 +4744,10 @@ async function updateCommand(_opts) {
   if (!manifest) {
     error("No .agents/hatch.json found.");
     console.log(chalk4.dim("  Run `npx hatch3r init` to set up your project first.\n"));
-    throw new HatchError("No .agents/hatch.json found.", 1);
+    throw new HatchError("No .agents/hatch.json found.", 1, "CONFIG_ERROR");
   }
-  const { manifest: migrated, allNotices } = await runMigrationCheckpoints(manifest, rootDir);
+  const headless = !!_opts?.yes;
+  const { manifest: migrated, allNotices } = await runMigrationCheckpoints(manifest, rootDir, headless);
   const m = migrated;
   for (const notice of allNotices) {
     warn(notice);
@@ -4152,165 +4768,659 @@ async function updateCommand(_opts) {
   ], "success");
 }
 
-// src/archive/index.ts
-import { access as access3, cp as cp3, mkdir as mkdir5, readFile as readFile13, readdir as readdir7, rm as rm2, stat as stat2, writeFile as writeFile3 } from "fs/promises";
-import { dirname as dirname8, join as join16, sep } from "path";
-function toPosixPath(p) {
-  return sep === "\\" ? p.replaceAll("\\", "/") : p;
+// src/workspace/manifest.ts
+import { readFile as readFile14 } from "fs/promises";
+import { join as join17, normalize as normalize2, isAbsolute as isAbsolute2 } from "path";
+
+// src/workspace/types.ts
+var WORKSPACE_MANIFEST_FILE = "workspace.json";
+var WORKSPACE_MANIFEST_VERSION = "1.0.0";
+
+// src/workspace/manifest.ts
+function isUnsafeRepoPath(repoPath) {
+  if (repoPath.includes("\0")) return true;
+  if (isAbsolute2(repoPath)) return true;
+  const normalized = normalize2(repoPath);
+  if (normalized.startsWith("..")) return true;
+  return false;
 }
-var ARCHIVE_DIR = ".hatch3r-archive";
-var TOOL_PATH_PREFIXES = {
-  cursor: [".cursor/"],
-  claude: [".claude/", "CLAUDE.md", ".mcp.json"],
-  copilot: [".github/copilot-instructions.md", ".github/workflows/copilot-setup-steps.yml", ".vscode/mcp.json"],
-  windsurf: [".windsurf/", ".windsurfrules"],
-  amp: [".amp/"],
-  codex: [".codex/"],
-  gemini: [".gemini/", "GEMINI.md"],
-  cline: [".roo/", ".roomodes"],
-  aider: ["CONVENTIONS.md", ".aider.conf.yml"],
-  kiro: [".kiro/"],
-  opencode: ["opencode.json"],
-  goose: [".goosehints"],
-  zed: [".rules"],
-  "amazon-q": [".amazonq/"]
-};
-var PATH_PATTERNS = [
-  { pattern: /\/rules\/([^/]+)\.(mdc|md)$/, type: "rules" },
-  { pattern: /\/agents\/([^/]+)\.md$/, type: "agents" },
-  { pattern: /\/skills\/([^/]+)\/SKILL\.md$/, type: "skills" },
-  { pattern: /\/commands\/([^/]+)\.md$/, type: "commands" }
-];
-function parseOutputPath(filePath) {
-  for (const { pattern, type } of PATH_PATTERNS) {
-    const match = filePath.match(pattern);
-    if (match) {
-      let id = match[1];
-      if (id.startsWith(HATCH3R_PREFIX)) {
-        id = id.slice(HATCH3R_PREFIX.length);
-      }
-      id = sanitizeId(id);
-      if (id.length > 0) return { type, id };
+function validateWorkspaceManifest(data) {
+  if (!data || typeof data !== "object") return false;
+  const obj = data;
+  if (typeof obj.version !== "string") return false;
+  if (typeof obj.hatch3rVersion !== "string") return false;
+  if (typeof obj.name !== "string") return false;
+  if (!Array.isArray(obj.repos)) return false;
+  if (typeof obj.syncStrategy !== "string") return false;
+  if (!["manual", "on-sync"].includes(obj.syncStrategy)) return false;
+  if (!obj.defaults || typeof obj.defaults !== "object") return false;
+  const defaults = obj.defaults;
+  if (!Array.isArray(defaults.tools)) return false;
+  if (!defaults.features || typeof defaults.features !== "object") return false;
+  if (!defaults.mcp || typeof defaults.mcp !== "object") return false;
+  const mcp = defaults.mcp;
+  if (!Array.isArray(mcp.servers)) return false;
+  if (defaults.content !== void 0) {
+    if (typeof defaults.content !== "object" || defaults.content === null) return false;
+    const content = defaults.content;
+    if (typeof content.preset !== "string") return false;
+    if (typeof content.projectType !== "string") return false;
+    if (typeof content.teamSize !== "string") return false;
+    if (!content.items || typeof content.items !== "object") return false;
+  }
+  for (const repo of obj.repos) {
+    if (!repo || typeof repo !== "object") return false;
+    const r = repo;
+    if (typeof r.path !== "string") return false;
+    if (isUnsafeRepoPath(r.path)) return false;
+    if (typeof r.sync !== "boolean") return false;
+    if (r.owner !== void 0 && typeof r.owner !== "string") return false;
+    if (r.repo !== void 0 && typeof r.repo !== "string") return false;
+    if (r.defaultBranch !== void 0 && typeof r.defaultBranch !== "string") return false;
+    if (r.platform !== void 0 && typeof r.platform !== "string") return false;
+  }
+  return true;
+}
+async function readWorkspaceManifest(rootDir) {
+  const manifestPath = join17(rootDir, AGENTS_DIR, WORKSPACE_MANIFEST_FILE);
+  let raw;
+  try {
+    raw = await readFile14(manifestPath, "utf-8");
+  } catch (err) {
+    if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+      return null;
     }
+    throw err;
   }
-  return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new HatchError(
+      `Malformed JSON in ${manifestPath}: ${err instanceof Error ? err.message : String(err)}`,
+      1,
+      "CONFIG_ERROR"
+    );
+  }
+  if (!validateWorkspaceManifest(parsed)) {
+    throw new HatchError(
+      `Invalid workspace manifest in ${manifestPath}: required fields missing or malformed.`,
+      1,
+      "VALIDATION_ERROR"
+    );
+  }
+  return parsed;
 }
-function stripFrontmatter(content) {
-  const trimmed = content.trimStart();
-  if (trimmed.startsWith("---")) {
-    const endIdx = trimmed.indexOf("\n---", 3);
-    if (endIdx !== -1) {
-      return trimmed.slice(endIdx + 4).trim();
+async function writeWorkspaceManifest(rootDir, manifest) {
+  const manifestPath = join17(rootDir, AGENTS_DIR, WORKSPACE_MANIFEST_FILE);
+  await atomicWriteFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+}
+function createWorkspaceManifest(name, defaults, repos, syncStrategy = "manual") {
+  return {
+    version: WORKSPACE_MANIFEST_VERSION,
+    hatch3rVersion: HATCH3R_VERSION,
+    name,
+    repos,
+    defaults,
+    syncStrategy
+  };
+}
+
+// src/workspace/detect.ts
+import { readdir as readdir8, stat as stat3, access as access4 } from "fs/promises";
+import { join as join18, dirname as dirname9, relative as relative2 } from "path";
+async function detectSubRepos(rootDir) {
+  const repos = [];
+  let entries;
+  try {
+    entries = await readdir8(rootDir, { withFileTypes: true });
+  } catch {
+    return repos;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+    const subDir = join18(rootDir, entry.name);
+    const gitPath = join18(subDir, ".git");
+    let isGitRepo = false;
+    try {
+      const gitStat = await stat3(gitPath);
+      isGitRepo = gitStat.isDirectory() || gitStat.isFile();
+    } catch {
     }
+    if (!isGitRepo) continue;
+    let hasHatch3r = false;
+    try {
+      await access4(join18(subDir, AGENTS_DIR, "hatch.json"));
+      hasHatch3r = true;
+    } catch {
+    }
+    repos.push({
+      path: entry.name,
+      name: entry.name,
+      hasHatch3r
+    });
   }
-  return content.trim();
+  return repos.sort((a, b) => a.name.localeCompare(b.name));
 }
-async function fileExists2(path) {
+async function hasGitDir(dir) {
   try {
-    await access3(path);
-    return true;
+    const gitStat = await stat3(join18(dir, ".git"));
+    return gitStat.isDirectory() || gitStat.isFile();
   } catch {
     return false;
   }
 }
-async function collectToolFiles(rootDir, tool) {
-  const prefixes = TOOL_PATH_PREFIXES[tool];
-  if (!prefixes) return [];
-  const files = [];
-  for (const prefix of prefixes) {
-    const absPath = join16(rootDir, prefix);
-    if (prefix.endsWith("/")) {
-      try {
-        const entries = await readdir7(absPath, { recursive: true, withFileTypes: true });
-        for (const entry of entries) {
-          if (entry.isFile()) {
-            const parent = entry.parentPath ?? entry.path ?? absPath;
-            const relPath = toPosixPath(join16(prefix, parent.slice(absPath.length), entry.name));
-            files.push(relPath);
-          }
-        }
-      } catch {
+async function shouldSuggestWorkspace(dir) {
+  if (await hasGitDir(dir)) return false;
+  const repos = await detectSubRepos(dir);
+  return repos.length > 0;
+}
+
+// src/workspace/sync.ts
+import { createHash as createHash2 } from "crypto";
+import { mkdir as mkdir6, access as access6, readFile as readFile16 } from "fs/promises";
+import { join as join20, relative as relative3 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname10 } from "path";
+
+// src/detect/repoAnalyzer.ts
+import { access as access5, readFile as readFile15, readdir as readdir9 } from "fs/promises";
+import { join as join19 } from "path";
+async function analyzeRepo(rootDir) {
+  const [languages, pm, isMonorepo, hasExistingAgents, existingTools, frameworks] = await Promise.all([
+    detectLanguages(rootDir),
+    detectPackageManager(rootDir),
+    detectMonorepo(rootDir),
+    detectExistingAgents(rootDir),
+    detectExistingTools(rootDir),
+    detectFrameworks(rootDir)
+  ]);
+  const packageManager = pm.name;
+  return {
+    languages,
+    packageManager,
+    frameworks,
+    isMonorepo,
+    hasExistingAgents,
+    existingTools,
+    rootDir
+  };
+}
+async function detectLanguages(rootDir) {
+  const languages = [];
+  const indicators = {
+    typescript: ["tsconfig.json", "tsconfig.base.json"],
+    javascript: ["jsconfig.json"],
+    python: ["pyproject.toml", "setup.py", "requirements.txt", "Pipfile"],
+    rust: ["Cargo.toml", "Cargo.lock"],
+    go: ["go.mod", "go.sum"],
+    java: ["pom.xml", "build.gradle"],
+    kotlin: ["build.gradle.kts"],
+    ruby: ["Gemfile"],
+    php: ["composer.json"],
+    swift: ["Package.swift"],
+    dart: ["pubspec.yaml"],
+    elixir: ["mix.exs"]
+  };
+  for (const [lang, files] of Object.entries(indicators)) {
+    for (const file of files) {
+      if (await pathExists(join19(rootDir, file))) {
+        languages.push(lang);
+        break;
       }
-    } else if (await fileExists2(absPath)) {
-      files.push(prefix);
     }
   }
-  return files;
+  try {
+    const rootEntries = await readdir9(rootDir);
+    if (rootEntries.some((f) => f.endsWith(".csproj") || f.endsWith(".sln"))) {
+      languages.push("csharp");
+    }
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  if (languages.length === 0) {
+    languages.push("unknown");
+  }
+  return languages;
 }
-async function archiveToolOutputs(rootDir, tool) {
-  const filesToArchive = await collectToolFiles(rootDir, tool);
-  if (filesToArchive.length === 0) {
-    return { archivedFiles: [], migrations: [] };
+async function detectMonorepo(rootDir) {
+  if (await pathExists(join19(rootDir, "pnpm-workspace.yaml"))) return true;
+  if (await pathExists(join19(rootDir, "lerna.json"))) return true;
+  if (await pathExists(join19(rootDir, "nx.json"))) return true;
+  if (await pathExists(join19(rootDir, "turbo.json"))) return true;
+  if (await pathExists(join19(rootDir, "pants.toml"))) return true;
+  try {
+    const pkgJson = await readFile15(join19(rootDir, "package.json"), "utf-8");
+    const pkg = JSON.parse(pkgJson);
+    if (pkg.workspaces) return true;
+  } catch (err) {
+    const isExpected = err.code === "ENOENT" || err instanceof SyntaxError;
+    if (!isExpected) throw err;
   }
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const archiveBase = join16(rootDir, ARCHIVE_DIR, tool, timestamp);
-  const archivedFiles = [];
-  const migrations = [];
-  for (const relPath of filesToArchive) {
-    const absPath = join16(rootDir, relPath);
-    if (!await fileExists2(absPath)) continue;
-    let content;
-    try {
-      content = await readFile13(absPath, "utf-8");
-    } catch {
-      continue;
+  return false;
+}
+async function detectExistingAgents(rootDir) {
+  return pathExists(join19(rootDir, ".agents"));
+}
+var TOOL_INDICATORS = [
+  { tool: "cursor", paths: [".cursor"] },
+  { tool: "copilot", paths: [join19(".github", "copilot-instructions.md")] },
+  { tool: "claude", paths: ["CLAUDE.md", ".claude"] },
+  { tool: "opencode", paths: ["opencode.json", "opencode.jsonc"] },
+  { tool: "windsurf", paths: [".windsurfrules"] },
+  { tool: "amp", paths: [".amp"] },
+  { tool: "codex", paths: [".codex"] },
+  { tool: "gemini", paths: [".gemini", "GEMINI.md"] },
+  { tool: "cline", paths: [".clinerules", ".roo", ".roomodes"] },
+  { tool: "aider", paths: [".aider", ".aider.conf.yml"] },
+  { tool: "kiro", paths: [".kiro"] },
+  { tool: "goose", paths: [".goosehints", ".goose"] },
+  { tool: "zed", paths: [".rules"] },
+  { tool: "amazon-q", paths: [".amazonq"] }
+];
+async function detectExistingTools(rootDir) {
+  const results = await Promise.allSettled(
+    TOOL_INDICATORS.map(async ({ tool, paths }) => {
+      for (const p of paths) {
+        if (await pathExists(join19(rootDir, p))) return tool;
+      }
+      return null;
+    })
+  );
+  return results.filter(
+    (r) => r.status === "fulfilled" && r.value !== null
+  ).map((r) => r.value);
+}
+var FRAMEWORK_CONFIG_INDICATORS = [
+  { framework: "next", configs: ["next.config.js", "next.config.mjs", "next.config.ts"] },
+  { framework: "angular", configs: ["angular.json"] },
+  { framework: "svelte", configs: ["svelte.config.js", "svelte.config.ts"] },
+  { framework: "nuxt", configs: ["nuxt.config.js", "nuxt.config.ts"] },
+  { framework: "astro", configs: ["astro.config.mjs", "astro.config.ts"] }
+];
+var FRAMEWORK_DEP_INDICATORS = [
+  { framework: "next", deps: ["next"] },
+  { framework: "angular", deps: ["@angular/core"] },
+  { framework: "sveltekit", deps: ["@sveltejs/kit"] },
+  { framework: "svelte", deps: ["svelte"] },
+  { framework: "nuxt", deps: ["nuxt"] },
+  { framework: "remix", deps: ["@remix-run/react"] },
+  { framework: "astro", deps: ["astro"] },
+  { framework: "vue", deps: ["vue"] },
+  { framework: "react", deps: ["react"] },
+  { framework: "express", deps: ["express"] },
+  { framework: "fastify", deps: ["fastify"] },
+  { framework: "hono", deps: ["hono"] }
+];
+var FRAMEWORK_SUPPRESSION = {
+  next: "react",
+  remix: "react",
+  nuxt: "vue",
+  sveltekit: "svelte"
+};
+async function detectFrameworks(rootDir) {
+  const detected = /* @__PURE__ */ new Set();
+  const configResults = await Promise.allSettled(
+    FRAMEWORK_CONFIG_INDICATORS.map(async ({ framework, configs }) => {
+      for (const cfg of configs) {
+        if (await pathExists(join19(rootDir, cfg))) return framework;
+      }
+      return null;
+    })
+  );
+  for (const r of configResults) {
+    if (r.status === "fulfilled" && r.value !== null) {
+      detected.add(r.value);
     }
-    if (hasManagedBlock(content)) {
-      const customContent = stripFrontmatter(extractCustomContent(content));
-      if (customContent.length > 0) {
-        const parsed = parseOutputPath(relPath);
-        if (parsed) {
-          const customizePath = join16(rootDir, ".hatch3r", parsed.type, `${parsed.id}.customize.md`);
-          if (!await fileExists2(customizePath)) {
-            await mkdir5(dirname8(customizePath), { recursive: true });
-            await writeFile3(customizePath, customContent + "\n", "utf-8");
-            migrations.push({
-              from: relPath,
-              to: `.hatch3r/${parsed.type}/${parsed.id}.customize.md`,
-              type: parsed.type,
-              id: parsed.id
-            });
-          }
-        }
+  }
+  try {
+    const raw = await readFile15(join19(rootDir, "package.json"), "utf-8");
+    const pkg = JSON.parse(raw);
+    const allDeps = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies
+    };
+    for (const { framework, deps } of FRAMEWORK_DEP_INDICATORS) {
+      if (deps.some((d) => d in allDeps)) {
+        detected.add(framework);
       }
     }
-    const archiveDest = join16(archiveBase, relPath);
-    await mkdir5(dirname8(archiveDest), { recursive: true });
-    await cp3(absPath, archiveDest);
-    const srcStat = await stat2(absPath);
-    const destStat = await stat2(archiveDest);
-    if (destStat.size !== srcStat.size) {
-      throw new Error(`Archive copy size mismatch for ${relPath}: source=${srcStat.size}, dest=${destStat.size}`);
+  } catch (err) {
+    const isExpected = err.code === "ENOENT" || err instanceof SyntaxError;
+    if (!isExpected) throw err;
+  }
+  for (const [meta, base] of Object.entries(FRAMEWORK_SUPPRESSION)) {
+    if (detected.has(meta)) {
+      detected.delete(base);
     }
-    await rm2(absPath);
-    archivedFiles.push(relPath);
   }
-  await cleanEmptyDirs(rootDir, filesToArchive);
-  return { archivedFiles, migrations };
+  return [...detected];
 }
-async function cleanEmptyDirs(rootDir, paths) {
-  const dirs = /* @__PURE__ */ new Set();
-  for (const p of paths) {
-    let dir = dirname8(join16(rootDir, p));
-    while (dir !== rootDir && dir.length > rootDir.length) {
-      dirs.add(dir);
-      dir = dirname8(dir);
+async function pathExists(path) {
+  try {
+    await access5(path);
+    return true;
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+    return false;
+  }
+}
+
+// src/workspace/resolve.ts
+function resolveRepoConfig(defaults, overrides, protectedIds) {
+  const tools = overrides?.tools ?? defaults.tools;
+  const features = { ...defaults.features, ...overrides?.features ?? {} };
+  const mcp = overrides?.mcp ?? defaults.mcp;
+  const platform = overrides?.platform ?? defaults.platform;
+  let models;
+  if (defaults.models || overrides?.models) {
+    models = {
+      ...defaults.models,
+      ...overrides?.models,
+      agents: {
+        ...defaults.models?.agents,
+        ...overrides?.models?.agents
+      }
+    };
+    if (!models.default && !models.agents) models = void 0;
+  }
+  const contentIds = getAllContentIds(defaults.content);
+  const excludedContent = [];
+  const addedContent = [];
+  if (overrides?.contentOverrides?.exclude) {
+    for (const id of overrides.contentOverrides.exclude) {
+      if (protectedIds?.has(id)) continue;
+      if (contentIds.has(id)) {
+        contentIds.delete(id);
+        excludedContent.push(id);
+      }
     }
   }
-  const sorted = [...dirs].sort((a, b) => b.length - a.length);
-  for (const dir of sorted) {
+  if (overrides?.contentOverrides?.include) {
+    for (const id of overrides.contentOverrides.include) {
+      if (!contentIds.has(id)) {
+        contentIds.add(id);
+        addedContent.push(id);
+      }
+    }
+  }
+  return { platform, tools, features, mcp, models, contentIds, excludedContent, addedContent };
+}
+function buildSelectionFromIds(ids, baseSelection, allItems) {
+  const items = {
+    agents: [],
+    skills: [],
+    rules: [],
+    commands: [],
+    prompts: [],
+    hooks: [],
+    githubAgents: []
+  };
+  for (const item of allItems) {
+    if (!ids.has(item.id)) continue;
+    const key = TYPE_TO_SELECTION_KEY[item.type];
+    if (key) items[key].push(item.id);
+  }
+  return {
+    preset: "custom",
+    projectType: baseSelection.projectType,
+    teamSize: baseSelection.teamSize,
+    items
+  };
+}
+
+// src/workspace/git.ts
+import { execFileSync as execFileSync4 } from "child_process";
+function parseGitRemote(cwd) {
+  try {
+    const url = execFileSync4("git", ["remote", "get-url", "origin"], {
+      cwd,
+      stdio: "pipe"
+    }).toString().trim();
+    const sshMatch = url.match(/[:\/]([^/]+)\/([^/]+?)(?:\.git)?$/);
+    if (sshMatch) {
+      return { owner: sshMatch[1], repo: sshMatch[2] };
+    }
+    return { owner: "", repo: "" };
+  } catch {
+    return { owner: "", repo: "" };
+  }
+}
+function parseGitDefaultBranch(cwd) {
+  try {
+    const ref = execFileSync4("git", ["rev-parse", "--abbrev-ref", "origin/HEAD"], {
+      cwd,
+      stdio: "pipe"
+    }).toString().trim();
+    if (ref && ref.startsWith("origin/")) {
+      return ref.replace(/^origin\//, "");
+    }
+    return "main";
+  } catch {
+    return "main";
+  }
+}
+function detectPlatformFromRemote(remoteUrl) {
+  if (remoteUrl.includes("dev.azure.com") || remoteUrl.includes("visualstudio.com")) return "azure-devops";
+  if (remoteUrl.includes("gitlab.com") || remoteUrl.includes("gitlab.")) return "gitlab";
+  return "github";
+}
+function getGitRemoteUrl(cwd) {
+  try {
+    return execFileSync4("git", ["remote", "get-url", "origin"], { cwd, stdio: "pipe" }).toString().trim();
+  } catch {
+    return "";
+  }
+}
+function detectRepoGitIdentity(repoDir) {
+  const remoteUrl = getGitRemoteUrl(repoDir);
+  const { owner, repo } = parseGitRemote(repoDir);
+  const defaultBranch = parseGitDefaultBranch(repoDir);
+  const platform = remoteUrl ? detectPlatformFromRemote(remoteUrl) : "github";
+  return { owner, repo, defaultBranch, platform };
+}
+
+// src/workspace/sync.ts
+var __dirname2 = dirname10(fileURLToPath2(import.meta.url));
+var CONTENT_ROOT = findPackageRoot(__dirname2);
+var CHARS_PER_TOKEN = 4;
+async function estimateTokensForContent(contentIds, index) {
+  let totalChars = 0;
+  for (const id of contentIds) {
+    const items = getAllItemsById(index, id);
+    for (const item of items) {
+      try {
+        if (item.type === "skill") {
+          const skillPath = join20(CONTENT_ROOT, item.relativePath, "SKILL.md");
+          const content = await readFile16(skillPath, "utf-8");
+          totalChars += content.length;
+        } else {
+          const filePath = join20(CONTENT_ROOT, item.relativePath);
+          const content = await readFile16(filePath, "utf-8");
+          totalChars += content.length;
+        }
+      } catch {
+      }
+    }
+  }
+  return Math.ceil(totalChars / CHARS_PER_TOKEN);
+}
+async function syncWorkspaceRepos(workspaceRoot, options = {}) {
+  const wsManifest = await readWorkspaceManifest(workspaceRoot);
+  if (!wsManifest) {
+    return { repos: [] };
+  }
+  const wsChecksum = createHash2("sha256").update(JSON.stringify(wsManifest)).digest("hex");
+  const index = await buildContentIndex(CONTENT_ROOT);
+  const protectedIds = new Set(
+    index.items.filter((item) => item.protected).map((item) => item.id)
+  );
+  const targetRepos = options.repos?.length ? wsManifest.repos.filter((r) => options.repos.includes(r.path)) : wsManifest.repos.filter((r) => r.sync);
+  const results = [];
+  for (const repoEntry of targetRepos) {
     try {
-      const entries = await readdir7(dir);
-      if (entries.length === 0) {
-        await rm2(dir, { recursive: true });
+      const result = await syncSingleRepo(
+        workspaceRoot,
+        wsManifest,
+        wsChecksum,
+        repoEntry,
+        index,
+        protectedIds,
+        options
+      );
+      results.push(result);
+    } catch (err) {
+      results.push({
+        path: repoEntry.path,
+        added: [],
+        removed: [],
+        toolsSynced: [],
+        action: "error",
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  if (!options.dryRun) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    for (const result of results) {
+      if (result.action === "synced") {
+        const entry = wsManifest.repos.find((r) => r.path === result.path);
+        if (entry) entry.lastSync = now;
       }
-    } catch {
     }
+    await writeWorkspaceManifest(workspaceRoot, wsManifest);
   }
+  return { repos: results };
 }
-function removeManagedFilesForPaths(manifest, paths) {
-  const pathSet = new Set(paths);
-  manifest.managedFiles = manifest.managedFiles.filter((f) => !pathSet.has(f));
+async function syncSingleRepo(workspaceRoot, wsManifest, wsChecksum, repoEntry, index, protectedIds, options) {
+  const repoDir = join20(workspaceRoot, repoEntry.path);
+  const repoAgentsDir = join20(repoDir, AGENTS_DIR);
+  try {
+    await access6(repoDir);
+  } catch {
+    return {
+      path: repoEntry.path,
+      added: [],
+      removed: [],
+      toolsSynced: [],
+      action: "error",
+      error: `Directory not found: ${repoEntry.path}`
+    };
+  }
+  const resolved = resolveRepoConfig(wsManifest.defaults, repoEntry.overrides, protectedIds);
+  const effectiveSelection = buildSelectionFromIds(resolved.contentIds, wsManifest.defaults.content, index.items);
+  const existingManifest = await readManifest(repoDir);
+  const previousIds = existingManifest?.content ? getAllContentIds(existingManifest.content) : /* @__PURE__ */ new Set();
+  const toAdd = [...resolved.contentIds].filter((id) => !previousIds.has(id));
+  const toRemove = [...previousIds].filter(
+    (id) => !resolved.contentIds.has(id) && !existingManifest?.workspace?.localContent?.includes(id)
+  );
+  if (options.dryRun) {
+    const estimatedTokens = await estimateTokensForContent(resolved.contentIds, index);
+    return {
+      path: repoEntry.path,
+      added: toAdd,
+      removed: toRemove,
+      toolsSynced: resolved.tools,
+      action: "dry-run",
+      estimatedTokens
+    };
+  }
+  options.onProgress?.(`Syncing ${repoEntry.name ?? repoEntry.path}...`);
+  await mkdir6(repoAgentsDir, { recursive: true });
+  await copySelectedContent(CONTENT_ROOT, repoAgentsDir, effectiveSelection, index);
+  for (const id of toRemove) {
+    const items = getAllItemsById(index, id);
+    for (const item of items) {
+      await removeContentItem(repoAgentsDir, item, { rootDir: repoDir });
+    }
+  }
+  const canonicalAgentsMd = await generateCanonicalAgentsMd(repoAgentsDir);
+  await safeWriteFile(join20(repoAgentsDir, "AGENTS.md"), canonicalAgentsMd, { force: true });
+  const repoInfo = await analyzeRepo(repoDir);
+  let gitOwner = repoEntry.owner ?? "";
+  let gitRepo = repoEntry.repo ?? "";
+  let gitBranch = repoEntry.defaultBranch ?? "";
+  let gitPlatform = repoEntry.platform;
+  if (!gitOwner && !gitRepo) {
+    const identity = detectRepoGitIdentity(repoDir);
+    gitOwner = identity.owner;
+    gitRepo = identity.repo;
+    gitBranch = gitBranch || identity.defaultBranch;
+    gitPlatform = gitPlatform ?? identity.platform;
+  }
+  if (!gitOwner && !gitRepo && existingManifest) {
+    gitOwner = existingManifest.owner;
+    gitRepo = existingManifest.repo;
+  }
+  if (!gitBranch) gitBranch = "main";
+  const manifest = createManifest({
+    platform: gitPlatform ?? resolved.platform,
+    owner: gitOwner,
+    repo: gitRepo,
+    namespace: gitOwner,
+    project: gitRepo,
+    defaultBranch: gitBranch,
+    tools: resolved.tools,
+    features: resolved.features,
+    mcpServers: resolved.mcp.servers,
+    content: effectiveSelection,
+    languages: repoInfo.languages
+  });
+  manifest.workspace = {
+    rootPath: relative3(repoDir, workspaceRoot),
+    lastSync: (/* @__PURE__ */ new Date()).toISOString(),
+    syncVersion: HATCH3R_VERSION,
+    workspaceChecksum: wsChecksum,
+    excludedContent: resolved.excludedContent.length > 0 ? resolved.excludedContent : void 0,
+    localContent: existingManifest?.workspace?.localContent
+  };
+  if (resolved.models) {
+    manifest.models = resolved.models;
+  }
+  await writeManifest(repoDir, manifest);
+  await safeWriteFile(join20(repoDir, "AGENTS.md"), AGENTS_MD_FULL, {
+    managedContent: AGENTS_MD_INNER,
+    appendIfNoBlock: true
+  });
+  addManagedFile(manifest, "AGENTS.md");
+  const toolsSynced = [];
+  for (const tool of resolved.tools) {
+    try {
+      const adapter = getAdapter(tool);
+      const outputs = await adapter.generate(repoAgentsDir, manifest);
+      for (const w of adapter.warnings) {
+        options.onWarn?.(w);
+      }
+      for (const out of outputs) {
+        await safeWriteFile(join20(repoDir, out.path), out.content, {
+          managedContent: out.managedContent,
+          appendIfNoBlock: true
+        });
+        addManagedFile(manifest, out.path);
+      }
+      toolsSynced.push(tool);
+    } catch (err) {
+      options.onWarn?.(
+        `Failed to generate ${tool} output for ${repoEntry.path}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  await writeManifest(repoDir, manifest);
+  const integrityManifest = await generateIntegrityManifest(repoAgentsDir, HATCH3R_VERSION);
+  await writeIntegrityManifest(repoAgentsDir, integrityManifest);
+  if (manifest.features.mcp && manifest.mcp.servers.length > 0) {
+    await ensureEnvMcp(repoDir, manifest.mcp.servers);
+    await ensureGitignoreEntry(repoDir);
+  }
+  return {
+    path: repoEntry.path,
+    added: toAdd,
+    removed: toRemove,
+    toolsSynced,
+    action: "synced"
+  };
 }
 
 // src/cli/shared/constants.ts
@@ -4329,7 +5439,8 @@ var TOOL_DISPLAY_NAMES = {
   kiro: "Kiro",
   goose: "Goose",
   zed: "Zed",
-  "amazon-q": "Amazon Q"
+  "amazon-q": "Amazon Q",
+  antigravity: "Antigravity"
 };
 var TOOL_PROMPT_CHOICES = TOOLS.map((t) => ({
   name: TOOL_DISPLAY_NAMES[t],
@@ -4359,6 +5470,42 @@ var PLATFORM_MCP_SERVER = {
   "azure-devops": "azure-devops",
   gitlab: "gitlab"
 };
+var TOOL_COMMAND_SYNTAX = {
+  cursor: "/",
+  copilot: "/",
+  claude: "/",
+  opencode: "/",
+  windsurf: "run workflow ",
+  amp: "/",
+  codex: "prompt with ",
+  gemini: "/",
+  cline: "run workflow ",
+  aider: "prompt with ",
+  kiro: "/",
+  goose: "prompt with ",
+  zed: "/",
+  "amazon-q": "/",
+  antigravity: "/"
+};
+function formatCommandHint(tools, commandName) {
+  const allSlash = tools.every((t) => TOOL_COMMAND_SYNTAX[t] === "/");
+  if (allSlash) {
+    return `/${commandName}`;
+  }
+  return `the ${commandName} command`;
+}
+var TOOL_SECRET_NOTES = {
+  cursor: "Cursor: auto-loads .env.mcp from project root",
+  copilot: "VS Code / Copilot: auto-loads .env.mcp from project root",
+  claude: "Claude Code: reads .env.mcp via shell sourcing (run `set -a && source .env.mcp && set +a` before starting)",
+  windsurf: "Windsurf: auto-loads .env.mcp from project root",
+  cline: "Cline / Roo Code: reads env from VS Code settings; copy values to .vscode/settings.json or use shell sourcing",
+  amp: "Amp: reads env from shell; source .env.mcp in your shell profile",
+  codex: "Codex CLI: reads env from shell; source .env.mcp before running",
+  gemini: "Gemini CLI: reads env from shell; source .env.mcp before running",
+  aider: "Aider: reads env from shell; source .env.mcp before running",
+  opencode: "OpenCode: reads env from shell; source .env.mcp before running"
+};
 function sanitizeInput(value) {
   return value.replace(/[^a-zA-Z0-9._-]/g, "");
 }
@@ -4372,7 +5519,7 @@ function isWSL() {
 }
 
 // src/cli/commands/config.ts
-var __dirname2 = dirname9(fileURLToPath2(import.meta.url));
+var __dirname3 = dirname11(fileURLToPath3(import.meta.url));
 function computeDiff(oldManifest, newTools, newFeatures, newMcp, newPlatform, newOwner, newRepo, newNamespace, newProject) {
   const oldToolSet = new Set(oldManifest.tools);
   const newToolSet = new Set(newTools);
@@ -4425,7 +5572,13 @@ async function configCommand() {
   if (!manifest) {
     error("No .agents/hatch.json found.");
     console.log(chalk5.dim("  Run `npx hatch3r init` to set up your project first.\n"));
-    throw new HatchError("No .agents/hatch.json found.", 1);
+    throw new HatchError("No .agents/hatch.json found.", 1, "CONFIG_ERROR");
+  }
+  if (manifest.workspace) {
+    warn(
+      `This repo is managed by workspace at ${manifest.workspace.rootPath}. Changes here may be overwritten on next workspace sync.`
+    );
+    console.log();
   }
   printCurrentConfig(manifest);
   const wslTheme = isWSL() ? { icon: { checked: chalk5.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
@@ -4499,7 +5652,7 @@ async function configCommand() {
   const tools = toolAnswers.tools;
   if (tools.length === 0) {
     error("At least one tool must be selected.");
-    throw new HatchError("At least one tool must be selected.", 1);
+    throw new HatchError("At least one tool must be selected.", 1, "VALIDATION_ERROR");
   }
   const currentFeatureKeys = Object.keys(DEFAULT_FEATURES).filter((k) => manifest.features[k]);
   const featureAnswers = await inquirer2.prompt([
@@ -4560,8 +5713,12 @@ async function configCommand() {
       }
     ]);
     if (manageContent.manage) {
-      const contentRoot = findPackageRoot(__dirname2);
-      const agentsDir = join17(rootDir, AGENTS_DIR);
+      info(
+        chalk5.dim("Config adds/removes content items. To customize an item's behavior without ") + chalk5.dim("removing it, use .hatch3r/<type>/<id>.customize.yaml instead.")
+      );
+      console.log();
+      const contentRoot = findPackageRoot(__dirname3);
+      const agentsDir = join21(rootDir, AGENTS_DIR);
       const index = await buildContentIndex(contentRoot);
       const currentIds = /* @__PURE__ */ new Set();
       for (const ids of Object.values(manifest.content.items)) {
@@ -4581,6 +5738,63 @@ async function configCommand() {
         }
       ]);
       const newIds = new Set(contentAnswer.items);
+      const pendingRemovals = [];
+      for (const id of currentIds) {
+        if (!newIds.has(id)) pendingRemovals.push(id);
+      }
+      if (pendingRemovals.length > 0) {
+        const dependencyWarnings = [];
+        for (const removedId of pendingRemovals) {
+          const dependents = [];
+          for (const keepId of contentAnswer.items) {
+            const keepItem = index.byId.get(keepId);
+            if (!keepItem) continue;
+            try {
+              const filePath = keepItem.type === "skill" ? join21(agentsDir, keepItem.relativePath, "SKILL.md") : join21(agentsDir, keepItem.relativePath);
+              const content = await readFile17(filePath, "utf-8");
+              const refs = extractContentReferences(content);
+              if (refs.includes(removedId)) {
+                dependents.push(keepId);
+              }
+            } catch {
+            }
+          }
+          if (dependents.length > 0) {
+            dependencyWarnings.push(
+              `Removing "${removedId}" \u2014 referenced by: ${dependents.join(", ")}`
+            );
+          }
+        }
+        const proposedSelection = {
+          ...manifest.content,
+          items: {
+            agents: [],
+            skills: [],
+            rules: [],
+            commands: [],
+            prompts: [],
+            hooks: [],
+            githubAgents: []
+          }
+        };
+        for (const id of contentAnswer.items) {
+          const proposedItem = index.byId.get(id);
+          if (proposedItem) {
+            const key = TYPE_TO_SELECTION_KEY[proposedItem.type];
+            if (key) proposedSelection.items[key].push(proposedItem.id);
+          }
+        }
+        const orchWarnings = validateOrchestrationDependencies(proposedSelection);
+        dependencyWarnings.push(...orchWarnings);
+        if (dependencyWarnings.length > 0) {
+          console.log();
+          warn("Dependency warnings for removed content:");
+          for (const w of dependencyWarnings) {
+            console.log(chalk5.dim(`  ${w}`));
+          }
+          console.log();
+        }
+      }
       for (const id of contentAnswer.items) {
         if (!currentIds.has(id)) {
           const item = index.byId.get(id);
@@ -4618,7 +5832,7 @@ async function configCommand() {
       manifest.content.items = newItems;
       if (contentChanges.added.length > 0 || contentChanges.removed.length > 0) {
         const canonicalAgentsMd = await generateCanonicalAgentsMd(agentsDir);
-        await safeWriteFile(join17(agentsDir, "AGENTS.md"), canonicalAgentsMd);
+        await safeWriteFile(join21(agentsDir, "AGENTS.md"), canonicalAgentsMd);
       }
     }
   }
@@ -4685,7 +5899,7 @@ async function configCommand() {
   if (manifest.worktree?.enabled) {
     const wtContent = await generateWorktreeInclude(manifest, rootDir);
     const wtManaged = extractManagedContent(wtContent);
-    await safeWriteFile(join17(rootDir, WORKTREE_INCLUDE_FILE), wtContent, {
+    await safeWriteFile(join21(rootDir, WORKTREE_INCLUDE_FILE), wtContent, {
       managedContent: wtManaged
     });
   }
@@ -4755,132 +5969,156 @@ async function configCommand() {
     }
     console.log();
   }
-}
-
-// src/cli/commands/init.ts
-import { access as access5, mkdir as mkdir6, readFile as readFile15 } from "fs/promises";
-import { fileURLToPath as fileURLToPath3 } from "url";
-import { dirname as dirname10, join as join19 } from "path";
-import { execFileSync as execFileSync4 } from "child_process";
-import chalk6 from "chalk";
-import inquirer3 from "inquirer";
-
-// src/detect/repoAnalyzer.ts
-import { access as access4, readFile as readFile14, readdir as readdir8 } from "fs/promises";
-import { join as join18 } from "path";
-async function analyzeRepo(rootDir) {
-  const [languages, pm, isMonorepo, hasExistingAgents, existingTools] = await Promise.all([
-    detectLanguages(rootDir),
-    detectPackageManager(rootDir),
-    detectMonorepo(rootDir),
-    detectExistingAgents(rootDir),
-    detectExistingTools(rootDir)
-  ]);
-  const packageManager = pm.name;
-  return {
-    languages,
-    packageManager,
-    isMonorepo,
-    hasExistingAgents,
-    existingTools,
-    rootDir
-  };
-}
-async function detectLanguages(rootDir) {
-  const languages = [];
-  const indicators = {
-    typescript: ["tsconfig.json", "tsconfig.base.json"],
-    javascript: ["jsconfig.json"],
-    python: ["pyproject.toml", "setup.py", "requirements.txt", "Pipfile"],
-    rust: ["Cargo.toml", "Cargo.lock"],
-    go: ["go.mod", "go.sum"],
-    java: ["pom.xml", "build.gradle"],
-    kotlin: ["build.gradle.kts"],
-    ruby: ["Gemfile"],
-    php: ["composer.json"],
-    swift: ["Package.swift"],
-    dart: ["pubspec.yaml"],
-    elixir: ["mix.exs"]
-  };
-  for (const [lang, files] of Object.entries(indicators)) {
-    for (const file of files) {
-      if (await pathExists(join18(rootDir, file))) {
-        languages.push(lang);
-        break;
-      }
+  if (diff.addedTools.length > 0 || diff.removedTools.length > 0) {
+    console.log();
+    info("Tool migration notes:");
+    if (diff.removedTools.length > 0) {
+      info(chalk5.dim(`  Removed tool output archived to .hatch3r-archive/ (recoverable).`));
+      info(chalk5.dim(`  Customizations in .hatch3r/ are tool-agnostic and carry forward.`));
     }
-  }
-  try {
-    const rootEntries = await readdir8(rootDir);
-    if (rootEntries.some((f) => f.endsWith(".csproj") || f.endsWith(".sln"))) {
-      languages.push("csharp");
+    if (diff.addedTools.length > 0) {
+      info(chalk5.dim(`  New tool output generated. Restart your editor to pick up changes.`));
+      info(chalk5.dim(`  MCP secrets (.env.mcp) are shared across tools \u2014 no re-entry needed.`));
     }
-  } catch (err) {
-    if (err.code !== "ENOENT") throw err;
-  }
-  if (languages.length === 0) {
-    languages.push("unknown");
-  }
-  return languages;
-}
-async function detectMonorepo(rootDir) {
-  if (await pathExists(join18(rootDir, "pnpm-workspace.yaml"))) return true;
-  if (await pathExists(join18(rootDir, "lerna.json"))) return true;
-  if (await pathExists(join18(rootDir, "nx.json"))) return true;
-  if (await pathExists(join18(rootDir, "turbo.json"))) return true;
-  if (await pathExists(join18(rootDir, "pants.toml"))) return true;
-  try {
-    const pkgJson = await readFile14(join18(rootDir, "package.json"), "utf-8");
-    const pkg = JSON.parse(pkgJson);
-    if (pkg.workspaces) return true;
-  } catch (err) {
-    const isExpected = err.code === "ENOENT" || err instanceof SyntaxError;
-    if (!isExpected) throw err;
+    console.log();
   }
-  return false;
-}
-async function detectExistingAgents(rootDir) {
-  return pathExists(join18(rootDir, ".agents"));
-}
-var TOOL_INDICATORS = [
-  { tool: "cursor", paths: [".cursor"] },
-  { tool: "copilot", paths: [join18(".github", "copilot-instructions.md")] },
-  { tool: "claude", paths: ["CLAUDE.md", ".claude"] },
-  { tool: "opencode", paths: ["opencode.json", "opencode.jsonc"] },
-  { tool: "windsurf", paths: [".windsurfrules"] },
-  { tool: "amp", paths: [".amp"] },
-  { tool: "codex", paths: [".codex"] },
-  { tool: "gemini", paths: [".gemini", "GEMINI.md"] },
-  { tool: "cline", paths: [".clinerules", ".roo", ".roomodes"] },
-  { tool: "aider", paths: [".aider", ".aider.conf.yml"] },
-  { tool: "kiro", paths: [".kiro"] },
-  { tool: "goose", paths: [".goosehints", ".goose"] },
-  { tool: "zed", paths: [".rules"] },
-  { tool: "amazon-q", paths: [".amazonq"] }
-];
-async function detectExistingTools(rootDir) {
-  const results = await Promise.allSettled(
-    TOOL_INDICATORS.map(async ({ tool, paths }) => {
-      for (const p of paths) {
-        if (await pathExists(join18(rootDir, p))) return tool;
+  const wsManifest = await readWorkspaceManifest(rootDir);
+  if (wsManifest) {
+    console.log();
+    info(chalk5.bold("Workspace configuration"));
+    const currentRepos = wsManifest.repos.map((r) => r.path);
+    console.log(chalk5.dim(`  Repos: ${currentRepos.join(", ") || "(none)"}`));
+    console.log(chalk5.dim(`  Sync strategy: ${wsManifest.syncStrategy}`));
+    const { manageWorkspace } = await inquirer2.prompt([
+      {
+        type: "confirm",
+        name: "manageWorkspace",
+        message: "Configure workspace settings?",
+        default: false
       }
-      return null;
-    })
-  );
-  return results.filter(
-    (r) => r.status === "fulfilled" && r.value !== null
-  ).map((r) => r.value);
-}
-async function pathExists(path) {
-  try {
-    await access4(path);
-    return true;
-  } catch (err) {
-    if (err.code !== "ENOENT") throw err;
-    return false;
+    ]);
+    if (manageWorkspace) {
+      const detectedRepos = await detectSubRepos(rootDir);
+      const existingPaths = new Set(wsManifest.repos.map((r) => r.path));
+      const newRepos = detectedRepos.filter((r) => !existingPaths.has(r.path));
+      if (newRepos.length > 0) {
+        const { addRepos } = await inquirer2.prompt([
+          {
+            type: "checkbox",
+            name: "addRepos",
+            message: "New repos detected. Add to workspace?",
+            choices: newRepos.map((r) => ({
+              name: r.name,
+              value: r.path,
+              checked: false
+            })),
+            ...wslTheme && { theme: wslTheme }
+          }
+        ]);
+        for (const path of addRepos) {
+          wsManifest.repos.push({ path, name: path, sync: false });
+        }
+      }
+      if (wsManifest.repos.length > 0) {
+        const { syncRepos } = await inquirer2.prompt([
+          {
+            type: "checkbox",
+            name: "syncRepos",
+            message: "Select repos to sync:",
+            choices: wsManifest.repos.map((r) => ({
+              name: r.name ?? r.path,
+              value: r.path,
+              checked: r.sync
+            })),
+            ...wslTheme && { theme: wslTheme }
+          }
+        ]);
+        const syncSet = new Set(syncRepos);
+        for (const repo2 of wsManifest.repos) {
+          repo2.sync = syncSet.has(repo2.path);
+        }
+      }
+      if (wsManifest.repos.length > 0) {
+        const { editIdentity } = await inquirer2.prompt([
+          {
+            type: "list",
+            name: "editIdentity",
+            message: "Repo git identities:",
+            choices: [
+              { name: "Keep current", value: "keep" },
+              { name: "Re-detect all from git remotes", value: "detect" },
+              { name: "Edit manually", value: "edit" }
+            ],
+            default: "keep"
+          }
+        ]);
+        if (editIdentity === "detect") {
+          for (const repo2 of wsManifest.repos) {
+            const identity = detectRepoGitIdentity(join21(rootDir, repo2.path));
+            repo2.owner = identity.owner || void 0;
+            repo2.repo = identity.repo || void 0;
+            repo2.defaultBranch = identity.defaultBranch || void 0;
+            repo2.platform = identity.platform || void 0;
+          }
+          info("Re-detected git identities for all repos.");
+        } else if (editIdentity === "edit") {
+          for (const repo2 of wsManifest.repos) {
+            console.log(chalk5.bold(`
+  ${repo2.name ?? repo2.path}:`));
+            const identity = await inquirer2.prompt([
+              { type: "input", name: "owner", message: "  Owner:", default: repo2.owner || void 0 },
+              { type: "input", name: "repo", message: "  Repo:", default: repo2.repo || void 0 },
+              { type: "input", name: "defaultBranch", message: "  Default branch:", default: repo2.defaultBranch || "main" }
+            ]);
+            repo2.owner = sanitizeInput(identity.owner) || void 0;
+            repo2.repo = sanitizeInput(identity.repo) || void 0;
+            repo2.defaultBranch = identity.defaultBranch.trim() || void 0;
+          }
+        }
+      }
+      const { strategy } = await inquirer2.prompt([
+        {
+          type: "list",
+          name: "strategy",
+          message: "Sync strategy:",
+          choices: [
+            { name: "Manual \u2014 sync sub-repos only with --repos flag", value: "manual" },
+            { name: "On sync \u2014 auto-sync sub-repos when running hatch3r sync", value: "on-sync" }
+          ],
+          default: wsManifest.syncStrategy
+        }
+      ]);
+      wsManifest.syncStrategy = strategy;
+      await writeWorkspaceManifest(rootDir, wsManifest);
+      const syncCount = wsManifest.repos.filter((r) => r.sync).length;
+      if (syncCount > 0) {
+        const { syncNow } = await inquirer2.prompt([
+          {
+            type: "confirm",
+            name: "syncNow",
+            message: `Sync ${syncCount} repo(s) now?`,
+            default: false
+          }
+        ]);
+        if (syncNow) {
+          const wsSpinner = createSpinner(`Syncing ${syncCount} repo(s)...`);
+          wsSpinner.start();
+          const result = await syncWorkspaceRepos(rootDir, { onWarn: (msg) => warn(msg) });
+          const succeeded = result.repos.filter((r) => r.action === "synced").length;
+          wsSpinner.succeed(`Workspace sync: ${succeeded} repo(s) synced`);
+        }
+      }
+    }
   }
 }
 
+// src/cli/commands/init.ts
+import { access as access7, mkdir as mkdir7, readFile as readFile18 } from "fs/promises";
+import { fileURLToPath as fileURLToPath4 } from "url";
+import { basename as basename2, dirname as dirname12, join as join22 } from "path";
+import chalk6 from "chalk";
+import inquirer3 from "inquirer";
+
 // src/content/presets.ts
 var PRESETS = [
   {
@@ -4920,66 +6158,45 @@ function getPreset(id) {
 }
 
 // src/cli/commands/init.ts
-var __dirname3 = dirname10(fileURLToPath3(import.meta.url));
-var CONTENT_ROOT = findPackageRoot(__dirname3);
+var __dirname4 = dirname12(fileURLToPath4(import.meta.url));
+var CONTENT_ROOT2 = findPackageRoot(__dirname4);
 var DEFAULT_TOOLS = ["cursor"];
 var DEFAULT_FEATURE_KEYS = Object.keys(DEFAULT_FEATURES);
 var DEFAULT_MCP = ["playwright", "github", "context7"];
-function parseGitRemote() {
-  try {
-    const url = execFileSync4("git", ["remote", "get-url", "origin"], {
-      stdio: "pipe"
-    }).toString().trim();
-    const sshMatch = url.match(/[:\/]([^/]+)\/([^/]+?)(?:\.git)?$/);
-    if (sshMatch) {
-      return { owner: sshMatch[1], repo: sshMatch[2] };
-    }
-    return { owner: "", repo: "" };
-  } catch (err) {
-    const e = err;
-    if (e.code === "ENOENT") return { owner: "", repo: "" };
-    if (e.status === 128) return { owner: "", repo: "" };
-    throw err;
-  }
-}
-function parseGitDefaultBranch() {
-  try {
-    const ref = execFileSync4("git", ["rev-parse", "--abbrev-ref", "origin/HEAD"], {
-      stdio: "pipe"
-    }).toString().trim();
-    if (ref && ref.startsWith("origin/")) {
-      return ref.replace(/^origin\//, "");
-    }
-    return "main";
-  } catch (err) {
-    const e = err;
-    if (e.code === "ENOENT") return "main";
-    if (e.status === 128) return "main";
-    throw err;
-  }
+function selectionHasBoardContent(selection) {
+  return selection.items.commands.some((id) => id.startsWith("hatch3r-board"));
 }
-function detectPlatformFromRemote(remoteUrl) {
-  if (remoteUrl.includes("dev.azure.com") || remoteUrl.includes("visualstudio.com")) return "azure-devops";
-  if (remoteUrl.includes("gitlab.com") || remoteUrl.includes("gitlab.")) return "gitlab";
-  return "github";
+function warnBoardPrerequisites(selection) {
+  if (!selectionHasBoardContent(selection)) return;
+  info(
+    `Board commands selected. Prerequisites: ${chalk6.bold("GitHub Projects V2")} must be enabled and your PAT needs the ${chalk6.bold("project")} scope. See ${chalk6.dim("https://docs.github.com/en/issues/planning-and-tracking-with-projects")}`
+  );
 }
-function getGitRemoteUrl() {
-  try {
-    return execFileSync4("git", ["remote", "get-url", "origin"], { stdio: "pipe" }).toString().trim();
-  } catch {
-    return "";
+function deriveWorkspacePlatform(identities) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const id of identities) {
+    counts.set(id.platform, (counts.get(id.platform) ?? 0) + 1);
+  }
+  let best = "github";
+  let max = 0;
+  for (const [p, c] of counts) {
+    if (c > max) {
+      best = p;
+      max = c;
+    }
   }
+  return best;
 }
 async function runInit(options) {
   const { rootDir, platform, owner, repo, namespace, project, defaultBranch, tools, features, mcpServers, repoInfo, contentSelection } = options;
-  const agentsDir = join19(rootDir, AGENTS_DIR);
+  const agentsDir = join22(rootDir, AGENTS_DIR);
   const totalSteps = 4;
   const s1 = createSpinner(step(1, totalSteps, "Creating canonical files..."));
   s1.start();
-  await mkdir6(agentsDir, { recursive: true });
+  await mkdir7(agentsDir, { recursive: true });
   const existingManifest = await readManifest(rootDir);
-  const index = await buildContentIndex(CONTENT_ROOT);
-  await copySelectedContent(CONTENT_ROOT, agentsDir, contentSelection, index);
+  const index = await buildContentIndex(CONTENT_ROOT2);
+  await copySelectedContent(CONTENT_ROOT2, agentsDir, contentSelection, index);
   if (existingManifest?.content) {
     const oldIds = getAllContentIds(existingManifest.content);
     const newIds = getAllContentIds(contentSelection);
@@ -4990,10 +6207,10 @@ async function runInit(options) {
       }
     }
   }
-  await mkdir6(join19(agentsDir, "learnings"), { recursive: true });
-  const mcpPath = join19(agentsDir, "mcp", "mcp.json");
+  await mkdir7(join22(agentsDir, "learnings"), { recursive: true });
+  const mcpPath = join22(agentsDir, "mcp", "mcp.json");
   try {
-    const mcpRaw = await readFile15(mcpPath, "utf-8");
+    const mcpRaw = await readFile18(mcpPath, "utf-8");
     const mcpParsed = JSON.parse(mcpRaw);
     if (mcpParsed.mcpServers) {
       const selected = new Set(mcpServers);
@@ -5015,7 +6232,7 @@ async function runInit(options) {
     if (!isExpected) throw err;
   }
   const canonicalAgentsMd = await generateCanonicalAgentsMd(agentsDir);
-  await safeWriteFile(join19(agentsDir, "AGENTS.md"), canonicalAgentsMd, { force: true });
+  await safeWriteFile(join22(agentsDir, "AGENTS.md"), canonicalAgentsMd, { force: true });
   s1.succeed(step(1, totalSteps, `Canonical files created (${countSelectionItems(contentSelection)} items)`));
   const s2 = createSpinner(step(2, totalSteps, "Writing manifest..."));
   s2.start();
@@ -5026,7 +6243,7 @@ async function runInit(options) {
     step(3, totalSteps, `Generating ${tools.map((t) => TOOL_DISPLAY_NAMES[t] ?? t).join(", ")} output...`)
   );
   s3.start();
-  await safeWriteFile(join19(rootDir, "AGENTS.md"), AGENTS_MD_FULL, {
+  await safeWriteFile(join22(rootDir, "AGENTS.md"), AGENTS_MD_FULL, {
     managedContent: AGENTS_MD_INNER,
     appendIfNoBlock: true
   });
@@ -5040,7 +6257,7 @@ async function runInit(options) {
         warn(w);
       }
       for (const out of outputs) {
-        await safeWriteFile(join19(rootDir, out.path), out.content, {
+        await safeWriteFile(join22(rootDir, out.path), out.content, {
           managedContent: out.managedContent,
           appendIfNoBlock: true
         });
@@ -5059,7 +6276,7 @@ async function runInit(options) {
     }
     if (adapterFailures.length === tools.length) {
       s3.fail(step(3, totalSteps, "All adapters failed"));
-      throw new HatchError("All adapters failed", 1);
+      throw new HatchError("All adapters failed", 1, "ADAPTER_ERROR");
     }
   }
   s3.succeed(step(3, totalSteps, adapterFailures.length > 0 ? `Adapter output generated (${adapterFailures.length} failed)` : "Adapter output generated"));
@@ -5077,7 +6294,7 @@ async function runInit(options) {
   if (manifest.worktree?.enabled) {
     const wtContent = await generateWorktreeInclude(manifest, rootDir);
     const wtManaged = extractManagedContent(wtContent);
-    await safeWriteFile(join19(rootDir, WORKTREE_INCLUDE_FILE), wtContent, {
+    await safeWriteFile(join22(rootDir, WORKTREE_INCLUDE_FILE), wtContent, {
       managedContent: wtManaged,
       appendIfNoBlock: true
     });
@@ -5125,22 +6342,21 @@ async function runInit(options) {
   const isGreenfield = repoInfo.languages.length === 1 && repoInfo.languages[0] === "unknown" && repoInfo.existingTools.length === 0 && !repoInfo.hasExistingAgents;
   summaryLines.push("");
   if (isGreenfield) {
-    summaryLines.push(`${chalk6.cyan("\u2192")} Run ${chalk6.bold("/project-spec")} to define your new project`);
+    summaryLines.push(`${chalk6.cyan("\u2192")} Run ${chalk6.bold(formatCommandHint(tools, "project-spec"))} to define your new project`);
   } else {
-    summaryLines.push(`${chalk6.cyan("\u2192")} Run ${chalk6.bold("/codebase-map")} to map your existing codebase`);
+    summaryLines.push(`${chalk6.cyan("\u2192")} Run ${chalk6.bold(formatCommandHint(tools, "codebase-map"))} to map your existing codebase`);
   }
-  printBox("Hatch complete", summaryLines, "success");
   if (envResult && envResult.newVars.length > 0) {
-    warn(
-      `Add your secrets to .env.mcp: ${envResult.newVars.join(", ")}`
-    );
-    info(`Run this, then start or restart your editor: ${getSourceEnvMcpCommand()}`);
+    summaryLines.push("");
+    summaryLines.push(`${chalk6.yellow("!")} Add your secrets to ${chalk6.bold(".env.mcp")}: ${envResult.newVars.join(", ")}`);
+    summaryLines.push(`  Then run: ${chalk6.dim(getSourceEnvMcpCommand())}`);
   }
+  printBox("Hatch complete", summaryLines, "success");
 }
 async function checkExisting(rootDir, skipPrompt, newSelection) {
-  const hatchJsonPath = join19(rootDir, AGENTS_DIR, "hatch.json");
+  const hatchJsonPath = join22(rootDir, AGENTS_DIR, "hatch.json");
   try {
-    await access5(hatchJsonPath);
+    await access7(hatchJsonPath);
     if (!skipPrompt) {
       let message = "Existing .agents/ found. This will overwrite managed files. Continue?";
       if (newSelection) {
@@ -5180,13 +6396,40 @@ function validateFlag(value, valid, fallback, name) {
   if (!value) return fallback;
   if (!valid.includes(value)) {
     error(`Invalid --${name}: "${value}". Valid: ${valid.join(", ")}`);
-    throw new HatchError(`Invalid --${name}: "${value}"`, 1);
+    throw new HatchError(`Invalid --${name}: "${value}"`, 1, "VALIDATION_ERROR");
   }
   return value;
 }
 async function initCommand(opts = {}) {
   printBanner();
   const rootDir = process.cwd();
+  if (!opts.workspace) {
+    const suggestWs = await shouldSuggestWorkspace(rootDir);
+    if (suggestWs) {
+      const detectedRepos = await detectSubRepos(rootDir);
+      if (opts.yes) {
+        opts.workspace = true;
+        info(chalk6.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 inquirer3.prompt([
+          {
+            type: "confirm",
+            name: "useWorkspace",
+            message: "Initialize as a multi-repo workspace?",
+            default: true
+          }
+        ]);
+        opts.workspace = useWorkspace;
+      }
+    }
+  }
+  if (opts.workspace) {
+    const detectedRepos = await detectSubRepos(rootDir);
+    const repoInfo2 = await analyzeRepo(rootDir);
+    await runWorkspaceInit(rootDir, detectedRepos, repoInfo2, opts);
+    return;
+  }
   const detectSpinner = createSpinner("Detecting repository...");
   detectSpinner.start();
   const repoInfo = await analyzeRepo(rootDir);
@@ -5217,7 +6460,7 @@ async function initCommand(opts = {}) {
       if (invalid.length > 0) {
         error(`Invalid tool(s): ${invalid.join(", ")}`);
         console.log(chalk6.dim(`  Valid tools: ${[...VALID_TOOLS].join(", ")}`));
-        throw new HatchError(`Invalid tool(s): ${invalid.join(", ")}`, 1);
+        throw new HatchError(`Invalid tool(s): ${invalid.join(", ")}`, 1, "VALIDATION_ERROR");
       }
       tools2 = rawTools;
     } else if (repoInfo.existingTools.length > 0) {
@@ -5234,12 +6477,13 @@ async function initCommand(opts = {}) {
     const projectType2 = validateFlag(opts.projectType, ["greenfield", "brownfield"], isGreenfield ? "greenfield" : "brownfield", "project-type");
     const teamSize2 = validateFlag(opts.teamSize, ["solo", "team"], "solo", "team-size");
     const preset = getPreset(presetId);
-    const index = await buildContentIndex(CONTENT_ROOT);
+    const index = await buildContentIndex(CONTENT_ROOT2);
     const contentSelection2 = resolveSelection(preset, projectType2, teamSize2, index);
     const orchWarnings2 = validateOrchestrationDependencies(contentSelection2);
     for (const w of orchWarnings2) {
       warn(w);
     }
+    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 });
     return;
@@ -5304,42 +6548,53 @@ async function initCommand(opts = {}) {
     }
   ]);
   const defaultBranch = defaultBranchAnswers.defaultBranch.trim() || defaultBranchDefault;
+  const filterIndex = await buildContentIndex(CONTENT_ROOT2);
   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 inquirer3.prompt([
     {
       type: "list",
       name: "projectType",
       message: "Is this a new (greenfield) or existing (brownfield) project?",
       choices: [
-        { name: "Greenfield \u2014 new project from scratch", value: "greenfield" },
-        { name: "Brownfield \u2014 existing codebase", value: "brownfield" }
+        { name: `Greenfield \u2014 new project from scratch${greenfieldExcl > 0 ? ` (filters out ${greenfieldExcl} brownfield-only item${greenfieldExcl === 1 ? "" : "s"})` : ""}`, value: "greenfield" },
+        { name: `Brownfield \u2014 existing codebase${brownfieldExcl > 0 ? ` (filters out ${brownfieldExcl} greenfield-only item${brownfieldExcl === 1 ? "" : "s"})` : ""}`, value: "brownfield" }
       ],
       default: isAutoGreenfield ? "greenfield" : "brownfield"
     }
   ]);
   const projectType = projectTypeAnswer.projectType;
+  const soloExcl = countTeamSizeExclusions("solo", filterIndex.items);
   const teamSizeAnswer = await inquirer3.prompt([
     {
       type: "list",
       name: "teamSize",
       message: "Solo developer or team collaboration?",
       choices: [
-        { name: "Solo \u2014 just me", value: "solo" },
+        { name: `Solo \u2014 just me${soloExcl > 0 ? ` (filters out ${soloExcl} team-only item${soloExcl === 1 ? "" : "s"})` : ""}`, value: "solo" },
         { name: "Team \u2014 multiple contributors", value: "team" }
       ],
       default: "solo"
     }
   ]);
   const teamSize = teamSizeAnswer.teamSize;
+  const totalItems = filterIndex.items.length;
   const presetAnswer = await inquirer3.prompt([
     {
       type: "list",
       name: "preset",
       message: "Select content profile:",
-      choices: PRESETS.map((p) => ({
-        name: `${p.name} \u2014 ${p.description}`,
-        value: p.id
-      })),
+      choices: PRESETS.map((p) => {
+        const excluded = countPresetExclusions(p, filterIndex);
+        const estimated = p.id !== "custom" ? estimatePresetItemCount(p, projectType, teamSize, filterIndex) : 0;
+        const countHint = estimated > 0 ? ` (~${estimated} items)` : "";
+        const suffix = excluded > 0 ? ` (excludes ${excluded} of ${totalItems})` : "";
+        return {
+          name: `${p.name} \u2014 ${p.description}${countHint}${suffix}`,
+          value: p.id
+        };
+      }),
       default: "standard"
     }
   ]);
@@ -5347,23 +6602,46 @@ async function initCommand(opts = {}) {
   const wslTheme = isWSL() ? { icon: { checked: chalk6.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
   let customSelections;
   if (selectedPreset.id === "custom") {
-    const contentIndex2 = await buildContentIndex(CONTENT_ROOT);
+    const contentIndex = filterIndex;
     const tagGroups = /* @__PURE__ */ new Map();
-    for (const item of contentIndex2.items) {
+    for (const item of contentIndex.items) {
       const primaryTag = item.tags[0] ?? "other";
       if (!tagGroups.has(primaryTag)) tagGroups.set(primaryTag, []);
       tagGroups.get(primaryTag).push(item);
     }
+    const TAG_LABELS = {
+      core: "Core",
+      planning: "Planning",
+      implementation: "Implementation",
+      review: "Review",
+      devops: "DevOps",
+      maintenance: "Maintenance",
+      greenfield: "Greenfield",
+      brownfield: "Brownfield",
+      board: "Board",
+      security: "Security",
+      a11y: "Accessibility",
+      performance: "Performance",
+      customize: "Customization",
+      other: "Other"
+    };
+    const groupedChoices = [];
+    for (const [tag, items] of tagGroups) {
+      groupedChoices.push(new inquirer3.Separator(`\u2500\u2500 ${TAG_LABELS[tag] ?? tag} (${items.length}) \u2500\u2500`));
+      for (const item of items) {
+        groupedChoices.push({
+          name: `${item.type}: ${item.id.replace(/^hatch3r-/, "")} \u2014 ${item.description.slice(0, 60)}`,
+          value: item.id,
+          checked: item.protected || item.tags.includes("core")
+        });
+      }
+    }
     const customAnswer = await inquirer3.prompt([
       {
         type: "checkbox",
         name: "items",
         message: "Select content items:",
-        choices: contentIndex2.items.map((item) => ({
-          name: `${item.type}: ${item.id.replace(/^hatch3r-/, "")} \u2014 ${item.description.slice(0, 60)}`,
-          value: item.id,
-          checked: item.protected || item.tags.includes("core")
-        })),
+        choices: groupedChoices,
         ...wslTheme && { theme: wslTheme }
       }
     ]);
@@ -5381,11 +6659,18 @@ async function initCommand(opts = {}) {
     }
   ]);
   const tools = toolAnswers.tools.length > 0 ? toolAnswers.tools : DEFAULT_TOOLS;
+  const secretNotes = tools.map((t) => TOOL_SECRET_NOTES[t]).filter(Boolean);
+  if (secretNotes.length > 0) {
+    info(chalk6.dim("MCP secret loading by tool:"));
+    for (const note of secretNotes) {
+      info(chalk6.dim(`  ${note}`));
+    }
+  }
   const featureAnswers = await inquirer3.prompt([
     {
       type: "checkbox",
       name: "features",
-      message: "Select features:",
+      message: "Select features (MCP provides tool-server integration):",
       choices: FEATURE_CHOICES,
       default: DEFAULT_FEATURE_KEYS,
       ...wslTheme && { theme: wslTheme }
@@ -5417,35 +6702,380 @@ async function initCommand(opts = {}) {
       mcpServers.unshift(platformMcp);
     }
   }
-  const contentIndex = await buildContentIndex(CONTENT_ROOT);
-  const contentSelection = resolveSelection(selectedPreset, projectType, teamSize, contentIndex, customSelections);
+  const contentSelection = resolveSelection(selectedPreset, projectType, teamSize, filterIndex, customSelections);
   const orchWarnings = validateOrchestrationDependencies(contentSelection);
   for (const w of orchWarnings) {
     warn(w);
   }
+  warnBoardPrerequisites(contentSelection);
   await checkExisting(rootDir, false, contentSelection);
   await runInit({ rootDir, platform, owner, repo, namespace, project, defaultBranch, tools, features, mcpServers, repoInfo, contentSelection });
 }
+async function runWorkspaceInit(rootDir, detectedRepos, repoInfo, opts) {
+  const headless = !!opts.yes;
+  console.log();
+  const wsSpinner = createSpinner("Detecting workspace repos...");
+  wsSpinner.start();
+  if (detectedRepos.length === 0) {
+    wsSpinner.succeed("Workspace created (no sub-repos found)");
+    const platform2 = "github";
+    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 index = await buildContentIndex(CONTENT_ROOT2);
+    const contentSelection2 = resolveSelection(getPreset("standard"), "brownfield", "solo", index);
+    const wsManifest2 = createWorkspaceManifest(
+      basename2(rootDir) || "workspace",
+      { platform: platform2, tools: tools2, features: features2, mcp: { servers: mcpServers2 }, content: contentSelection2 },
+      [],
+      "manual"
+    );
+    await writeWorkspaceManifest(rootDir, wsManifest2);
+    return;
+  }
+  const enriched = detectedRepos.map((r) => ({
+    ...r,
+    ...detectRepoGitIdentity(join22(rootDir, r.path))
+  }));
+  wsSpinner.succeed(`Workspace: ${detectedRepos.length} repo(s) detected`);
+  console.log();
+  console.log(chalk6.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}${chalk6.dim(platLabel)}${chalk6.dim(identity)}${chalk6.dim(r.defaultBranch)}`);
+    } else {
+      console.log(`  ${name}${chalk6.dim("(no remote detected)")}`);
+    }
+  }
+  console.log();
+  if (!headless) {
+    const { acceptIdentity } = await inquirer3.prompt([
+      {
+        type: "confirm",
+        name: "acceptIdentity",
+        message: "Accept detected repo identities?",
+        default: true
+      }
+    ]);
+    if (!acceptIdentity) {
+      for (const r of enriched) {
+        console.log(chalk6.bold(`
+  ${r.name ?? r.path}:`));
+        const identity = await inquirer3.prompt([
+          { type: "input", name: "owner", message: "  Owner:", default: r.owner || void 0 },
+          { type: "input", name: "repo", message: "  Repo:", default: r.repo || void 0 },
+          { type: "input", name: "defaultBranch", message: "  Default branch:", default: r.defaultBranch || "main" }
+        ]);
+        r.owner = sanitizeInput(identity.owner);
+        r.repo = sanitizeInput(identity.repo);
+        r.defaultBranch = identity.defaultBranch.trim() || "main";
+      }
+    }
+  }
+  const platform = deriveWorkspacePlatform(enriched);
+  let tools;
+  let features;
+  let mcpServers;
+  let contentSelection;
+  if (headless) {
+    tools = resolveToolsFromOpts(opts.tools, repoInfo);
+    features = { ...DEFAULT_FEATURES };
+    const platformMcp = PLATFORM_MCP_SERVER[platform];
+    mcpServers = features.mcp ? Array.from(/* @__PURE__ */ new Set([platformMcp, ...DEFAULT_MCP.filter((s) => s !== "github")])) : [];
+    const isGreenfield = repoInfo.languages.length === 1 && repoInfo.languages[0] === "unknown" && repoInfo.existingTools.length === 0 && !repoInfo.hasExistingAgents;
+    const presetId = validateFlag(opts.preset, ["minimal", "standard", "full"], "standard", "preset");
+    const projectType = validateFlag(opts.projectType, ["greenfield", "brownfield"], isGreenfield ? "greenfield" : "brownfield", "project-type");
+    const teamSize = validateFlag(opts.teamSize, ["solo", "team"], "solo", "team-size");
+    const preset = getPreset(presetId);
+    const index = await buildContentIndex(CONTENT_ROOT2);
+    contentSelection = resolveSelection(preset, projectType, teamSize, index);
+  } else {
+    const wslTheme = isWSL() ? { icon: { checked: chalk6.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
+    const wsFilterIndex = await buildContentIndex(CONTENT_ROOT2);
+    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 inquirer3.prompt([
+      {
+        type: "list",
+        name: "projectType",
+        message: "Is this a new (greenfield) or existing (brownfield) project?",
+        choices: [
+          { name: `Greenfield \u2014 new project from scratch${wsGreenfieldExcl > 0 ? ` (filters out ${wsGreenfieldExcl} brownfield-only item${wsGreenfieldExcl === 1 ? "" : "s"})` : ""}`, value: "greenfield" },
+          { name: `Brownfield \u2014 existing codebase${wsBrownfieldExcl > 0 ? ` (filters out ${wsBrownfieldExcl} greenfield-only item${wsBrownfieldExcl === 1 ? "" : "s"})` : ""}`, value: "brownfield" }
+        ],
+        default: isAutoGreenfield ? "greenfield" : "brownfield"
+      }
+    ]);
+    const projectType = projectTypeAnswer.projectType;
+    const wsSoloExcl = countTeamSizeExclusions("solo", wsFilterIndex.items);
+    const teamSizeAnswer = await inquirer3.prompt([
+      {
+        type: "list",
+        name: "teamSize",
+        message: "Solo developer or team collaboration?",
+        choices: [
+          { name: `Solo \u2014 just me${wsSoloExcl > 0 ? ` (filters out ${wsSoloExcl} team-only item${wsSoloExcl === 1 ? "" : "s"})` : ""}`, value: "solo" },
+          { name: "Team \u2014 multiple contributors", value: "team" }
+        ],
+        default: "solo"
+      }
+    ]);
+    const teamSize = teamSizeAnswer.teamSize;
+    const wsTotalItems = wsFilterIndex.items.length;
+    const presetAnswer = await inquirer3.prompt([
+      {
+        type: "list",
+        name: "preset",
+        message: "Select content profile:",
+        choices: PRESETS.map((p) => {
+          const excluded = countPresetExclusions(p, wsFilterIndex);
+          const wsEstimated = p.id !== "custom" ? estimatePresetItemCount(p, projectType, teamSize, wsFilterIndex) : 0;
+          const wsCountHint = wsEstimated > 0 ? ` (~${wsEstimated} items)` : "";
+          const suffix = excluded > 0 ? ` (excludes ${excluded} of ${wsTotalItems})` : "";
+          return {
+            name: `${p.name} \u2014 ${p.description}${wsCountHint}${suffix}`,
+            value: p.id
+          };
+        }),
+        default: "standard"
+      }
+    ]);
+    const selectedPreset = getPreset(presetAnswer.preset);
+    let customSelections;
+    if (selectedPreset.id === "custom") {
+      const contentIndex = wsFilterIndex;
+      const wsTagGroups = /* @__PURE__ */ new Map();
+      for (const item of contentIndex.items) {
+        const primaryTag = item.tags[0] ?? "other";
+        if (!wsTagGroups.has(primaryTag)) wsTagGroups.set(primaryTag, []);
+        wsTagGroups.get(primaryTag).push(item);
+      }
+      const WS_TAG_LABELS = {
+        core: "Core",
+        planning: "Planning",
+        implementation: "Implementation",
+        review: "Review",
+        devops: "DevOps",
+        maintenance: "Maintenance",
+        greenfield: "Greenfield",
+        brownfield: "Brownfield",
+        board: "Board",
+        security: "Security",
+        a11y: "Accessibility",
+        performance: "Performance",
+        customize: "Customization",
+        other: "Other"
+      };
+      const wsGroupedChoices = [];
+      for (const [tag, items] of wsTagGroups) {
+        wsGroupedChoices.push(new inquirer3.Separator(`\u2500\u2500 ${WS_TAG_LABELS[tag] ?? tag} (${items.length}) \u2500\u2500`));
+        for (const item of items) {
+          wsGroupedChoices.push({
+            name: `${item.type}: ${item.id.replace(/^hatch3r-/, "")} \u2014 ${item.description.slice(0, 60)}`,
+            value: item.id,
+            checked: item.protected || item.tags.includes("core")
+          });
+        }
+      }
+      const customAnswer = await inquirer3.prompt([
+        {
+          type: "checkbox",
+          name: "items",
+          message: "Select content items:",
+          choices: wsGroupedChoices,
+          ...wslTheme && { theme: wslTheme }
+        }
+      ]);
+      customSelections = customAnswer.items;
+    }
+    const toolDefaults = repoInfo.existingTools.length > 0 ? repoInfo.existingTools : DEFAULT_TOOLS;
+    const toolAnswers = await inquirer3.prompt([
+      {
+        type: "checkbox",
+        name: "tools",
+        message: "Select tools to configure:",
+        choices: TOOL_PROMPT_CHOICES,
+        default: toolDefaults,
+        ...wslTheme && { theme: wslTheme }
+      }
+    ]);
+    tools = toolAnswers.tools.length > 0 ? toolAnswers.tools : DEFAULT_TOOLS;
+    const wsSecretNotes = tools.map((t) => TOOL_SECRET_NOTES[t]).filter(Boolean);
+    if (wsSecretNotes.length > 0) {
+      info(chalk6.dim("MCP secret loading by tool:"));
+      for (const note of wsSecretNotes) {
+        info(chalk6.dim(`  ${note}`));
+      }
+    }
+    const featureAnswers = await inquirer3.prompt([
+      {
+        type: "checkbox",
+        name: "features",
+        message: "Select features:",
+        choices: FEATURE_CHOICES,
+        default: DEFAULT_FEATURE_KEYS,
+        ...wslTheme && { theme: wslTheme }
+      }
+    ]);
+    const selectedFeatures = featureAnswers.features;
+    features = { ...DEFAULT_FEATURES };
+    for (const k of Object.keys(features)) {
+      features[k] = selectedFeatures.includes(k);
+    }
+    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 inquirer3.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);
+      }
+    }
+    contentSelection = resolveSelection(selectedPreset, projectType, teamSize, wsFilterIndex, customSelections);
+  }
+  const orchWarnings = validateOrchestrationDependencies(contentSelection);
+  for (const w of orchWarnings) {
+    warn(w);
+  }
+  warnBoardPrerequisites(contentSelection);
+  await checkExisting(rootDir, headless, contentSelection);
+  await runInit({
+    rootDir,
+    platform,
+    owner: "",
+    repo: "",
+    namespace: "",
+    project: "",
+    defaultBranch: "",
+    tools,
+    features,
+    mcpServers,
+    repoInfo,
+    contentSelection
+  });
+  let repoEntries;
+  if (headless) {
+    repoEntries = enriched.map((r) => ({
+      path: r.path,
+      name: r.name,
+      sync: false,
+      owner: r.owner || void 0,
+      repo: r.repo || void 0,
+      defaultBranch: r.defaultBranch || void 0,
+      platform: r.platform || void 0
+    }));
+  } else {
+    const wslTheme = isWSL() ? { icon: { checked: chalk6.green("[x]"), unchecked: "[ ]", cursor: ">" } } : void 0;
+    const { syncRepos } = await inquirer3.prompt([
+      {
+        type: "checkbox",
+        name: "syncRepos",
+        message: "Select repos to sync workspace content to:",
+        choices: enriched.map((r) => ({
+          name: `${r.name}${r.hasHatch3r ? chalk6.dim(" (has existing hatch3r)") : ""}`,
+          value: r.path,
+          checked: false
+        })),
+        ...wslTheme && { theme: wslTheme }
+      }
+    ]);
+    const syncSet = new Set(syncRepos);
+    repoEntries = enriched.map((r) => ({
+      path: r.path,
+      name: r.name,
+      sync: syncSet.has(r.path),
+      owner: r.owner || void 0,
+      repo: r.repo || void 0,
+      defaultBranch: r.defaultBranch || void 0,
+      platform: r.platform || void 0
+    }));
+  }
+  const dirName = basename2(rootDir) || "workspace";
+  const wsManifest = createWorkspaceManifest(
+    dirName,
+    { platform, tools, features, mcp: { servers: mcpServers }, content: contentSelection },
+    repoEntries,
+    "manual"
+  );
+  await writeWorkspaceManifest(rootDir, wsManifest);
+  const syncCount = repoEntries.filter((r) => r.sync).length;
+  if (syncCount > 0) {
+    const syncSpinner = createSpinner(`Syncing ${syncCount} repo(s)...`);
+    syncSpinner.start();
+    const result = await syncWorkspaceRepos(rootDir, {
+      onWarn: (msg) => warn(msg)
+    });
+    const succeeded = result.repos.filter((r) => r.action === "synced").length;
+    const failed = result.repos.filter((r) => r.action === "error").length;
+    if (failed > 0) {
+      syncSpinner.warn(`Workspace sync: ${succeeded} synced, ${failed} failed`);
+      for (const r of result.repos.filter((r2) => r2.action === "error")) {
+        error(`  ${r.path}: ${r.error}`);
+      }
+    } else {
+      syncSpinner.succeed(`Workspace sync: ${succeeded} repo(s) synced`);
+    }
+  }
+  console.log();
+  const wsLines = [
+    label("Mode", "workspace"),
+    label("Repos", `${repoEntries.length} registered, ${syncCount} synced`),
+    label("Strategy", "manual (use hatch3r sync --repos to propagate)"),
+    label("Manifest", `${AGENTS_DIR}/workspace.json`)
+  ];
+  printBox("Workspace ready", wsLines, "success");
+}
+function resolveToolsFromOpts(toolsFlag, repoInfo) {
+  if (toolsFlag) {
+    const rawTools = toolsFlag.split(",").map((t) => t.trim());
+    const invalid = rawTools.filter((t) => !VALID_TOOLS.has(t));
+    if (invalid.length > 0) {
+      error(`Invalid tool(s): ${invalid.join(", ")}`);
+      console.log(chalk6.dim(`  Valid tools: ${[...VALID_TOOLS].join(", ")}`));
+      throw new HatchError(`Invalid tool(s): ${invalid.join(", ")}`, 1);
+    }
+    return rawTools;
+  }
+  if (repoInfo.existingTools.length > 0) return repoInfo.existingTools;
+  return DEFAULT_TOOLS;
+}
 
 // src/cli/commands/sync.ts
-import { stat as stat3, readdir as readdir9 } from "fs/promises";
-import { join as join20 } from "path";
+import { stat as stat4, readdir as readdir10 } from "fs/promises";
+import { join as join23 } from "path";
 import { execFileSync as execFileSync5 } from "child_process";
 import chalk7 from "chalk";
 async function checkSpecFreshness(rootDir) {
-  const specsDir = join20(rootDir, "docs", "specs");
+  const specsDir = join23(rootDir, "docs", "specs");
   try {
-    await stat3(specsDir);
+    await stat4(specsDir);
   } catch {
     return;
   }
   let oldestSpecMtime = Date.now();
   try {
-    const entries = await readdir9(specsDir, { withFileTypes: true, recursive: true });
+    const entries = await readdir10(specsDir, { withFileTypes: true, recursive: true });
     for (const entry of entries) {
       if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
       const parentPath = entry.parentPath ?? entry.path ?? specsDir;
-      const fileStat = await stat3(join20(parentPath, entry.name));
+      const fileStat = await stat4(join23(parentPath, entry.name));
       if (fileStat.mtimeMs < oldestSpecMtime) {
         oldestSpecMtime = fileStat.mtimeMs;
       }
@@ -5467,15 +7097,15 @@ async function checkSpecFreshness(rootDir) {
   } catch {
   }
 }
-async function syncCommand() {
+async function syncCommand(opts = {}) {
   printBanner(true);
   const rootDir = process.cwd();
-  const agentsDir = join20(rootDir, AGENTS_DIR);
+  const agentsDir = join23(rootDir, AGENTS_DIR);
   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"));
-    throw new HatchError("No .agents/hatch.json found.", 1);
+    throw new HatchError("No .agents/hatch.json found.", 1, "CONFIG_ERROR");
   }
   const m = manifest;
   const integrityResults = await verifyIntegrity(agentsDir);
@@ -5497,28 +7127,32 @@ async function syncCommand() {
   let currentStep = 0;
   const s1 = createSpinner(step(++currentStep, totalSteps, "Syncing AGENTS.md..."));
   s1.start();
-  const agentsMdResult = await safeWriteFile(join20(rootDir, "AGENTS.md"), AGENTS_MD_FULL, {
+  const agentsMdResult = await safeWriteFile(join23(rootDir, "AGENTS.md"), AGENTS_MD_FULL, {
     managedContent: AGENTS_MD_INNER
   });
   if (agentsMdResult.warning) warn(agentsMdResult.warning);
   results.push({ path: "AGENTS.md", action: agentsMdResult.action });
   const canonicalAgentsMd = await generateCanonicalAgentsMd(agentsDir);
-  const canonicalResult = await safeWriteFile(join20(agentsDir, "AGENTS.md"), canonicalAgentsMd);
+  const canonicalResult = await safeWriteFile(join23(agentsDir, "AGENTS.md"), canonicalAgentsMd);
   if (canonicalResult.warning) warn(canonicalResult.warning);
   results.push({ path: `${AGENTS_DIR}/AGENTS.md`, action: canonicalResult.action });
   s1.succeed(step(currentStep, totalSteps, "AGENTS.md synced"));
+  const generationMode = opts.minimal ? "minimal" : "standard";
+  if (opts.minimal) {
+    info("Minimal generation mode: output will be stripped-down to reduce token usage.");
+  }
   const adapterFailures = [];
   for (const tool of m.tools) {
     const s = createSpinner(step(++currentStep, totalSteps, `Generating ${tool} output...`));
     s.start();
     try {
       const adapter = getAdapter(tool);
-      const outputs = await adapter.generate(agentsDir, m);
+      const outputs = await adapter.generate(agentsDir, m, generationMode);
       for (const w of adapter.warnings) {
         warn(w);
       }
       for (const out of outputs) {
-        const fullPath = join20(rootDir, out.path);
+        const fullPath = join23(rootDir, out.path);
         if (out.managedContent) {
           const result = await safeWriteFile(fullPath, out.content, {
             managedContent: out.managedContent
@@ -5545,7 +7179,7 @@ async function syncCommand() {
       error(`Failed to generate ${f.tool}: ${f.error}`);
     }
     if (adapterFailures.length === m.tools.length) {
-      throw new HatchError("All adapters failed", 1);
+      throw new HatchError("All adapters failed", 1, "ADAPTER_ERROR");
     }
   }
   for (const tool of m.tools) {
@@ -5558,7 +7192,7 @@ async function syncCommand() {
     const wtContent = await generateWorktreeInclude(m, rootDir);
     const wtManaged = extractManagedContent(wtContent);
     const wtResult = await safeWriteFile(
-      join20(rootDir, WORKTREE_INCLUDE_FILE),
+      join23(rootDir, WORKTREE_INCLUDE_FILE),
       wtContent,
       { managedContent: wtManaged }
     );
@@ -5578,6 +7212,9 @@ async function syncCommand() {
       info(`Run this, then start or restart your editor: ${getSourceEnvMcpCommand()}`);
     }
   }
+  const integrityManifest = await generateIntegrityManifest(agentsDir, HATCH3R_VERSION);
+  await writeIntegrityManifest(agentsDir, integrityManifest);
+  await pruneArchives(rootDir);
   await checkSpecFreshness(rootDir);
   console.log();
   const icons = {
@@ -5590,11 +7227,55 @@ async function syncCommand() {
     return `${icon} ${r.path} ${chalk7.dim(`(${r.action})`)}`;
   });
   printBox("Sync complete", summaryLines, "success");
+  const wsManifest = await readWorkspaceManifest(rootDir);
+  if (!wsManifest) return;
+  const syncReposRequested = opts.repos !== void 0;
+  const syncOnSync = wsManifest.syncStrategy === "on-sync";
+  const syncableCount = wsManifest.repos.filter((r) => r.sync).length;
+  if (!syncReposRequested && !syncOnSync) {
+    if (syncableCount > 0) {
+      info(`Workspace: ${syncableCount} repo(s) available for sync. Run ${chalk7.bold("hatch3r sync --repos")} to propagate.`);
+    }
+    return;
+  }
+  const repoPaths = Array.isArray(opts.repos) ? opts.repos : void 0;
+  console.log();
+  const wsSpinner = createSpinner(
+    opts.dryRun ? "Workspace sync (dry run)..." : `Syncing workspace to ${repoPaths ? repoPaths.length : syncableCount} repo(s)...`
+  );
+  wsSpinner.start();
+  const wsResult = await syncWorkspaceRepos(rootDir, {
+    repos: repoPaths,
+    dryRun: opts.dryRun,
+    force: opts.force,
+    onWarn: (msg) => warn(msg)
+  });
+  if (opts.dryRun) {
+    wsSpinner.succeed("Workspace sync (dry run)");
+    for (const r of wsResult.repos) {
+      const changes = [];
+      if (r.added.length > 0) changes.push(`+${r.added.length} content`);
+      if (r.removed.length > 0) changes.push(`-${r.removed.length} content`);
+      if (r.toolsSynced.length > 0) changes.push(`${r.toolsSynced.length} tools`);
+      info(`  ${r.path}: ${changes.length > 0 ? changes.join(", ") : "up to date"}`);
+    }
+    return;
+  }
+  const succeeded = wsResult.repos.filter((r) => r.action === "synced").length;
+  const failed = wsResult.repos.filter((r) => r.action === "error").length;
+  if (failed > 0) {
+    wsSpinner.warn(`Workspace sync: ${succeeded} synced, ${failed} failed`);
+    for (const r of wsResult.repos.filter((r2) => r2.action === "error")) {
+      error(`  ${r.path}: ${r.error}`);
+    }
+  } else {
+    wsSpinner.succeed(`Workspace sync: ${succeeded} repo(s) synced`);
+  }
 }
 
 // src/cli/commands/validate.ts
-import { readdir as readdir10, readFile as readFile16, access as access6 } from "fs/promises";
-import { join as join21, posix as posix2 } from "path";
+import { readdir as readdir11, readFile as readFile19, access as access8 } from "fs/promises";
+import { join as join24, posix as posix2 } from "path";
 import chalk8 from "chalk";
 import { parse as parseYaml4 } from "yaml";
 var DEFAULT_KNOWN_AGENTS = /* @__PURE__ */ new Set([
@@ -5630,7 +7311,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 access6(join21(rootDir, managedFile));
+      await access8(join24(rootDir, managedFile));
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
       result.warnings.push(`Managed file missing from disk: ${managedFile}`);
@@ -5642,7 +7323,7 @@ async function validateDirectories(agentsDir, result) {
   const optionalDirs = ["commands", "prompts", "mcp", "policy", "github-agents"];
   for (const dir of requiredDirs) {
     try {
-      await access6(join21(agentsDir, dir));
+      await access8(join24(agentsDir, dir));
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
       result.errors.push(`Required directory missing: .agents/${dir}/`);
@@ -5650,7 +7331,7 @@ async function validateDirectories(agentsDir, result) {
   }
   for (const dir of optionalDirs) {
     try {
-      await access6(join21(agentsDir, dir));
+      await access8(join24(agentsDir, dir));
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
       result.warnings.push(`Optional directory missing: .agents/${dir}/`);
@@ -5661,13 +7342,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 = join21(agentsDir, dir);
+    const dirPath = join24(agentsDir, dir);
     try {
-      const entries = await readdir10(dirPath, { withFileTypes: true });
+      const entries = await readdir11(dirPath, { withFileTypes: true });
       for (const entry of entries) {
         if (entry.isFile() && entry.name.endsWith(".md")) {
-          const filePath = join21(dirPath, entry.name);
-          const content = await readFile16(filePath, "utf-8");
+          const filePath = join24(dirPath, entry.name);
+          const content = await readFile19(filePath, "utf-8");
           if (!content.startsWith("---")) {
             result.warnings.push(`Missing frontmatter: .agents/${dir}/${entry.name}`);
           } else {
@@ -5686,9 +7367,9 @@ async function validateFrontmatter(agentsDir, result) {
             }
           }
         } else if (entry.isDirectory()) {
-          const skillPath = join21(dirPath, entry.name, "SKILL.md");
+          const skillPath = join24(dirPath, entry.name, "SKILL.md");
           try {
-            await access6(skillPath);
+            await access8(skillPath);
           } catch (err) {
             if (err.code !== "ENOENT") throw err;
             result.warnings.push(`Skill directory missing SKILL.md: .agents/${dir}/${entry.name}/`);
@@ -5700,7 +7381,7 @@ async function validateFrontmatter(agentsDir, result) {
     }
   }
   try {
-    await access6(join21(agentsDir, "AGENTS.md"));
+    await access8(join24(agentsDir, "AGENTS.md"));
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
     result.warnings.push("Missing .agents/AGENTS.md");
@@ -5719,22 +7400,22 @@ async function validateManagedFilePrefixes(manifest, result) {
 }
 async function validateHooks(agentsDir, manifest, result) {
   if (!manifest.features.hooks) return;
-  const hooksDir = join21(agentsDir, "hooks");
+  const hooksDir = join24(agentsDir, "hooks");
   try {
-    const hookFiles = await readdir10(hooksDir);
+    const hookFiles = await readdir11(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 readdir10(join21(agentsDir, "agents"));
+      const agentEntries = await readdir11(join24(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 readFile16(join21(hooksDir, hookFile), "utf-8");
+      const hookContent = await readFile19(join24(hooksDir, hookFile), "utf-8");
       if (!hookContent.startsWith("---")) {
         result.warnings.push(`Hook missing frontmatter: .agents/hooks/${hookFile}`);
         continue;
@@ -5766,9 +7447,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 = join21(agentsDir, "mcp", "mcp.json");
+  const mcpPath = join24(agentsDir, "mcp", "mcp.json");
   try {
-    const mcpContent = await readFile16(mcpPath, "utf-8");
+    const mcpContent = await readFile19(mcpPath, "utf-8");
     const mcpParsed = JSON.parse(mcpContent);
     if (!mcpParsed.mcpServers || typeof mcpParsed.mcpServers !== "object") {
       result.errors.push("MCP config missing 'mcpServers' key");
@@ -5794,17 +7475,101 @@ async function validateModels(manifest, result) {
     }
   }
 }
+async function validateCustomizeYaml(rootDir, result) {
+  const VALID_FIELDS = /* @__PURE__ */ new Set(["model", "scope", "description", "enabled"]);
+  const FIELD_TYPES = {
+    model: "string",
+    scope: "string",
+    description: "string",
+    enabled: "boolean"
+  };
+  for (const { dir } of CUSTOMIZATION_TYPES) {
+    const customDir = join24(rootDir, ".hatch3r", dir);
+    let files;
+    try {
+      files = await readdir11(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 = join24(customDir, file);
+      const itemId = file.replace(".customize.yaml", "");
+      let raw;
+      try {
+        raw = await readFile19(filePath, "utf-8");
+      } catch {
+        continue;
+      }
+      if (Buffer.byteLength(raw, "utf-8") > 10240) {
+        result.warnings.push(
+          `.customize.yaml for "${itemId}" exceeds 10KB limit and will be skipped during generation`
+        );
+        continue;
+      }
+      let parsed;
+      try {
+        parsed = parseYaml4(raw);
+      } catch {
+        result.errors.push(
+          `Invalid YAML syntax in .hatch3r/${dir}/${file}`
+        );
+        continue;
+      }
+      if (!parsed || typeof parsed !== "object") {
+        result.warnings.push(
+          `.customize.yaml for "${itemId}" is empty or not an object`
+        );
+        continue;
+      }
+      for (const key of Object.keys(parsed)) {
+        if (!VALID_FIELDS.has(key)) {
+          result.warnings.push(
+            `.hatch3r/${dir}/${file}: unknown field "${key}" (valid: ${[...VALID_FIELDS].join(", ")})`
+          );
+        }
+      }
+      for (const [key, expectedType] of Object.entries(FIELD_TYPES)) {
+        if (key in parsed && parsed[key] !== void 0 && parsed[key] !== null) {
+          const actualType = typeof parsed[key];
+          if (actualType !== expectedType) {
+            result.warnings.push(
+              `.hatch3r/${dir}/${file}: field "${key}" should be ${expectedType} but is ${actualType}`
+            );
+          }
+        }
+      }
+      for (const field of ["description", "scope"]) {
+        const value = parsed[field];
+        if (typeof value === "string") {
+          const violations = scanForDeniedPatterns(value);
+          for (const v of violations) {
+            result.warnings.push(
+              `.hatch3r/${dir}/${file}: field "${field}" contains denied pattern: ${v}`
+            );
+          }
+        }
+      }
+      const type = dir;
+      const readResult = await readCustomizationWithWarnings(rootDir, type, itemId);
+      for (const w of readResult.warnings) {
+        result.warnings.push(w);
+      }
+    }
+  }
+}
 async function validateCustomizations(rootDir, agentsDir, manifest, result) {
   for (const { dir, canonical } of CUSTOMIZATION_TYPES) {
-    const customDir = join21(rootDir, ".hatch3r", dir);
+    const customDir = join24(rootDir, ".hatch3r", dir);
     try {
-      const customFiles = await readdir10(customDir);
+      const customFiles = await readdir11(customDir);
       for (const file of customFiles) {
         if (file.endsWith(".customize.yaml")) {
           const itemId = file.replace(".customize.yaml", "");
-          const canonicalPath = canonical === "skills" ? join21(agentsDir, canonical, itemId) : join21(agentsDir, canonical, `${itemId}.md`);
+          const canonicalPath = canonical === "skills" ? join24(agentsDir, canonical, itemId) : join24(agentsDir, canonical, `${itemId}.md`);
           try {
-            await access6(canonicalPath);
+            await access8(canonicalPath);
           } catch (err) {
             if (err.code !== "ENOENT") throw err;
             result.warnings.push(`Customization file for non-existent ${canonical.slice(0, -1)}: .hatch3r/${dir}/${file}`);
@@ -5830,9 +7595,9 @@ async function validateContentConsistency(rootDir, agentsDir, manifest, result)
     for (const [key, cfg] of Object.entries(contentDirs)) {
       const ids = manifest.content.items[key];
       for (const id of ids) {
-        const checkPath = cfg.strategy === "subdir" ? join21(agentsDir, cfg.dir, id, "SKILL.md") : join21(agentsDir, cfg.dir, `${id}.md`);
+        const checkPath = cfg.strategy === "subdir" ? join24(agentsDir, cfg.dir, id, "SKILL.md") : join24(agentsDir, cfg.dir, `${id}.md`);
         try {
-          await access6(checkPath);
+          await access8(checkPath);
         } catch {
           result.warnings.push(`Content "${id}" (${key}) in manifest but missing from .agents/${cfg.dir}/`);
         }
@@ -5843,9 +7608,9 @@ async function validateContentConsistency(rootDir, agentsDir, manifest, result)
       for (const id of ids) allContentIds.add(id);
     }
     for (const { dir } of CUSTOMIZATION_TYPES) {
-      const customDir = join21(rootDir, ".hatch3r", dir);
+      const customDir = join24(rootDir, ".hatch3r", dir);
       try {
-        const files = await readdir10(customDir);
+        const files = await readdir11(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}`)) {
@@ -5857,12 +7622,12 @@ async function validateContentConsistency(rootDir, agentsDir, manifest, result)
       }
     }
   }
-  const learningsDir = join21(agentsDir, "learnings");
+  const learningsDir = join24(agentsDir, "learnings");
   try {
-    const learningFiles = await readdir10(learningsDir);
+    const learningFiles = await readdir11(learningsDir);
     const mdFiles = learningFiles.filter((f) => f.endsWith(".md"));
     for (const file of mdFiles) {
-      const content = await readFile16(join21(learningsDir, file), "utf-8");
+      const content = await readFile19(join24(learningsDir, file), "utf-8");
       const violations = scanForDeniedPatterns(content);
       if (violations.length > 0) {
         for (const v of violations) {
@@ -5877,18 +7642,18 @@ async function validateContentConsistency(rootDir, agentsDir, manifest, result)
 async function validateCommand() {
   printBanner(true);
   const rootDir = process.cwd();
-  const agentsDir = join21(rootDir, AGENTS_DIR);
+  const agentsDir = join24(rootDir, AGENTS_DIR);
   const result = { errors: [], warnings: [] };
   const spinner = createSpinner("Validating .agents/ structure...");
   spinner.start();
   try {
-    await access6(agentsDir);
+    await access8(agentsDir);
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
     spinner.fail("Validation failed");
     error(".agents/ directory not found. Run `hatch3r init` first.");
     console.log();
-    throw new HatchError(".agents/ directory not found.", 1);
+    throw new HatchError(".agents/ directory not found.", 1, "CONFIG_ERROR");
   }
   const manifest = await readManifest(rootDir);
   await validateManifest2(rootDir, manifest, result);
@@ -5900,6 +7665,7 @@ async function validateCommand() {
     await validateMcp(agentsDir, manifest, result);
     await validateModels(manifest, result);
     await validateCustomizations(rootDir, agentsDir, manifest, result);
+    await validateCustomizeYaml(rootDir, result);
     await validateContentConsistency(rootDir, agentsDir, manifest, result);
     try {
       const index = await buildContentIndex(agentsDir);
@@ -5909,6 +7675,18 @@ async function validateCommand() {
           result.warnings.push(w);
         }
       }
+      const EXPECTED_CROSS_TYPE_PAIRS = /* @__PURE__ */ new Set(["command", "skill"]);
+      for (const collision of index.collisions) {
+        if (collision.kind === "cross-type") {
+          const types = /* @__PURE__ */ new Set([collision.existingType, collision.duplicateType]);
+          if (types.size === 2 && [...types].every((t) => EXPECTED_CROSS_TYPE_PAIRS.has(t))) {
+            continue;
+          }
+        }
+        result.warnings.push(
+          `Content ID collision: "${collision.id}" exists as ${collision.existingType} (${collision.existingPath}) and ${collision.duplicateType} (${collision.duplicatePath})`
+        );
+      }
     } catch {
     }
     if (manifest.content) {
@@ -5919,8 +7697,22 @@ async function validateCommand() {
     }
   }
   spinner.stop();
+  let hasCustomizations = false;
+  for (const { dir } of CUSTOMIZATION_TYPES) {
+    try {
+      const files = await readdir11(join24(rootDir, ".hatch3r", dir));
+      if (files.some((f) => f.endsWith(".customize.yaml") || f.endsWith(".customize.md"))) {
+        hasCustomizations = true;
+        break;
+      }
+    } catch {
+    }
+  }
   if (result.errors.length === 0 && result.warnings.length === 0) {
     printBox("Validation", [chalk8.green("All checks passed")], "success");
+    if (hasCustomizations) {
+      printCustomizationHint();
+    }
     return;
   }
   console.log();
@@ -5942,7 +7734,7 @@ async function validateCommand() {
       `${chalk8.yellow("\u26A0")} ${result.warnings.length} warning(s)`
     ];
     printBox("Validation failed", summaryLines, "error");
-    throw new HatchError("Validation failed", 1);
+    throw new HatchError("Validation failed", 1, "VALIDATION_ERROR");
   } else {
     const summaryLines = [
       `${chalk8.green("\u2714")} 0 errors`,
@@ -5950,15 +7742,29 @@ async function validateCommand() {
     ];
     printBox("Validation passed", summaryLines, "success");
   }
+  if (hasCustomizations) {
+    printCustomizationHint();
+  }
+}
+function printCustomizationHint() {
+  console.log();
+  info(chalk8.bold("Customization mechanisms detected. Quick reference:"));
+  console.log(chalk8.dim("  1. hatch3r- prefix: Files prefixed with hatch3r- are managed by hatch3r and"));
+  console.log(chalk8.dim("     overwritten on update. Do not edit these directly."));
+  console.log(chalk8.dim("  2. Managed blocks: Sections between <!-- MANAGED-BLOCK:BEGIN --> and"));
+  console.log(chalk8.dim("     <!-- MANAGED-BLOCK:END --> are auto-updated. Add content outside these markers."));
+  console.log(chalk8.dim("  3. .customize.yaml/.md: Place in .hatch3r/{type}/ to override model, scope,"));
+  console.log(chalk8.dim("     description, or disable items. Use .customize.md for content additions."));
+  console.log(chalk8.dim("  See: https://docs.hatch3r.com/docs/guides/customization"));
 }
 
 // src/cli/commands/verify.ts
-import { join as join22 } from "path";
+import { join as join25 } from "path";
 import chalk9 from "chalk";
 async function verifyCommand() {
   printBanner(true);
   const rootDir = process.cwd();
-  const agentsDir = join22(rootDir, AGENTS_DIR);
+  const agentsDir = join25(rootDir, AGENTS_DIR);
   const spinner = createSpinner("Verifying file integrity...");
   spinner.start();
   const manifest = await readIntegrityManifest(agentsDir);
@@ -5966,7 +7772,7 @@ async function verifyCommand() {
     spinner.fail("No integrity manifest found");
     error("Missing .agents/.integrity.json \u2014 run `hatch3r init` or `hatch3r update` to generate it.");
     console.log();
-    throw new HatchError("Missing .agents/.integrity.json", 1);
+    throw new HatchError("Missing .agents/.integrity.json", 1, "INTEGRITY_ERROR");
   }
   const results = await verifyIntegrity(agentsDir);
   spinner.stop();
@@ -6015,30 +7821,30 @@ async function verifyCommand() {
       info(`Modified files may have been tampered with. Run ${chalk9.bold("hatch3r update")} to restore originals.`);
     }
     console.log();
-    throw new HatchError("Integrity check failed", 1);
+    throw new HatchError("Integrity check failed", 1, "INTEGRITY_ERROR");
   } else {
     printBox("Integrity check passed", summaryLines, "success");
   }
 }
 
 // src/cli/commands/status.ts
-import { readFile as readFile17, readdir as readdir11, stat as stat4 } from "fs/promises";
-import { join as join23 } from "path";
+import { readFile as readFile20, readdir as readdir12, stat as stat5 } from "fs/promises";
+import { join as join26 } from "path";
 import chalk10 from "chalk";
 async function dirCharCount(dir) {
   let total = 0;
   let entries;
   try {
-    entries = await readdir11(dir, { withFileTypes: true });
+    entries = await readdir12(dir, { withFileTypes: true });
   } catch {
     return 0;
   }
   for (const entry of entries) {
-    const fullPath = join23(dir, entry.name);
+    const fullPath = join26(dir, entry.name);
     if (entry.isDirectory()) {
       total += await dirCharCount(fullPath);
     } else if (entry.isFile()) {
-      const info2 = await stat4(fullPath);
+      const info2 = await stat5(fullPath);
       total += info2.size;
     }
   }
@@ -6047,12 +7853,12 @@ async function dirCharCount(dir) {
 async function statusCommand() {
   printBanner(true);
   const rootDir = process.cwd();
-  const agentsDir = join23(rootDir, AGENTS_DIR);
+  const agentsDir = join26(rootDir, AGENTS_DIR);
   const manifest = await readManifest(rootDir);
   if (!manifest) {
     error("No .agents/hatch.json found.");
     console.log(chalk10.dim("  Run `npx hatch3r init` to set up your project first.\n"));
-    throw new HatchError("No .agents/hatch.json found.", 1);
+    throw new HatchError("No .agents/hatch.json found.", 1, "CONFIG_ERROR");
   }
   const spinner = createSpinner("Checking sync status...");
   spinner.start();
@@ -6063,9 +7869,9 @@ async function statusCommand() {
     const outputs = await adapter.generate(agentsDir, manifest);
     fileLines.push(chalk10.bold(`${tool}:`));
     for (const out of outputs) {
-      const destPath = join23(rootDir, out.path);
+      const destPath = join26(rootDir, out.path);
       try {
-        const existing = await readFile17(destPath, "utf-8");
+        const existing = await readFile20(destPath, "utf-8");
         const existingBlock = extractManagedBlock(existing);
         const expectedBlock = out.managedContent ?? extractManagedBlock(out.content);
         if (existingBlock !== null && expectedBlock !== null ? existingBlock === expectedBlock : existing === out.content) {
@@ -6107,6 +7913,36 @@ async function statusCommand() {
     info(`Run ${chalk10.bold("hatch3r sync")} to regenerate drifted/missing files.`);
     console.log();
   }
+  const wsManifest = await readWorkspaceManifest(rootDir);
+  if (wsManifest && wsManifest.repos.length > 0) {
+    const wsLines = [];
+    for (const repo of wsManifest.repos) {
+      const icon = repo.sync ? chalk10.green("\u2713") : chalk10.dim("\u25CB");
+      let detail;
+      if (!repo.sync) {
+        detail = chalk10.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 = chalk10.yellow("never synced");
+      }
+      const identity = repo.owner && repo.repo ? chalk10.dim(`${repo.owner}/${repo.repo}`) : "";
+      const branch = repo.defaultBranch ? chalk10.dim(`[${repo.defaultBranch}]`) : "";
+      const identityPart = identity || branch ? `  ${identity} ${branch}` : "";
+      wsLines.push(`${icon} ${repo.name ?? repo.path}${identityPart}  ${chalk10.dim(`(${detail})`)}`);
+    }
+    printBox(`Workspace: ${wsManifest.name} (${wsManifest.repos.length} repos)`, wsLines, "info");
+  }
+  if (manifest.workspace) {
+    const wsInfo = [
+      `Managed by workspace at ${chalk10.bold(manifest.workspace.rootPath)}`,
+      `Last synced: ${manifest.workspace.lastSync ? new Date(manifest.workspace.lastSync).toLocaleString() : "never"}`
+    ];
+    printBox("Workspace member", wsInfo, "info");
+  }
 }
 
 // src/cli/index.ts
@@ -6117,15 +7953,67 @@ program.name("hatch3r").description(
 program.command("init").description("Install a complete agent setup into the current repo").option(
   "--tools <tools>",
   `Comma-separated tools (${TOOL_CHOICES})`
-).option("--yes", "Skip interactive prompts, use defaults").option("--preset <preset>", "Content preset: minimal, standard, full").option("--project-type <type>", "Project type: greenfield, brownfield").option("--team-size <size>", "Team size: solo, team").action(initCommand);
-program.command("sync").description("Re-generate tool outputs from canonical .agents/ state").action(syncCommand);
+).option("--yes", "Skip interactive prompts, use defaults").option("--preset <preset>", "Content preset: minimal, standard, full").option("--project-type <type>", "Project type: greenfield, brownfield").option("--team-size <size>", "Team size: solo, team").option("--workspace", "Initialize as a multi-repo workspace").action(initCommand);
+program.command("sync").description("Re-generate tool outputs from canonical .agents/ state").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("--force", "Overwrite locally modified files in sub-repos").option("--minimal", "Generate stripped-down output (no comments, minimal formatting) to reduce token usage").action(syncCommand);
 program.command("status").description("Check sync status between canonical .agents/ and generated files").action(statusCommand);
-program.command("update").description("Pull latest hatch3r templates with safe merge").action(updateCommand);
+program.command("update").description("Pull latest hatch3r templates with safe merge").option("--yes", "Skip interactive prompts, use defaults").action(updateCommand);
 program.command("validate").description("Validate the canonical .agents/ structure").action(validateCommand);
 program.command("verify").description("Verify integrity of canonical agent files").action(verifyCommand);
 program.command("config").description("Reconfigure tools, MCP servers, features, and platform").action(configCommand);
 program.command("add [pack]").description("Install a community pack (coming soon)").action(addCommand);
 program.command("worktree-setup [worktree-path]").description("Set up gitignored files in a git worktree").option("--from <path>", "Main repo path (auto-detected by default)").option("--dry-run", "Show what would be done without changes").option("--force", "Overwrite existing files in the worktree").action(worktreeSetupCommand);
+var AGENT_COMMAND_NAMES = /* @__PURE__ */ new Set([
+  "review",
+  "workflow",
+  "project-spec",
+  "codebase-map",
+  "debug",
+  "release",
+  "refactor-plan",
+  "test-plan",
+  "bug-plan",
+  "roadmap",
+  "onboard",
+  "recipe",
+  "board-init",
+  "board-pickup",
+  "board-groom",
+  "board-refresh",
+  "security-audit",
+  "dep-audit",
+  "benchmark",
+  "healthcheck",
+  "context-health",
+  "learn",
+  "revision",
+  "cost-tracking",
+  "api-spec",
+  "hooks",
+  "quick-change",
+  "command-customize"
+]);
+program.on("command:*", (operands) => {
+  const cmd = operands[0];
+  if (cmd && AGENT_COMMAND_NAMES.has(cmd)) {
+    console.error(
+      `
+  "${cmd}" is a hatch3r agent command meant to be run inside your AI editor (e.g. /${cmd}).
+  It cannot be invoked from the terminal CLI.
+
+  To use agent commands, open your project in Cursor, Claude Code, or another supported tool
+  and type /${cmd} in the AI chat.
+`
+    );
+  } else {
+    console.error(
+      `
+  Unknown command: ${cmd}
+  Run "hatch3r --help" for available commands.
+`
+    );
+  }
+  process.exit(1);
+});
 var nodeVersion = parseInt(process.version.slice(1), 10);
 if (nodeVersion < 22) {
   console.error(