@haus-tech/haus-workflow 1.5.6 → 1.6.0

package/dist/cli.js

@@ -29,12 +29,15 @@ async function runCommand(command, args = [], options = {}) {
       // non-zero exits are returned, not thrown
       ...options
     });
+    const killed = result.timedOut === true || result.isCanceled === true || Boolean(result.signal);
     return {
       command,
       args,
       stdout: String(result.stdout ?? ""),
-      stderr: String(result.stderr ?? ""),
-      exitCode: result.exitCode ?? 0
+      stderr: String(
+        result.stderr ?? (result.timedOut === true ? `timed out after ${options.timeout}ms` : "")
+      ),
+      exitCode: result.exitCode ?? (killed || result.failed === true ? 1 : 0)
     };
   } catch (error2) {
     const message = error2 instanceof Error ? error2.message : String(error2);
@@ -44,9 +47,9 @@ async function runCommand(command, args = [], options = {}) {
 async function runGit(args, options = {}) {
   return runCommand("git", args, options);
 }
-async function commandExists(command) {
+async function commandExists(command, timeoutMs = 1e4) {
   try {
-    const result = await runCommand(command, ["--version"]);
+    const result = await runCommand(command, ["--version"], { timeout: timeoutMs });
     return result.exitCode === 0;
   } catch {
     return false;
@@ -60,11 +63,11 @@ var init_exec = __esm({
 
 // src/cli.ts
 import { readFileSync as readFileSync5 } from "node:fs";
-import path72 from "node:path";
+import path73 from "node:path";
 import { Command } from "commander";
 
 // src/commands/apply.ts
-import path24 from "node:path";
+import path25 from "node:path";
 import checkbox from "@inquirer/checkbox";
 
 // src/catalog/load-catalog.ts
@@ -216,6 +219,11 @@ function hausPath(root, ...parts) {
 function claudePath(root, ...parts) {
   return path2.join(root, ".claude", ...parts);
 }
+function claudeConfigDir() {
+  const override = process.env.CLAUDE_CONFIG_DIR;
+  if (override && override.trim().length > 0) return override;
+  return path2.join(os.homedir(), ".claude");
+}
 function displayPath(root, targetPath) {
   const rel = path2.relative(root, targetPath).replace(/\\/g, "/");
   if (rel && !rel.startsWith("../") && rel !== "..") {
@@ -894,7 +902,15 @@ function parseManifest(json) {
   if (formerIdFailures.length > 0) {
     return { ok: false, error: formerIdFailures[0] };
   }
-  return { ok: true, manifest: { version: root.version, items }, warnings };
+  return {
+    ok: true,
+    manifest: {
+      version: root.version,
+      items,
+      ...root.globalPlugins !== void 0 ? { globalPlugins: root.globalPlugins } : {}
+    },
+    warnings
+  };
 }
 
 // src/catalog/remote-catalog/manifest.ts
@@ -944,8 +960,6 @@ var validation_rules_default = {
     "java",
     "spring",
     "kotlin",
-    "swift",
-    "android",
     "flutter",
     "dart",
     "c++",
@@ -1167,6 +1181,16 @@ function extractUseWhenSection(text) {
   const next = tail.search(/\n##\s+/);
   return next < 0 ? tail : tail.slice(0, next);
 }
+function indentedContinuationLines(lines, idx) {
+  const out = [];
+  for (let j = idx + 1; j < lines.length; j++) {
+    const line2 = lines[j];
+    if (line2.trim() === "") continue;
+    if (!/^\s+\S/.test(line2)) break;
+    out.push(line2.trim());
+  }
+  return out;
+}
 function isYamlBlockScalarHeader(rest) {
   return /^[>|][-+]?(\d+)?(?:\s+#.*)?$/.test(rest);
 }
@@ -1180,7 +1204,7 @@ function extractFrontmatterValue(text, key) {
   const rest = lines[idx].replace(keyRe, "").trim();
   if (!rest) return "";
   if (!isYamlBlockScalarHeader(rest)) {
-    return rest.replace(/^["']|["']$/g, "").trim();
+    return [rest, ...indentedContinuationLines(lines, idx)].join(" ").replace(/\s+/g, " ").replace(/^["']|["']$/g, "").trim();
   }
   const body = [];
   for (let j = idx + 1; j < lines.length; j++) {
@@ -1192,11 +1216,20 @@ function extractFrontmatterValue(text, key) {
   }
   return body.join(" ").replace(/\s+/g, " ").trim();
 }
-function extractFrontmatterDescription(text) {
-  return extractFrontmatterValue(text, "description");
+function frontmatterDescriptionRegion(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return "";
+  const lines = m[1].split(/\r?\n/);
+  const idx = lines.findIndex((l) => /^description:[ \t]*/.test(l));
+  if (idx < 0) return "";
+  const region = [
+    lines[idx].replace(/^description:[ \t]*/, ""),
+    ...indentedContinuationLines(lines, idx)
+  ];
+  return region.join(" ").replace(/\s+/g, " ").trim();
 }
 function auditForbiddenTagsInText(text, label) {
-  const body = `${extractFrontmatterDescription(text)}
+  const body = `${frontmatterDescriptionRegion(text)}
 ${extractUseWhenSection(text)}`;
   if (!body.trim()) return [];
   const failures = [];
@@ -1467,13 +1500,16 @@ async function syncRemoteCatalog() {
     warn("Remote catalog fetch failed \u2014 using bundled catalog");
     return { newItems: [], refreshed: [], unchanged: 0, failed: [] };
   }
-  const { version, items } = manifest;
+  const { version, items, globalPlugins } = manifest;
   const cacheDir = getCacheDir();
   try {
     await fs6.ensureDir(cacheDir);
     await fs6.writeFile(
       path8.join(cacheDir, "manifest.json"),
-      `${JSON.stringify({ version, items }, null, 2)}
+      // globalPlugins must round-trip into the cache: the cache is what `haus update`
+      // and `haus refresh` read pins from, so dropping it here would make every
+      // catalog pin bump invisible and pin resolution fall back to the bundled default.
+      `${JSON.stringify({ version, items, ...globalPlugins !== void 0 ? { globalPlugins } : {} }, null, 2)}
 `,
       "utf8"
     );
@@ -1527,14 +1563,20 @@ async function loadCatalogContext(root) {
     return {
       items: data2?.items ?? [],
       contentRoot: path9.dirname(envPath),
-      source: "fixture"
+      source: "fixture",
+      globalPlugins: data2?.globalPlugins
     };
   }
   const cacheDir = getCacheDir();
   const cacheManifestPath = path9.join(cacheDir, "manifest.json");
   const cacheData = await readJson(cacheManifestPath);
   if (cacheData?.items?.length) {
-    return { items: cacheData.items, contentRoot: cacheDir, source: "cache" };
+    return {
+      items: cacheData.items,
+      contentRoot: cacheDir,
+      source: "cache",
+      globalPlugins: cacheData.globalPlugins
+    };
   }
   const localManifest = path9.join(root, "library/catalog/manifest.json");
   const localData = await readJson(localManifest);
@@ -1542,7 +1584,8 @@ async function loadCatalogContext(root) {
     return {
       items: localData.items,
       contentRoot: path9.dirname(localManifest),
-      source: "local"
+      source: "local",
+      globalPlugins: localData.globalPlugins
     };
   }
   const packageManifest = path9.join(packageRoot(), "library/catalog/manifest.json");
@@ -1550,7 +1593,8 @@ async function loadCatalogContext(root) {
   return {
     items: data?.items ?? [],
     contentRoot: path9.dirname(packageManifest),
-    source: "bundled"
+    source: "bundled",
+    globalPlugins: data?.globalPlugins
   };
 }
 async function loadCatalog(root) {
@@ -1840,6 +1884,26 @@ function mergeRecommendationWarnings(context, isLinkedWorktree = false) {
   return [.../* @__PURE__ */ new Set([...statusLines, ...context.warnings, ...riskLines])];
 }
 
+// src/recommender/superseded-by-plugin.ts
+var RULES = [
+  {
+    pinId: "superpowers",
+    originSourceId: "superpowers-pcvelz",
+    idPrefix: "haus.superpowers-"
+  }
+];
+function isItemSupersededByPlugin(item, activePinIds) {
+  if (item.originSourceId === void 0) return false;
+  return RULES.some(
+    (rule) => activePinIds.includes(rule.pinId) && rule.originSourceId === item.originSourceId
+  );
+}
+function isSupersededByPlugin(lockId, activePinIds) {
+  return RULES.some(
+    (rule) => (activePinIds === void 0 || activePinIds.includes(rule.pinId)) && lockId.startsWith(rule.idPrefix)
+  );
+}
+
 // src/update/hash-installed.ts
 import path11 from "node:path";
 import fg2 from "fast-glob";
@@ -2008,13 +2072,22 @@ async function readManifest() {
 async function writeManifest(manifest) {
   await writeJson(hausManifestPath(), manifest);
 }
-function buildManifest(source, files, hooks) {
+async function recordManifestPlugins(plugins) {
+  if (plugins.length === 0) return;
+  const manifest = await readManifest();
+  if (!manifest) return;
+  const byId = new Map((manifest.plugins ?? []).map((p) => [p.id, p]));
+  for (const plugin of plugins) byId.set(plugin.id, plugin);
+  await writeManifest({ ...manifest, plugins: [...byId.values()] });
+}
+function buildManifest(source, files, hooks, plugins) {
   return {
     _schema: MANIFEST_SCHEMA,
     source,
     installedAt: (/* @__PURE__ */ new Date()).toISOString(),
     files,
-    hooks
+    hooks,
+    ...plugins && plugins.length > 0 ? { plugins } : {}
   };
 }
 
@@ -2270,8 +2343,8 @@ function buildDenyRules() {
   for (const command of DENY_COMMANDS) {
     rules.push(`Bash(${command}:*)`);
   }
-  for (const path73 of DENY_PATHS) {
-    const pattern = DENY_DIRS.has(path73) ? `${path73}/**` : path73;
+  for (const path74 of DENY_PATHS) {
+    const pattern = DENY_DIRS.has(path74) ? `${path74}/**` : path74;
     for (const tool of FILE_TOOLS) {
       rules.push(`${tool}(${pattern})`);
     }
@@ -2354,6 +2427,7 @@ import path14 from "node:path";
 import fg3 from "fast-glob";
 import fs10 from "fs-extra";
 var SUPERPOWERS_ORIGIN_SOURCE_ID = "superpowers-pcvelz";
+var SUPERPOWERS_SHARED_INSTALL_REL = ".claude/skills/shared";
 var PATH_REWRITES = [
   ["skills/shared/", ".claude/skills/shared/"]
 ];
@@ -3229,6 +3303,10 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
       warn(`Skipping ${item.id}: reviewStatus is deprecated`);
       continue;
     }
+    if (isItemSupersededByPlugin(manifestItem, opts.activePluginIds ?? [])) {
+      warn(`Skipping ${item.id}: provided by an installed global plugin`);
+      continue;
+    }
     const manifestItemTags = (manifestItem.tags ?? []).map((t) => t.toLowerCase());
     if (UNSUPPORTED.some((x) => manifestItemTags.includes(x))) {
       warn(`Skipping ${item.id}: unsupported stack policy`);
@@ -3354,7 +3432,13 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
       `${curatedReviewStatusSkips} curated items skipped: reviewStatus is not approved \u2014 possible catalog field rename upstream`
     );
   }
-  await cleanupStaleCatalogItems(root, cleanupManifestById, dryRun, opts.quiet);
+  await cleanupStaleCatalogItems(
+    root,
+    cleanupManifestById,
+    dryRun,
+    opts.quiet,
+    opts.activePluginIds ?? []
+  );
   const refuseDestructiveLockChange = recommendationUnusable && prevLock.length > 0 && !opts.force;
   if (opts.prune) {
     if (refuseDestructiveLockChange) {
@@ -3498,25 +3582,46 @@ async function resolveExistingTrackedPaths(root, itemId, relPaths, warnFn) {
   }
   return existing;
 }
-async function cleanupStaleCatalogItems(root, manifestById, dryRun, quiet) {
+async function cleanupStaleCatalogItems(root, manifestById, dryRun, quiet, activePluginIds = []) {
   const say = quiet ? () => {
   } : log;
   const prevLock = await readJson(hausPath(root, "haus.lock.json"));
   if (!prevLock?.length) return;
+  const supersededEntries = prevLock.filter(
+    (entry) => entry.id && isSupersededByPlugin(entry.id, activePluginIds)
+  );
+  let keepShared = false;
+  for (const entry of supersededEntries) {
+    const relPaths = entry.paths ?? [];
+    if (relPaths.length === 0) continue;
+    const existing = await resolveExistingTrackedPaths(root, entry.id, relPaths, warn);
+    if (existing.length === 0) continue;
+    if (entry.hash === void 0) {
+      keepShared = true;
+      continue;
+    }
+    const currentHash = await hashInstalledPaths(
+      root,
+      existing.map((e) => e.rel)
+    );
+    if (currentHash !== entry.hash) keepShared = true;
+  }
   for (const entry of prevLock) {
     if (!entry.id) continue;
     const manifestItem = manifestById.get(entry.id);
     const removedFromManifest = manifestItem === void 0;
     const deprecated = manifestItem?.reviewStatus === "deprecated";
-    if (!removedFromManifest && !deprecated) continue;
+    const superseded = isSupersededByPlugin(entry.id, activePluginIds);
+    if (!removedFromManifest && !deprecated && !superseded) continue;
     const relPaths = entry.paths ?? [];
     if (relPaths.length === 0) continue;
     const existing = await resolveExistingTrackedPaths(root, entry.id, relPaths, warn);
     if (existing.length === 0) continue;
-    const pruneReason = deprecated ? "deprecated" : "stale";
+    const pruneReason = superseded ? "superseded" : deprecated ? "deprecated" : "stale";
+    const label = superseded ? "Superseded" : deprecated ? "Deprecated" : "Stale";
     if (entry.hash === void 0) {
       warn(
-        `${deprecated ? "Deprecated" : "Stale"} catalog item ${entry.id} has no lock hash \u2014 leaving in place: ${existing.map((e) => e.rel).join(", ")}`
+        `${label} catalog item ${entry.id} has no lock hash \u2014 leaving in place: ${existing.map((e) => e.rel).join(", ")}`
       );
       continue;
     }
@@ -3526,11 +3631,28 @@ async function cleanupStaleCatalogItems(root, manifestById, dryRun, quiet) {
     );
     if (currentHash !== entry.hash) {
       warn(
-        `${deprecated ? "Deprecated" : "Stale"} catalog item ${entry.id} was modified locally \u2014 leaving in place: ${existing.map((e) => e.rel).join(", ")}`
+        `${label} catalog item ${entry.id} was modified locally \u2014 leaving in place${superseded ? " (the global plugin provides it; delete the copy manually if you no longer want it)" : ""}: ${existing.map((e) => e.rel).join(", ")}`
       );
       continue;
     }
-    for (const { abs } of existing) {
+    const removable = superseded ? existing.filter(({ rel }) => {
+      const isShared = rel.split(path20.sep).join("/") === SUPERPOWERS_SHARED_INSTALL_REL;
+      if (isShared && keepShared) {
+        say(
+          `Keeping ${displayPath(root, path20.join(root, rel))} \u2014 a locally-edited superpowers skill still uses it`
+        );
+        return false;
+      }
+      return true;
+    }) : existing;
+    if (superseded && !dryRun && removable.length > 0) {
+      await backupBeforePrune(
+        root,
+        removable.map((e) => e.abs),
+        say
+      );
+    }
+    for (const { abs } of removable) {
       if (dryRun) {
         say(`[dry-run] would remove ${pruneReason} ${displayPath(root, abs)} (${entry.id})`);
         continue;
@@ -3769,16 +3891,431 @@ async function untrackMachineLocalArtifacts(root, dryRun, notify) {
   return untracked;
 }
 
+// src/install/ensure-global-plugins.ts
+import path22 from "node:path";
+init_exec();
+
+// src/install/global-plugins.ts
+var DEFAULT_GLOBAL_PLUGINS = [
+  {
+    id: "superpowers",
+    plugin: "superpowers-extended-cc",
+    marketplace: "superpowers-extended-cc-marketplace",
+    url: "https://github.com/pcvelz/superpowers.git",
+    ref: "v6.4.0"
+  }
+];
+var MANAGED_SCOPE = "user";
+function pluginId(pin) {
+  return `${pin.plugin}@${pin.marketplace}`;
+}
+function canonicalUrl(url) {
+  return url.trim().toLowerCase().replace(/\.git$/, "").replace(/\/+$/, "");
+}
+function isNonEmptyString3(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function normalizeMarketplaceSource(marketplace) {
+  if (marketplace.source === "git" && isNonEmptyString3(marketplace.url)) {
+    return { url: canonicalUrl(marketplace.url), ref: marketplace.ref };
+  }
+  if (marketplace.source === "github" && isNonEmptyString3(marketplace.repo)) {
+    return { url: canonicalUrl(`https://github.com/${marketplace.repo}`), ref: marketplace.ref };
+  }
+  return null;
+}
+function resolveGlobalPlugins(manifest, deps = {}) {
+  const warn2 = deps.warn ?? warn;
+  const declared = manifest?.globalPlugins;
+  if (declared === void 0) return [...DEFAULT_GLOBAL_PLUGINS];
+  if (!Array.isArray(declared)) {
+    warn2("Catalog `globalPlugins` is not an array \u2014 falling back to the bundled pin.");
+    return [...DEFAULT_GLOBAL_PLUGINS];
+  }
+  const pins = [];
+  for (const entry of declared) {
+    if (!isValidPin(entry)) {
+      const label = entry !== null && typeof entry === "object" && isNonEmptyString3(entry.id) ? entry.id : JSON.stringify(entry);
+      warn2(`Skipping malformed catalog globalPlugins entry: ${label}`);
+      continue;
+    }
+    if (!isImmutableRef(entry.ref)) {
+      warn2(
+        `Refusing catalog pin ${entry.id}: ref "${entry.ref}" is not a release tag \u2014 haus only installs immutable, reviewed plugin content.`
+      );
+      continue;
+    }
+    pins.push({
+      id: entry.id,
+      plugin: entry.plugin,
+      marketplace: entry.marketplace,
+      url: entry.url,
+      ref: entry.ref
+    });
+  }
+  return pins;
+}
+function isValidPin(entry) {
+  if (entry === null || typeof entry !== "object") return false;
+  const candidate = entry;
+  return isNonEmptyString3(candidate.id) && isNonEmptyString3(candidate.plugin) && isNonEmptyString3(candidate.marketplace) && isNonEmptyString3(candidate.url) && isNonEmptyString3(candidate.ref);
+}
+var RELEASE_TAG = /^v?\d+(\.\d+)*([-+][0-9A-Za-z.-]+)?$/;
+function isImmutableRef(ref) {
+  return RELEASE_TAG.test(ref.trim());
+}
+function findManagedInstall(state, pin) {
+  const id = pluginId(pin);
+  return state.installed.find((p) => p.id === id && (p.scope ?? MANAGED_SCOPE) === MANAGED_SCOPE);
+}
+function isPluginActive(state, pin) {
+  if (!state.available) return false;
+  const id = pluginId(pin);
+  return state.installed.some((p) => p.id === id && p.enabled !== false);
+}
+function planPluginActions(desired, state) {
+  return desired.map((pin) => planOne(pin, state));
+}
+function planOne(pin, state) {
+  if (!state.available) {
+    return {
+      pin,
+      kind: "unavailable",
+      steps: [],
+      reason: "the `claude` CLI is not on PATH \u2014 plugin state is unknown"
+    };
+  }
+  const marketplace = state.marketplaces.find((m) => m.name === pin.marketplace);
+  const normalized = marketplace ? normalizeMarketplaceSource(marketplace) : null;
+  const marketplaceMatches = normalized !== null && normalized.url === canonicalUrl(pin.url) && normalized.ref === pin.ref;
+  const installed = findManagedInstall(state, pin);
+  const disabled = installed?.enabled === false;
+  const enableStep = disabled ? ["plugin-enable"] : [];
+  if (!installed) {
+    const steps = marketplaceMatches ? ["plugin-install"] : ["marketplace-add", "plugin-install"];
+    return {
+      pin,
+      kind: "install",
+      steps,
+      reason: marketplace ? `plugin ${pluginId(pin)} is not installed at ${MANAGED_SCOPE} scope` : `marketplace ${pin.marketplace} is not configured`
+    };
+  }
+  if (!marketplaceMatches) {
+    return {
+      pin,
+      kind: "repin",
+      steps: [
+        "marketplace-add",
+        "marketplace-update",
+        "plugin-uninstall",
+        "plugin-install",
+        ...enableStep
+      ],
+      reason: `marketplace ${pin.marketplace} does not track the pinned ref ${pin.ref}`,
+      ...normalized?.ref !== void 0 ? { overriddenRef: normalized.ref } : {}
+    };
+  }
+  const versionsDiffer = isNonEmptyString3(marketplace?.pluginVersion) && isNonEmptyString3(installed.version) && marketplace.pluginVersion !== installed.version;
+  if (versionsDiffer) {
+    return {
+      pin,
+      kind: "repin",
+      steps: ["marketplace-update", "plugin-uninstall", "plugin-install", ...enableStep],
+      reason: `installed ${installed.version} does not match marketplace ${marketplace?.pluginVersion} at ref ${pin.ref}`
+    };
+  }
+  if (disabled) {
+    return {
+      pin,
+      kind: "re-enable",
+      steps: ["plugin-enable"],
+      reason: `plugin ${pluginId(pin)} is disabled \u2014 haus workflows depend on it`
+    };
+  }
+  return { pin, kind: "up-to-date", steps: [], reason: `pinned to ${pin.ref}` };
+}
+function pluginDriftStatus(actions, opts) {
+  if (actions.length === 0) return false;
+  if (actions.some((a) => a.kind === "unavailable")) return null;
+  return actions.some((a) => {
+    if (a.kind === "install" || a.kind === "re-enable") return true;
+    if (a.kind === "repin") return opts.matchRef;
+    return false;
+  });
+}
+
+// src/install/ensure-global-plugins.ts
+async function loadCatalogPluginPins(root) {
+  const ctx = await loadCatalogContext(root);
+  return resolveGlobalPlugins({ globalPlugins: ctx.globalPlugins });
+}
+async function activeGlobalPluginIds(root, deps = {}) {
+  try {
+    const [pins, state] = await Promise.all([loadCatalogPluginPins(root), probePluginEnv(deps)]);
+    if (!state.available) return [];
+    return pins.filter((pin) => isPluginActive(state, pin)).map((pin) => pin.id);
+  } catch {
+    return [];
+  }
+}
+var EXEC_TIMEOUT_MS = 12e4;
+var EXEC_ENV = { GIT_TERMINAL_PROMPT: "0" };
+function globalPluginsDisabled() {
+  return process.env.HAUS_NO_GLOBAL_PLUGINS === "1";
+}
+var realExec = (args) => runCommand("claude", args, {
+  timeout: EXEC_TIMEOUT_MS,
+  env: EXEC_ENV,
+  extendEnv: true
+});
+function parseInstalled(stdout) {
+  try {
+    const parsed = JSON.parse(stdout);
+    const list = Array.isArray(parsed) ? parsed : parsed !== null && typeof parsed === "object" ? parsed.installed : void 0;
+    if (!Array.isArray(list)) return null;
+    return list.flatMap((entry) => {
+      const item = entry;
+      if (typeof item.id !== "string") return [];
+      return [
+        {
+          id: item.id,
+          ...typeof item.version === "string" ? { version: item.version } : {},
+          ...typeof item.scope === "string" ? { scope: item.scope } : {},
+          ...typeof item.enabled === "boolean" ? { enabled: item.enabled } : {}
+        }
+      ];
+    });
+  } catch {
+    return null;
+  }
+}
+async function readMarketplaceRefs(configDir) {
+  const settings = await readJson(path22.join(configDir, "settings.json"));
+  const out = {};
+  for (const [name, entry] of Object.entries(settings?.extraKnownMarketplaces ?? {})) {
+    const ref = entry?.source?.ref;
+    out[name] = typeof ref === "string" ? ref : void 0;
+  }
+  return out;
+}
+async function readClonedPluginVersion(installLocation) {
+  const manifest = await readJson(
+    path22.join(installLocation, ".claude-plugin", "plugin.json")
+  );
+  return typeof manifest?.version === "string" ? manifest.version : void 0;
+}
+async function parseMarketplaces(stdout, configDir) {
+  let rows = [];
+  try {
+    const parsed = JSON.parse(stdout);
+    if (!Array.isArray(parsed)) return null;
+    rows = parsed;
+  } catch {
+    return null;
+  }
+  const refs = await readMarketplaceRefs(configDir);
+  const out = [];
+  for (const row of rows) {
+    if (typeof row.name !== "string") continue;
+    const installLocation = typeof row.installLocation === "string" ? row.installLocation : void 0;
+    out.push({
+      name: row.name,
+      ...typeof row.source === "string" ? { source: row.source } : {},
+      ...typeof row.url === "string" ? { url: row.url } : {},
+      ...typeof row.repo === "string" ? { repo: row.repo } : {},
+      ...refs[row.name] !== void 0 ? { ref: refs[row.name] } : {},
+      ...installLocation ? { pluginVersion: await readClonedPluginVersion(installLocation) } : {}
+    });
+  }
+  return out;
+}
+async function probePluginEnv(deps = {}) {
+  const exec = deps.exec ?? realExec;
+  const isAvailable = deps.isAvailable ?? (() => commandExists("claude"));
+  const warn2 = deps.warn ?? warn;
+  if (globalPluginsDisabled() && deps.exec === void 0) {
+    return { available: false, installed: [], marketplaces: [] };
+  }
+  if (!await isAvailable()) return { available: false, installed: [], marketplaces: [] };
+  const [listed, markets] = await Promise.all([
+    exec(["plugin", "list", "--json"]),
+    exec(["plugin", "marketplace", "list", "--json"])
+  ]);
+  if (listed.exitCode !== 0 || markets.exitCode !== 0) {
+    warn2(
+      `Could not read Claude Code plugin state (${listed.exitCode !== 0 ? "plugin list" : "marketplace list"} exited ${listed.exitCode !== 0 ? listed.exitCode : markets.exitCode}) \u2014 leaving global plugins untouched.`
+    );
+    return { available: false, installed: [], marketplaces: [] };
+  }
+  const configDir = deps.configDir ?? claudeConfigDir();
+  const installed = parseInstalled(listed.stdout);
+  const marketplaces = await parseMarketplaces(markets.stdout, configDir);
+  if (installed === null || marketplaces === null) {
+    warn2("Claude Code returned unreadable plugin state \u2014 leaving global plugins untouched.");
+    return { available: false, installed: [], marketplaces: [] };
+  }
+  return { available: true, installed, marketplaces };
+}
+function stepArgs(step, pin) {
+  const id = pluginId(pin);
+  switch (step) {
+    case "marketplace-add":
+      return ["plugin", "marketplace", "add", `${pin.url}#${pin.ref}`, "--scope", "user"];
+    case "marketplace-update":
+      return ["plugin", "marketplace", "update", pin.marketplace];
+    case "plugin-uninstall":
+      return ["plugin", "uninstall", id, "--scope", "user"];
+    case "plugin-install":
+      return ["plugin", "install", id, "--scope", "user"];
+    case "plugin-update":
+      return ["plugin", "update", id, "--scope", "user"];
+    case "plugin-enable":
+      return ["plugin", "enable", id, "--scope", "user"];
+  }
+}
+var RESTART_STEPS = /* @__PURE__ */ new Set([
+  "plugin-uninstall",
+  "plugin-install",
+  "plugin-update",
+  "plugin-enable"
+]);
+function manualCommands(pin) {
+  return [
+    `claude plugin marketplace add ${pin.url}#${pin.ref}`,
+    `claude plugin install ${pluginId(pin)}`
+  ];
+}
+async function ensureGlobalPlugins(pins, deps = {}) {
+  const exec = deps.exec ?? realExec;
+  const log2 = deps.log ?? log;
+  const warn2 = deps.warn ?? warn;
+  const dryRun = deps.dryRun ?? false;
+  if (globalPluginsDisabled() && deps.exec === void 0) {
+    return { actions: [], ensured: [], failed: [], unavailable: true, restartRequired: false };
+  }
+  const state = await probePluginEnv(deps);
+  const actions = planPluginActions(pins, state);
+  const result = {
+    actions,
+    ensured: [],
+    failed: [],
+    unavailable: !state.available,
+    restartRequired: false
+  };
+  for (const action of actions) {
+    if (action.kind === "unavailable") {
+      warn2(
+        `Claude Code CLI not found \u2014 cannot manage the ${action.pin.id} plugin. Install it manually:`
+      );
+      manualCommands(action.pin).forEach((cmd) => warn2(`  ${cmd}`));
+      continue;
+    }
+    if (action.kind === "up-to-date") {
+      result.ensured.push(action.pin.id);
+      continue;
+    }
+    if (action.overriddenRef !== void 0 && action.overriddenRef !== action.pin.ref) {
+      warn2(
+        `Re-pointing marketplace ${action.pin.marketplace} from ${action.overriddenRef} to the haus-pinned ${action.pin.ref} \u2014 haus manages this plugin's version.`
+      );
+    }
+    if (dryRun) {
+      log2(`[dry-run] would ${action.kind} ${action.pin.id}: ${action.reason}`);
+      action.steps.forEach(
+        (step) => log2(`[dry-run]   claude ${stepArgs(step, action.pin).join(" ")}`)
+      );
+      continue;
+    }
+    let ok = true;
+    for (const step of action.steps) {
+      const args = stepArgs(step, action.pin);
+      const run = await exec(args);
+      if (run.exitCode !== 0) {
+        ok = false;
+        warn2(`\`claude ${args.join(" ")}\` failed: ${run.stderr.trim() || `exit ${run.exitCode}`}`);
+        break;
+      }
+      if (RESTART_STEPS.has(step)) result.restartRequired = true;
+    }
+    if (ok) {
+      result.ensured.push(action.pin.id);
+      log2(
+        `Global plugin ${action.pin.id} ${action.kind === "install" ? "installed" : "updated"} (${action.pin.ref}).`
+      );
+    } else {
+      result.failed.push(action.pin.id);
+      warn2(`Could not set up the ${action.pin.id} plugin. Run manually:`);
+      manualCommands(action.pin).forEach((cmd) => warn2(`  ${cmd}`));
+    }
+  }
+  if (result.restartRequired && !dryRun) {
+    log2("Restart Claude Code to load the updated plugin.");
+  }
+  return result;
+}
+async function removeGlobalPlugins(plugins, deps = {}) {
+  const exec = deps.exec ?? realExec;
+  const warn2 = deps.warn ?? warn;
+  const log2 = deps.log ?? log;
+  const result = { removed: [], failed: [], unavailable: false };
+  if (plugins.length === 0) return result;
+  if (globalPluginsDisabled() && deps.exec === void 0) {
+    return { ...result, unavailable: true };
+  }
+  const state = await probePluginEnv(deps);
+  if (!state.available) {
+    result.unavailable = true;
+    warn2("Claude Code CLI not found \u2014 leaving the haus-managed global plugin(s) in place.");
+    return result;
+  }
+  const scopeKey = (id, scope) => `${id}@@${scope ?? "user"}`;
+  const stillInstalled = new Set(state.installed.map((p) => scopeKey(p.id, p.scope)));
+  for (const pin of plugins) {
+    const id = pluginId(pin);
+    const managedKey = scopeKey(id, "user");
+    if (deps.dryRun) {
+      if (stillInstalled.has(managedKey))
+        log2(`[dry-run] would remove global plugin ${pin.id} (${id})`);
+      continue;
+    }
+    if (stillInstalled.has(managedKey)) {
+      const uninstalled = await exec(["plugin", "uninstall", id, "--scope", "user"]);
+      if (uninstalled.exitCode !== 0) {
+        result.failed.push(pin.id);
+        warn2(
+          `Could not remove plugin ${id}: ${uninstalled.stderr.trim() || `exit ${uninstalled.exitCode}`}`
+        );
+        continue;
+      }
+      stillInstalled.delete(managedKey);
+      result.removed.push(pin.id);
+    }
+    const marketplaceStillConfigured = state.marketplaces.some((m) => m.name === pin.marketplace);
+    const othersFromMarketplace = [...stillInstalled].some(
+      (key) => key.split("@@")[0]?.endsWith(`@${pin.marketplace}`)
+    );
+    if (marketplaceStillConfigured && !othersFromMarketplace) {
+      const removedMarket = await exec(["plugin", "marketplace", "remove", pin.marketplace]);
+      if (removedMarket.exitCode !== 0) {
+        warn2(
+          `Could not remove marketplace ${pin.marketplace}: ${removedMarket.stderr.trim() || `exit ${removedMarket.exitCode}`}`
+        );
+      }
+    }
+  }
+  return result;
+}
+
 // src/refs/fetch-refs.ts
-import path23 from "node:path";
+import path24 from "node:path";
 import fs21 from "fs-extra";
 
 // src/refs/cache-meta.ts
-import path22 from "node:path";
+import path23 from "node:path";
 import fs20 from "fs-extra";
 var META_FILENAME = "cache-meta.json";
 async function readCacheMeta(cacheDir) {
-  const metaPath = path22.join(cacheDir, META_FILENAME);
+  const metaPath = path23.join(cacheDir, META_FILENAME);
   try {
     const raw = await fs20.readFile(metaPath, "utf8");
     return JSON.parse(raw);
@@ -3788,7 +4325,7 @@ async function readCacheMeta(cacheDir) {
 }
 async function writeCacheMeta(cacheDir, meta) {
   await fs20.ensureDir(cacheDir);
-  const metaPath = path22.join(cacheDir, META_FILENAME);
+  const metaPath = path23.join(cacheDir, META_FILENAME);
   await fs20.writeFile(metaPath, JSON.stringify(meta, null, 2) + "\n", "utf8");
 }
 
@@ -3809,8 +4346,8 @@ function isLlmsTxtUrl(ref) {
 async function fetchSingleRef(url, cacheDir, meta) {
   const existing = meta[url];
   const headers = {};
-  const safeFile = existing?.file && existing.file === path23.basename(existing.file);
-  const cachedFileExists = safeFile && await fs21.pathExists(path23.join(cacheDir, existing.file));
+  const safeFile = existing?.file && existing.file === path24.basename(existing.file);
+  const cachedFileExists = safeFile && await fs21.pathExists(path24.join(cacheDir, existing.file));
   if (cachedFileExists) {
     if (existing?.etag) headers["If-None-Match"] = existing.etag;
     if (existing?.lastModified) headers["If-Modified-Since"] = existing.lastModified;
@@ -3822,7 +4359,7 @@ async function fetchSingleRef(url, cacheDir, meta) {
     const text = await res.text();
     const file = `${urlToSlug(url)}.md`;
     await fs21.ensureDir(cacheDir);
-    await fs21.writeFile(path23.join(cacheDir, file), text, "utf8");
+    await fs21.writeFile(path24.join(cacheDir, file), text, "utf8");
     meta[url] = {
       url,
       etag: res.headers.get("etag") ?? void 0,
@@ -3845,8 +4382,8 @@ async function pruneOrphanedRefs(cacheDir, keepUrls) {
     if (keepUrls.has(url)) continue;
     delete meta[url];
     removed++;
-    const safeFile = typeof entry.file === "string" && entry.file === path23.basename(entry.file);
-    if (safeFile) await fs21.remove(path23.join(cacheDir, entry.file)).catch(() => {
+    const safeFile = typeof entry.file === "string" && entry.file === path24.basename(entry.file);
+    if (safeFile) await fs21.remove(path24.join(cacheDir, entry.file)).catch(() => {
     });
   }
   if (removed > 0) await writeCacheMeta(cacheDir, meta);
@@ -3868,10 +4405,10 @@ async function fetchRefsForItems(items, cacheDir) {
       const outcome = await fetchSingleRef(url, cacheDir, meta);
       if (outcome.result === "fetched") {
         summary.fetched++;
-        summary.cachedFiles[url] = path23.join(cacheDir, outcome.file);
+        summary.cachedFiles[url] = path24.join(cacheDir, outcome.file);
       } else if (outcome.result === "unchanged") {
         summary.unchanged++;
-        if (meta[url]?.file) summary.cachedFiles[url] = path23.join(cacheDir, meta[url].file);
+        if (meta[url]?.file) summary.cachedFiles[url] = path24.join(cacheDir, meta[url].file);
       } else {
         summary.failed++;
         summary.failedUrls.push(url);
@@ -3890,11 +4427,17 @@ function parseIdList(value) {
   const raw = Array.isArray(value) ? value : [value];
   return raw.flatMap((v) => v.split(",")).map((v) => v.trim()).filter((v) => v.length > 0);
 }
+function normalizeOnly(only) {
+  if (!only) return void 0;
+  const list = Array.isArray(only) ? only : only.split(/[\s,]+/);
+  const cleaned = list.map((s) => s.trim()).filter(Boolean);
+  return cleaned.length > 0 ? cleaned : void 0;
+}
 
 // src/commands/apply.ts
 var STALE_CACHE_THRESHOLD_DAYS = 7;
 async function cacheHasItems() {
-  const data = await readJson(path24.join(getCacheDir(), "manifest.json"));
+  const data = await readJson(path25.join(getCacheDir(), "manifest.json"));
   return Array.isArray(data?.items) && data.items.length > 0;
 }
 function installableRecommendedItems(recommended) {
@@ -3998,7 +4541,9 @@ async function runApply(options) {
   const files = await writeClaudeFiles(root, isDryRun, selectedIds, {
     refillConfig: options.refillConfig,
     force: options.force,
-    prune: options.prune
+    prune: options.prune,
+    // Copies a global plugin already provides are removed here (issue #272).
+    activePluginIds: await activeGlobalPluginIds(root)
   });
   await writeGitignore(root, isDryRun);
   await untrackMachineLocalArtifacts(root, isDryRun, warn);
@@ -4045,7 +4590,7 @@ async function runApply(options) {
 }
 
 // src/commands/backups.ts
-import path25 from "node:path";
+import path26 from "node:path";
 import fs22 from "fs-extra";
 
 // src/utils/prompts.ts
@@ -4082,7 +4627,7 @@ async function listBackups(root) {
   for (const name of names) {
     const kind = classify(name);
     if (!kind) continue;
-    const absPath = path25.join(dir, name);
+    const absPath = path26.join(dir, name);
     const stat = await fs22.lstat(absPath);
     if (stat.isSymbolicLink()) continue;
     const expectDirectory = kind !== "lock";
@@ -4112,10 +4657,10 @@ async function runList(root) {
   }
 }
 async function isUnsafeWriteTarget(root, target) {
-  const segments = path25.relative(root, target).split(path25.sep).filter(Boolean);
+  const segments = path26.relative(root, target).split(path26.sep).filter(Boolean);
   let current = root;
   for (let i = 0; i < segments.length; i++) {
-    current = path25.join(current, segments[i]);
+    current = path26.join(current, segments[i]);
     const isLastSegment = i === segments.length - 1;
     try {
       const stat = await fs22.lstat(current);
@@ -4179,7 +4724,7 @@ async function collectFilesRecursive(dir) {
   const skippedOther = [];
   const names = await fs22.readdir(dir);
   for (const name of names) {
-    const abs = path25.join(dir, name);
+    const abs = path26.join(dir, name);
     const stat = await fs22.lstat(abs);
     if (stat.isSymbolicLink()) {
       skippedLinks.push(abs);
@@ -4202,12 +4747,12 @@ async function restoreDirBackup(root, entry, yes) {
   const { files, skippedLinks, skippedOther } = await collectFilesRecursive(entry.absPath);
   if (skippedLinks.length > 0) {
     warn(
-      `Skipped ${skippedLinks.length} symlink(s) inside backup ${entry.id} \u2014 never followed: ${skippedLinks.map((abs) => path25.relative(entry.absPath, abs)).join(", ")}`
+      `Skipped ${skippedLinks.length} symlink(s) inside backup ${entry.id} \u2014 never followed: ${skippedLinks.map((abs) => path26.relative(entry.absPath, abs)).join(", ")}`
     );
   }
   if (skippedOther.length > 0) {
     warn(
-      `Skipped ${skippedOther.length} non-regular file(s) inside backup ${entry.id} (not restorable): ${skippedOther.map((abs) => path25.relative(entry.absPath, abs)).join(", ")}`
+      `Skipped ${skippedOther.length} non-regular file(s) inside backup ${entry.id} (not restorable): ${skippedOther.map((abs) => path26.relative(entry.absPath, abs)).join(", ")}`
     );
   }
   if (files.length === 0) {
@@ -4217,8 +4762,8 @@ async function restoreDirBackup(root, entry, yes) {
   const safeFiles = [];
   const unsafeTargets = [];
   for (const abs of files) {
-    const rel = path25.relative(entry.absPath, abs);
-    const target = path25.join(root, rel);
+    const rel = path26.relative(entry.absPath, abs);
+    const target = path26.join(root, rel);
     if (await isUnsafeWriteTarget(root, target)) unsafeTargets.push(rel);
     else safeFiles.push(abs);
   }
@@ -4235,14 +4780,14 @@ async function restoreDirBackup(root, entry, yes) {
   const vanished = [];
   const toRestore = [];
   for (const abs of safeFiles) {
-    const rel = path25.relative(entry.absPath, abs);
+    const rel = path26.relative(entry.absPath, abs);
     const backupFileStat = await lstatIfRegularFile(abs);
     if (!backupFileStat) {
       vanished.push(rel);
       continue;
     }
     toRestore.push(abs);
-    const target = path25.join(root, rel);
+    const target = path26.join(root, rel);
     if (await fs22.pathExists(target)) {
       const targetStat = await fs22.stat(target);
       if (targetStat.mtimeMs > backupFileStat.mtimeMs) {
@@ -4283,13 +4828,13 @@ async function restoreDirBackup(root, entry, yes) {
   let restoredCount = 0;
   const skippedAtWrite = [];
   for (const abs of toRestore) {
-    const rel = path25.relative(entry.absPath, abs);
-    const target = path25.join(root, rel);
+    const rel = path26.relative(entry.absPath, abs);
+    const target = path26.join(root, rel);
     if (!await lstatIfRegularFile(abs) || await isUnsafeWriteTarget(root, target)) {
       skippedAtWrite.push(rel);
       continue;
     }
-    await fs22.ensureDir(path25.dirname(target));
+    await fs22.ensureDir(path26.dirname(target));
     await fs22.copy(abs, target, { overwrite: true });
     restoredCount++;
   }
@@ -4428,18 +4973,19 @@ async function runCatalogAudit() {
 }
 
 // src/commands/doctor.ts
-import path39 from "node:path";
+import path40 from "node:path";
 import fs30 from "fs-extra";
 
 // src/claude/skill-reference-check.ts
-import path26 from "node:path";
+import path27 from "node:path";
 import fg4 from "fast-glob";
 import fs23 from "fs-extra";
 var REFERENCE_PATTERN = /\b([a-z][a-z0-9]*(?:-[a-z0-9]+)+):([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\b(?!:\/\/)/g;
 function stripFencedCodeBlocks(text) {
   return text.replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, " "));
 }
-async function findUnresolvedSkillReferences(root) {
+async function findUnresolvedSkillReferences(root, options = {}) {
+  const resolvableNamespaces = new Set(options.pluginNamespaces ?? []);
   const skillsRoot = claudePath(root, "skills");
   if (!await fs23.pathExists(skillsRoot)) return [];
   const skillDirs = (await fs23.readdir(skillsRoot, { withFileTypes: true })).filter((entry) => entry.isDirectory() && entry.name !== "shared").map((entry) => entry.name);
@@ -4448,15 +4994,16 @@ async function findUnresolvedSkillReferences(root) {
   const issues = [];
   for (const rel of files) {
     if (rel.startsWith("shared/")) continue;
-    const abs = path26.join(skillsRoot, rel);
+    const abs = path27.join(skillsRoot, rel);
     const raw = await fs23.readFile(abs, "utf8");
     const lines = stripFencedCodeBlocks(raw).split("\n");
     lines.forEach((line2, idx) => {
       for (const match of line2.matchAll(REFERENCE_PATTERN)) {
-        const [reference, , bareName] = match;
+        const [reference, namespace, bareName] = match;
         if (!reference || !bareName) continue;
+        if (namespace && resolvableNamespaces.has(namespace)) continue;
         issues.push({
-          file: path26.join(".claude/skills", rel),
+          file: path27.join(".claude/skills", rel),
           line: idx + 1,
           reference,
           bareName,
@@ -4469,11 +5016,11 @@ async function findUnresolvedSkillReferences(root) {
 }
 
 // src/decisions/doctor.ts
-import path31 from "node:path";
+import path32 from "node:path";
 import fs27 from "fs-extra";
 
 // src/decisions/check.ts
-import path30 from "node:path";
+import path31 from "node:path";
 import fs26 from "fs-extra";
 
 // src/decisions/dep-bump.ts
@@ -4533,7 +5080,7 @@ function isDependencyBumpOnly(beforeText, afterText) {
 
 // src/decisions/diff.ts
 init_exec();
-import path27 from "node:path";
+import path28 from "node:path";
 function isPackageJsonPath(file) {
   return file === "package.json" || file.endsWith("/package.json");
 }
@@ -4594,7 +5141,7 @@ async function resolvePackageJsonPair(root, file, opts) {
     return { before: before2, after: after2 };
   }
   const before = await readBlob(root, `${range}:${file}`) ?? empty;
-  const after = await readText(path27.join(root, file)) ?? empty;
+  const after = await readText(path28.join(root, file)) ?? empty;
   return { before, after };
 }
 async function collectDiffStats(root, opts) {
@@ -4665,21 +5212,21 @@ function firstMatchingRegex(filePath, patterns) {
 }
 
 // src/decisions/paths.ts
-import path28 from "node:path";
+import path29 from "node:path";
 import fs24 from "fs-extra";
 async function resolveDecisionsDir(root) {
-  const primary = path28.join(root, DECISIONS_TRIGGERS.decisionsDir);
+  const primary = path29.join(root, DECISIONS_TRIGGERS.decisionsDir);
   if (await fs24.pathExists(primary)) return primary;
-  const legacy = path28.join(root, DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr");
+  const legacy = path29.join(root, DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr");
   if (await fs24.pathExists(legacy)) return legacy;
   return primary;
 }
 function relativeDecisionPath(decisionsDir, root) {
-  return path28.relative(root, decisionsDir).replace(/\\/g, "/");
+  return path29.relative(root, decisionsDir).replace(/\\/g, "/");
 }
 
 // src/decisions/validate.ts
-import path29 from "node:path";
+import path30 from "node:path";
 import fs25 from "fs-extra";
 function validateDecisionContent(content2) {
   const errors = [];
@@ -4709,14 +5256,14 @@ function decisionNumberFromFile(name) {
   return match?.[1] ?? null;
 }
 async function validateIndexSync(decisionsDir, decisionFiles) {
-  const readmePath = path29.join(decisionsDir, "README.md");
+  const readmePath = path30.join(decisionsDir, "README.md");
   if (!await fs25.pathExists(readmePath)) {
     return ["docs/decisions/README.md is missing"];
   }
   const readme = await readText(readmePath) ?? "";
   const errors = [];
   for (const file of decisionFiles) {
-    const num = decisionNumberFromFile(path29.basename(file));
+    const num = decisionNumberFromFile(path30.basename(file));
     if (num && !indexReferencesNumber(readme, num)) {
       errors.push(`README.md missing index row for ADR-${num}`);
     }
@@ -4811,22 +5358,22 @@ async function checkSatisfaction(input2) {
   const errors = [];
   const decisionsPrefix = `${input2.decisionsRel}/`;
   const newDecisionFiles = input2.changedFiles.filter(
-    (f) => f.startsWith(decisionsPrefix) && isDecisionFileName(path30.basename(f))
+    (f) => f.startsWith(decisionsPrefix) && isDecisionFileName(path31.basename(f))
   );
   if (newDecisionFiles.length === 0) {
     errors.push(`no new or updated decision under ${input2.decisionsRel}/`);
     return errors;
   }
-  const decisionsDir = path30.join(input2.root, input2.decisionsRel);
+  const decisionsDir = path31.join(input2.root, input2.decisionsRel);
   for (const rel of newDecisionFiles) {
-    const abs = path30.join(input2.root, rel);
+    const abs = path31.join(input2.root, rel);
     const content2 = await readText(abs) ?? "";
     const valid = validateDecisionContent(content2);
     if (!valid.ok) errors.push(...valid.errors.map((e) => `${rel}: ${e}`));
   }
   const indexErrors = await validateIndexSync(
     decisionsDir,
-    newDecisionFiles.map((f) => path30.basename(f))
+    newDecisionFiles.map((f) => path31.basename(f))
   );
   errors.push(...indexErrors);
   return errors;
@@ -4882,7 +5429,7 @@ ${opts.commitMessages ?? ""}`;
     changedFiles: stats.files
   });
   if (satisfactionErrors.length > 0 && decisionsRel !== legacyRel) {
-    const legacyExists = await fs26.pathExists(path30.join(root, legacyRel));
+    const legacyExists = await fs26.pathExists(path31.join(root, legacyRel));
     if (legacyExists && !await fs26.pathExists(decisionsDir)) {
       satisfactionErrors = await checkSatisfaction({
         root,
@@ -4913,8 +5460,8 @@ async function listDecisionNumbers(decisionsDir) {
 // src/decisions/doctor.ts
 async function auditDecisionsLayout(root) {
   const findings = [];
-  const primary = path31.join(root, DECISIONS_TRIGGERS.decisionsDir);
-  const legacy = path31.join(root, DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr");
+  const primary = path32.join(root, DECISIONS_TRIGGERS.decisionsDir);
+  const legacy = path32.join(root, DECISIONS_TRIGGERS.legacyDecisionsDir ?? "docs/adr");
   const hasPrimary = await fs27.pathExists(primary);
   const hasLegacy = await fs27.pathExists(legacy);
   if (!hasPrimary && hasLegacy) {
@@ -4929,7 +5476,7 @@ async function auditDecisionsLayout(root) {
   if (!hasPrimary) return findings;
   const decisionsDir = await resolveDecisionsDir(root);
   const rel = relativeDecisionPath(decisionsDir, root);
-  const readmePath = path31.join(decisionsDir, "README.md");
+  const readmePath = path32.join(decisionsDir, "README.md");
   if (!await fs27.pathExists(readmePath)) {
     findings.push({
       level: "advisory",
@@ -4954,7 +5501,7 @@ async function auditDecisionsLayout(root) {
       });
     }
   }
-  const claude = await readText(path31.join(root, "CLAUDE.md"));
+  const claude = await readText(path32.join(root, "CLAUDE.md"));
   if (claude && !claude.includes(`@${rel}/README.md`)) {
     findings.push({
       level: "advisory",
@@ -4985,11 +5532,11 @@ async function auditDecisionsLayout(root) {
 }
 
 // src/scanner/read-context.ts
-import path38 from "node:path";
+import path39 from "node:path";
 import fs29 from "fs-extra";
 
 // src/commands/workspace/config.ts
-import path32 from "node:path";
+import path33 from "node:path";
 import YAML from "yaml";
 var WORKSPACE_FILE = "haus.workspace.yaml";
 function parseWorkspaceConfig(text) {
@@ -5012,11 +5559,11 @@ function parseWorkspaceConfig(text) {
   };
 }
 async function readWorkspaceConfig(workspaceRoot) {
-  return parseWorkspaceConfig(await readText(path32.join(workspaceRoot, WORKSPACE_FILE)));
+  return parseWorkspaceConfig(await readText(path33.join(workspaceRoot, WORKSPACE_FILE)));
 }
 
 // src/workspace/members.ts
-import path33 from "node:path";
+import path34 from "node:path";
 var REPOS_MANIFEST_FILE = "repos.manifest.json";
 var REPOS_LOCAL_FILE = "repos.local.json";
 var MemberConfigError = class extends Error {
@@ -5029,14 +5576,14 @@ var MemberConfigError = class extends Error {
 };
 function resolveAbsPath(workspaceRoot, folder, overrides) {
   const override = overrides[folder];
-  if (override) return path33.resolve(workspaceRoot, override);
-  return path33.resolve(workspaceRoot, folder);
+  if (override) return path34.resolve(workspaceRoot, override);
+  return path34.resolve(workspaceRoot, folder);
 }
 function isSelfMember(workspaceRoot, member) {
-  return path33.resolve(member.absPath) === path33.resolve(workspaceRoot);
+  return path34.resolve(member.absPath) === path34.resolve(workspaceRoot);
 }
 async function readPathOverrides(workspaceRoot) {
-  const filePath = path33.join(workspaceRoot, REPOS_LOCAL_FILE);
+  const filePath = path34.join(workspaceRoot, REPOS_LOCAL_FILE);
   const result = await readJsonDetailed(filePath);
   if (result.status === "missing") return {};
   if (result.status === "invalid") throw new MemberConfigError(filePath, "invalid JSON");
@@ -5052,7 +5599,7 @@ async function readPathOverrides(workspaceRoot) {
   return overrides;
 }
 async function readFromWorkspaceYaml(workspaceRoot, overrides) {
-  const filePath = path33.join(workspaceRoot, WORKSPACE_FILE);
+  const filePath = path34.join(workspaceRoot, WORKSPACE_FILE);
   const text = await readText(filePath);
   if (text === void 0) return void 0;
   const config = parseWorkspaceConfig(text);
@@ -5065,7 +5612,7 @@ async function readFromWorkspaceYaml(workspaceRoot, overrides) {
   }));
 }
 async function readFromManifest(workspaceRoot, overrides) {
-  const filePath = path33.join(workspaceRoot, REPOS_MANIFEST_FILE);
+  const filePath = path34.join(workspaceRoot, REPOS_MANIFEST_FILE);
   const result = await readJsonDetailed(filePath);
   if (result.status === "missing") return void 0;
   if (result.status === "invalid") throw new MemberConfigError(filePath, "invalid JSON");
@@ -5107,11 +5654,11 @@ async function readMembers(rootInfo) {
 }
 
 // src/scanner/scan-project.ts
-import path37 from "node:path";
+import path38 from "node:path";
 
 // src/utils/git-root.ts
 init_exec();
-import path34 from "node:path";
+import path35 from "node:path";
 function fallback(start) {
   return {
     cwd: start,
@@ -5127,11 +5674,11 @@ function fallback(start) {
 async function resolveAbsoluteGitPath(flag, cwd, repoRoot) {
   const withFormat = await runGit(["rev-parse", "--path-format=absolute", flag], { cwd });
   const raw = withFormat.exitCode === 0 ? withFormat.stdout.trim() : "";
-  if (raw && path34.isAbsolute(raw)) return path34.resolve(raw);
+  if (raw && path35.isAbsolute(raw)) return path35.resolve(raw);
   const plain = await runGit(["rev-parse", flag], { cwd });
   const plainRaw = plain.exitCode === 0 ? plain.stdout.trim() : "";
   if (!plainRaw) return "";
-  return path34.isAbsolute(plainRaw) ? path34.resolve(plainRaw) : path34.resolve(repoRoot, plainRaw);
+  return path35.isAbsolute(plainRaw) ? path35.resolve(plainRaw) : path35.resolve(repoRoot, plainRaw);
 }
 async function resolveRoots(start) {
   const cwd = start ?? process.cwd();
@@ -5140,15 +5687,15 @@ async function resolveRoots(start) {
     if (toplevel.exitCode !== 0) return fallback(cwd);
     const toplevelRaw = toplevel.stdout.trim();
     if (!toplevelRaw) return fallback(cwd);
-    const repoRoot = path34.resolve(toplevelRaw);
+    const repoRoot = path35.resolve(toplevelRaw);
     const [gitDir, gitCommonDir] = await Promise.all([
       resolveAbsoluteGitPath("--git-dir", cwd, repoRoot),
       resolveAbsoluteGitPath("--git-common-dir", cwd, repoRoot)
     ]);
     if (!gitDir || !gitCommonDir) return fallback(cwd);
     const isLinkedWorktree = gitDir !== gitCommonDir;
-    const mainRoot = isLinkedWorktree && path34.basename(gitCommonDir) === ".git" ? path34.dirname(gitCommonDir) : repoRoot;
-    const worktreeName = isLinkedWorktree ? path34.basename(gitDir) : null;
+    const mainRoot = isLinkedWorktree && path35.basename(gitCommonDir) === ".git" ? path35.dirname(gitCommonDir) : repoRoot;
+    const worktreeName = isLinkedWorktree ? path35.basename(gitDir) : null;
     return {
       cwd,
       repoRoot,
@@ -5193,7 +5740,7 @@ function resolveMajorVersion(range) {
 }
 
 // src/scanner/detect-package-manager.ts
-import path35 from "node:path";
+import path36 from "node:path";
 import fs28 from "fs-extra";
 function detectPackageManager(root, packageManagerField) {
   const field = String(packageManagerField ?? "").trim();
@@ -5212,9 +5759,9 @@ function detectPackageManager(root, packageManagerField) {
     if (satisfiesVersion(version, ">=9")) return "npm";
     return "unknown";
   }
-  if (fs28.existsSync(path35.join(root, "yarn.lock"))) return "yarn";
-  if (fs28.existsSync(path35.join(root, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs28.existsSync(path35.join(root, "package-lock.json"))) return "npm";
+  if (fs28.existsSync(path36.join(root, "yarn.lock"))) return "yarn";
+  if (fs28.existsSync(path36.join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs28.existsSync(path36.join(root, "package-lock.json"))) return "npm";
   return "unknown";
 }
 
@@ -5439,7 +5986,7 @@ function runDetection(ctx, rules = STACK_RULES) {
 
 // src/scanner/render.ts
 import { readFile } from "node:fs/promises";
-import path36 from "node:path";
+import path37 from "node:path";
 async function buildContentBlob(root, files) {
   const candidates = files.filter(
     (f) => f.endsWith(".ts") || f.endsWith(".js") || f.endsWith(".php") || f.endsWith(".json") || f.endsWith(".yml") || f.endsWith(".yaml")
@@ -5447,7 +5994,7 @@ async function buildContentBlob(root, files) {
   const slice = candidates.slice(0, 300);
   const parts = await mapWithConcurrency(slice, async (rel) => {
     try {
-      return await readFile(path36.join(root, rel), "utf8");
+      return await readFile(path37.join(root, rel), "utf8");
     } catch {
       return "";
     }
@@ -5539,8 +6086,8 @@ var SAFE_FILES = [
   "Gemfile"
 ];
 async function scanProject(root) {
-  const pkg = await readJson(path37.join(root, "package.json"));
-  const composer = await readJson(path37.join(root, "composer.json"));
+  const pkg = await readJson(path38.join(root, "package.json"));
+  const composer = await readJson(path38.join(root, "composer.json"));
   const files = await listFiles(root, SAFE_FILES);
   const safeFiles = files.filter((f) => !blocked(f));
   const depVersions = dependencyVersionMap(pkg, composer);
@@ -5570,7 +6117,7 @@ async function scanProject(root) {
     crossRepoHints.push("Monorepo orchestration detected");
   const unsupportedSignals = collectUnsupportedSignals(safeFiles);
   const detectionStatus = computeDetectionStatus(roles, stacks, unsupportedSignals);
-  const repoNameFallback = pkg?.name ? String(pkg.name) : path37.basename((await resolveRoots(root)).mainRoot);
+  const repoNameFallback = pkg?.name ? String(pkg.name) : path38.basename((await resolveRoots(root)).mainRoot);
   const context = {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     repoName: repoNameFallback,
@@ -5592,10 +6139,10 @@ async function scanProject(root) {
 // src/scanner/read-context.ts
 async function isCacheFresh(root, cachePath) {
   const markerPaths = [
-    path38.join(root, "package.json"),
-    path38.join(root, "composer.json"),
-    path38.join(root, WORKSPACE_FILE),
-    path38.join(root, REPOS_MANIFEST_FILE)
+    path39.join(root, "package.json"),
+    path39.join(root, "composer.json"),
+    path39.join(root, WORKSPACE_FILE),
+    path39.join(root, REPOS_MANIFEST_FILE)
   ];
   const cacheStat = await fs29.stat(cachePath);
   for (const markerPath of markerPaths) {
@@ -5701,7 +6248,7 @@ async function runDoctor(options) {
   } else {
     ok(`- HOOKS OK: ${hooks.message}`);
   }
-  const rootClaudeMdPath = path39.join(root, "CLAUDE.md");
+  const rootClaudeMdPath = path40.join(root, "CLAUDE.md");
   const rootClaudeMdContent = await readText(rootClaudeMdPath);
   if (!rootClaudeMdContent) {
     flag(
@@ -5744,9 +6291,9 @@ async function runDoctor(options) {
         ok("- CLAUDE.md: import block present");
       }
       for (const target of actualTargets) {
-        const resolved = path39.resolve(root, target);
-        const relFromRoot = path39.relative(root, resolved);
-        const escapesRoot = relFromRoot === ".." || relFromRoot.startsWith(`..${path39.sep}`) || path39.isAbsolute(relFromRoot);
+        const resolved = path40.resolve(root, target);
+        const relFromRoot = path40.relative(root, resolved);
+        const escapesRoot = relFromRoot === ".." || relFromRoot.startsWith(`..${path40.sep}`) || path40.isAbsolute(relFromRoot);
         if (escapesRoot || !await fs30.pathExists(resolved)) {
           flag(
             `- CLAUDE.md import: @${target} does not resolve (run \`haus apply --write\`)`,
@@ -5780,8 +6327,8 @@ async function runDoctor(options) {
     } else {
       const storedHashMatch = firstLine.match(/hash=(sha256-[a-f0-9]+)/);
       const bodyContent = workflowContent.slice(firstLine.length + 1);
-      const cachePath = path39.join(getCacheDir(), "templates/agentic-workflow-standard.md");
-      const bundledPath = path39.join(
+      const cachePath = path40.join(getCacheDir(), "templates/agentic-workflow-standard.md");
+      const bundledPath = path40.join(
         packageRoot(),
         "library",
         "global",
@@ -5830,7 +6377,7 @@ async function runDoctor(options) {
     }
   }
   if (workflowExists) {
-    const prettierIgnore = await readText(path39.join(root, ".prettierignore")) ?? "";
+    const prettierIgnore = await readText(path40.join(root, ".prettierignore")) ?? "";
     const lines = prettierIgnore.split("\n");
     const missing = IGNORED_PATHS.filter((p) => !prettierIgnoreProtects(lines, p));
     if (missing.length > 0) {
@@ -5870,7 +6417,50 @@ async function runDoctor(options) {
     if (finding.level === "ok") ok(finding.line);
     else suggest(finding.line, finding.sentence, finding.fix);
   }
-  const skillRefIssues = await findUnresolvedSkillReferences(root);
+  const pluginPins = await loadCatalogPluginPins(root);
+  const pluginState = await probePluginEnv();
+  const activePins = pluginPins.filter((pin) => isPluginActive(pluginState, pin));
+  const activeNamespaces = activePins.map((pin) => pin.plugin);
+  if (pluginPins.length === 0) {
+  } else if (!pluginState.available) {
+    suggest(
+      "- GLOBAL PLUGINS: not checked (the `claude` CLI is not on PATH)",
+      "Claude Code's CLI isn't on PATH, so haus can't verify the global plugin(s) it manages",
+      "install Claude Code, then run `haus install`"
+    );
+  } else {
+    const pending = planPluginActions(pluginPins, pluginState).filter(
+      (action) => action.kind !== "up-to-date"
+    );
+    if (pending.length > 0) {
+      suggest(
+        `- GLOBAL PLUGINS: ${pending.length} plugin(s) not at the pinned state (${pending.map((a) => `${a.pin.id}: ${a.reason}`).join("; ")})`,
+        `${pending.length} haus-managed global plugin(s) are missing, disabled, or off the pinned ref`,
+        "haus update (or `haus install` outside a project)"
+      );
+    } else {
+      ok(`- GLOBAL PLUGINS: OK (${pluginPins.map((p) => `${p.id}@${p.ref}`).join(", ")})`);
+    }
+  }
+  if (activePins.length > 0) {
+    const lockEntries = await readJson(hausPath(root, "haus.lock.json"));
+    const superseded = (lockEntries ?? []).map((entry) => entry.id).filter(
+      (id) => typeof id === "string" && isSupersededByPlugin(
+        id,
+        activePins.map((pin) => pin.id)
+      )
+    );
+    if (superseded.length > 0) {
+      suggest(
+        `- GLOBAL PLUGINS: ${superseded.length} installed item(s) are superseded by the global plugin (${superseded.slice(0, 3).join(", ")}${superseded.length > 3 ? ", \u2026" : ""})`,
+        `${superseded.length} project skill(s) duplicate what the global plugin already provides`,
+        "haus update (removes the superseded copies)"
+      );
+    }
+  }
+  const skillRefIssues = await findUnresolvedSkillReferences(root, {
+    pluginNamespaces: activeNamespaces
+  });
   if (skillRefIssues.length > 0) {
     const prefixBug = skillRefIssues.filter((i) => i.bareInstalled);
     const missingDep = skillRefIssues.filter((i) => !i.bareInstalled);
@@ -5934,7 +6524,7 @@ async function runDoctor(options) {
       }
     }
   }
-  const pkgJson = await readJson(path39.join(packageRoot(), "package.json"));
+  const pkgJson = await readJson(path40.join(packageRoot(), "package.json"));
   const currentVersion = pkgJson?.version ?? "0.0.0";
   const npmStatus = await fetchNpmVersionStatus(currentVersion);
   if (npmStatus.updateAvailable && npmStatus.latest !== null) {
@@ -5967,7 +6557,7 @@ async function runDoctor(options) {
 }
 
 // src/commands/update.ts
-import path42 from "node:path";
+import path43 from "node:path";
 
 // src/claude/refresh-project.ts
 import fs31 from "fs-extra";
@@ -5979,12 +6569,16 @@ async function isHausProject(root) {
 }
 async function refreshProjectApply(root) {
   if (!await isHausProject(root)) return [];
-  return writeClaudeFiles(root, false, void 0, { refillConfig: false });
+  return writeClaudeFiles(root, false, void 0, {
+    refillConfig: false,
+    // Superseded copies are removed in the same pass that re-applies the catalog.
+    activePluginIds: await activeGlobalPluginIds(root)
+  });
 }
 
 // src/install/apply.ts
 import crypto2 from "node:crypto";
-import path40 from "node:path";
+import path41 from "node:path";
 import fs32 from "fs-extra";
 
 // src/install/header.ts
@@ -6078,7 +6672,7 @@ function destFileMissing(destPath) {
 }
 function sourceVersion() {
   try {
-    const pkgPath = path40.join(packageRoot(), "package.json");
+    const pkgPath = path41.join(packageRoot(), "package.json");
     const pkg = JSON.parse(fs32.readFileSync(pkgPath, "utf8"));
     return `${pkg.name ?? "haus"}@${pkg.version ?? "0.0.0"}`;
   } catch {
@@ -6086,49 +6680,49 @@ function sourceVersion() {
   }
 }
 function globalSrcDir() {
-  return path40.join(packageRoot(), "library", "global");
+  return path41.join(packageRoot(), "library", "global");
 }
 function collectSkillAuxFiles(skillsDir, claudeDir, skillName) {
-  const skillDir = path40.join(skillsDir, skillName);
+  const skillDir = path41.join(skillsDir, skillName);
   const entries = [];
   for (const rel of fs32.readdirSync(skillDir, { recursive: true })) {
     if (rel === "SKILL.md") continue;
-    const abs = path40.join(skillDir, rel);
+    const abs = path41.join(skillDir, rel);
     if (!fs32.statSync(abs).isFile()) continue;
-    const posixRel = rel.split(path40.sep).join("/");
+    const posixRel = rel.split(path41.sep).join("/");
     entries.push({
       stableId: `skill.${skillName}.${posixRel.replace(/\//g, ".")}`,
-      srcRelPath: path40.join("library", "global", "skills", skillName, rel),
-      destPath: path40.join(claudeDir, "skills", skillName, rel)
+      srcRelPath: path41.join("library", "global", "skills", skillName, rel),
+      destPath: path41.join(claudeDir, "skills", skillName, rel)
     });
   }
   return entries;
 }
 function collectSourceFiles(srcDir, claudeDir) {
   const entries = [];
-  const skillsDir = path40.join(srcDir, "skills");
+  const skillsDir = path41.join(srcDir, "skills");
   if (fs32.pathExistsSync(skillsDir)) {
     for (const skillName of fs32.readdirSync(skillsDir)) {
-      const skillFile = path40.join(skillsDir, skillName, "SKILL.md");
+      const skillFile = path41.join(skillsDir, skillName, "SKILL.md");
       if (fs32.pathExistsSync(skillFile)) {
         entries.push({
           stableId: `skill.${skillName}`,
-          srcRelPath: path40.join("library", "global", "skills", skillName, "SKILL.md"),
-          destPath: path40.join(claudeDir, "skills", skillName, "SKILL.md")
+          srcRelPath: path41.join("library", "global", "skills", skillName, "SKILL.md"),
+          destPath: path41.join(claudeDir, "skills", skillName, "SKILL.md")
         });
         entries.push(...collectSkillAuxFiles(skillsDir, claudeDir, skillName));
       }
     }
   }
-  const commandsDir = path40.join(srcDir, "commands");
+  const commandsDir = path41.join(srcDir, "commands");
   if (fs32.pathExistsSync(commandsDir)) {
     for (const fileName of fs32.readdirSync(commandsDir)) {
       if (!fileName.endsWith(".md")) continue;
       const commandName = fileName.slice(0, -".md".length);
       entries.push({
         stableId: `command.${commandName}`,
-        srcRelPath: path40.join("library", "global", "commands", fileName),
-        destPath: path40.join(claudeDir, "commands", fileName)
+        srcRelPath: path41.join("library", "global", "commands", fileName),
+        destPath: path41.join(claudeDir, "commands", fileName)
       });
     }
   }
@@ -6154,7 +6748,7 @@ async function applyInstall(options = {}) {
   };
   const manifestFiles = [];
   for (const entry of sourceFiles) {
-    const srcPath = path40.join(packageRoot(), entry.srcRelPath);
+    const srcPath = path41.join(packageRoot(), entry.srcRelPath);
     const rawContent = await readText(srcPath);
     if (rawContent === void 0) {
       warn(`Source file not found: ${entry.srcRelPath}`);
@@ -6215,7 +6809,7 @@ async function applyInstall(options = {}) {
   }
   let mergedSettings;
   if (!check) {
-    const fragmentPath = path40.join(srcDir, "settings-fragments", "hooks.json");
+    const fragmentPath = path41.join(srcDir, "settings-fragments", "hooks.json");
     const fragments = await loadHooksFragment(fragmentPath);
     const settings = await readSettings();
     const { settings: hookSettings, addedIds } = mergeHooks(settings, fragments);
@@ -6245,9 +6839,12 @@ async function applyInstall(options = {}) {
   }
   if (!dryRun && !check && mergedSettings) {
     await writeSettings(mergedSettings);
-    const manifest = buildManifest(source, manifestFiles, [
-      .../* @__PURE__ */ new Set([...existingManifest?.hooks ?? [], ...result.hookIds])
-    ]);
+    const manifest = buildManifest(
+      source,
+      manifestFiles,
+      [.../* @__PURE__ */ new Set([...existingManifest?.hooks ?? [], ...result.hookIds])],
+      existingManifest?.plugins
+    );
     await writeManifest(manifest);
   }
   return result;
@@ -6304,7 +6901,7 @@ function summarizeLockDiff(before, after) {
 
 // src/update/lockfile.ts
 import { mkdir, readFile as readFile2, copyFile } from "node:fs/promises";
-import path41 from "node:path";
+import path42 from "node:path";
 async function readLockSummary(root) {
   const lock = await readJson(hausPath(root, "haus.lock.json")) ?? [];
   const catalogRef = lock.find((item) => item.catalogRef)?.catalogRef ?? null;
@@ -6342,7 +6939,7 @@ async function applyLock(root) {
   try {
     const backupDir = hausPath(root, "backups");
     await mkdir(backupDir, { recursive: true });
-    await copyFile(lockPath, path41.join(backupDir, `haus.lock.${Date.now()}.json`));
+    await copyFile(lockPath, path42.join(backupDir, `haus.lock.${Date.now()}.json`));
   } catch {
   }
   const enriched = await Promise.all(
@@ -6364,7 +6961,7 @@ function diffLock(before, after) {
 }
 async function hasLocalOverrides(root) {
   try {
-    await readFile2(path41.join(root, ".claude", "settings.json"), "utf8");
+    await readFile2(path42.join(root, ".claude", "settings.json"), "utf8");
     return true;
   } catch {
     return false;
@@ -6380,15 +6977,26 @@ async function runUpdate(options) {
     return;
   }
   if (options.check) {
-    const pkgJson2 = await readJson(path42.join(packageRoot(), "package.json"));
+    const pkgJson2 = await readJson(path43.join(packageRoot(), "package.json"));
     const currentVersion2 = pkgJson2?.version ?? "0.0.0";
-    const [status, npmVersion, latestCatalogTag, globalInstallDrift, catalogItems, lockItems] = await Promise.all([
+    const [
+      status,
+      npmVersion,
+      latestCatalogTag,
+      globalInstallDrift,
+      catalogItems,
+      lockItems,
+      globalPluginDrift
+    ] = await Promise.all([
       options.fast ? fastLockStatus(root) : checkLock(root),
       fetchNpmVersionStatus(currentVersion2),
       fetchLatestCatalogTag(),
       options.fast ? Promise.resolve(null) : detectGlobalInstallDrift(),
       loadCatalog(root),
-      readJson(hausPath(root, "haus.lock.json"))
+      readJson(hausPath(root, "haus.lock.json")),
+      // Same tier split as globalInstallDrift: --fast is the cheap probe the
+      // SessionStart hook uses and must not shell out to the `claude` CLI.
+      options.fast ? Promise.resolve(null) : detectGlobalPluginDrift(root)
     ]);
     const formerIdMigrations = findFormerIdMigrations(lockItems ?? [], catalogItems);
     const installedRef = options.fast ? status.catalogRef : status.catalogRef ?? "main";
@@ -6403,6 +7011,7 @@ async function runUpdate(options) {
           catalogRefBehind,
           formerIdMigrations,
           globalInstallDrift,
+          globalPluginDrift,
           localOverrides: await hasLocalOverrides(root),
           summary: diffGeneratedFiles(),
           npmVersion
@@ -6412,12 +7021,12 @@ async function runUpdate(options) {
       )
     );
     const hasHashDrift = !options.fast && status.count > 0 && "ok" in status && !status.ok;
-    if (hasHashDrift || formerIdMigrations.length > 0 || globalInstallDrift === true) {
+    if (hasHashDrift || formerIdMigrations.length > 0 || globalInstallDrift === true || globalPluginDrift === true) {
       process.exitCode = 1;
     }
     return;
   }
-  const pkgJson = await readJson(path42.join(packageRoot(), "package.json"));
+  const pkgJson = await readJson(path43.join(packageRoot(), "package.json"));
   const currentVersion = pkgJson?.version ?? "0.0.0";
   const npmStatus = await fetchNpmVersionStatus(currentVersion);
   if (npmStatus.updateAvailable && npmStatus.latest !== null) {
@@ -6450,6 +7059,7 @@ async function runUpdate(options) {
     warn(formatGithubRateLimitMessage(sync.rateLimit));
   }
   await refreshGlobalInstall();
+  await ensureCatalogPinnedPlugins(root);
   await refreshProjectFiles(root);
   const { after } = await applyLock(root);
   log(diffLock(lockBefore, after));
@@ -6460,7 +7070,7 @@ async function runFromHookCheck(root) {
   try {
     const summary = await readLockSummary(root);
     if (summary.count === 0) return;
-    const pkgJson = await readJson(path42.join(packageRoot(), "package.json"));
+    const pkgJson = await readJson(path43.join(packageRoot(), "package.json"));
     const currentVersion = pkgJson?.version ?? "0.0.0";
     const [npmVersion, latestCatalogTag] = await Promise.all([
       fetchNpmVersionStatus(currentVersion),
@@ -6518,6 +7128,26 @@ async function refreshGlobalInstall() {
     warn(`Could not refresh ~/.claude/: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
+async function ensureCatalogPinnedPlugins(root) {
+  try {
+    const pins = await loadCatalogPluginPins(root);
+    const ensured = await ensureGlobalPlugins(pins);
+    await recordManifestPlugins(
+      pins.filter((pin) => ensured.ensured.includes(pin.id)).map((pin) => ({ ...pin, installedAt: (/* @__PURE__ */ new Date()).toISOString() }))
+    );
+  } catch (err) {
+    warn(`Could not update global plugins: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+async function detectGlobalPluginDrift(root) {
+  try {
+    const pins = await loadCatalogPluginPins(root);
+    const state = await probePluginEnv();
+    return pluginDriftStatus(planPluginActions(pins, state), { matchRef: true });
+  } catch {
+    return null;
+  }
+}
 async function detectGlobalInstallDrift() {
   try {
     const result = await applyInstall({ check: true });
@@ -6611,7 +7241,7 @@ async function runCiGate(options = {}) {
 init_exec();
 import { existsSync as existsSync2 } from "node:fs";
 import { readdir } from "node:fs/promises";
-import path43 from "node:path";
+import path44 from "node:path";
 var GIT_LOCATION_VARS = [
   "GIT_DIR",
   "GIT_WORK_TREE",
@@ -6671,11 +7301,11 @@ async function runClone(url, opts = {}) {
     process.exitCode = 1;
     return;
   }
-  const target = path43.resolve(opts.dir?.trim() || repoNameFromUrl(url));
+  const target = path44.resolve(opts.dir?.trim() || repoNameFromUrl(url));
   if (existsSync2(target) && !await isEmptyDirectory(target)) {
     const check = await checkExistingTarget(target, url);
     if (check.kind === "matches") {
-      log(`\u2022 ${path43.basename(target)} already cloned here, matches ${url} \u2014 skipped`);
+      log(`\u2022 ${path44.basename(target)} already cloned here, matches ${url} \u2014 skipped`);
       return;
     }
     const message = check.kind === "not-a-repo" ? `${target} already exists and is not a git repository \u2014 refusing to clone ${url} there. Remove or rename it, or pass a different [dir].` : `${target} already exists as a different repository (origin: ${check.origin ?? "(no origin remote)"}) \u2014 refusing to clone ${url} there. Remove or rename it, or pass a different [dir].`;
@@ -6784,7 +7414,7 @@ async function runDecisionsGuard(options = {}) {
 }
 
 // src/commands/decisions.ts
-import path44 from "node:path";
+import path45 from "node:path";
 
 // src/decisions/next-number.ts
 async function nextDecisionNumber(root) {
@@ -6894,7 +7524,7 @@ async function runDecisions(sub, arg, options = {}) {
     return;
   }
   if (sub === "validate") {
-    const target = arg ? path44.resolve(root, arg) : void 0;
+    const target = arg ? path45.resolve(root, arg) : void 0;
     if (!target) {
       error("usage: haus decisions validate <path-to-decision.md>");
       process.exitCode = 1;
@@ -7163,17 +7793,34 @@ async function runGuard(kind, _options) {
 }
 
 // src/commands/init.ts
-import path46 from "node:path";
+import path47 from "node:path";
 import fs33 from "fs-extra";
 
 // src/recommender/git-signal.ts
 init_exec();
 async function runGitLines(root, args) {
+  const started = Date.now();
   try {
     const result = await runGit(args, { cwd: root, timeout: 3e3 });
+    if (process.env.HAUS_DEBUG_GITSIG) {
+      const { appendFileSync } = await import("node:fs");
+      appendFileSync(
+        process.env.HAUS_DEBUG_GITSIG,
+        `GITSIG ok git ${args.join(" ")} cwd=${root} ms=${Date.now() - started} exit=${result.exitCode} stdout=${JSON.stringify(result.stdout.slice(0, 200))} stderr=${JSON.stringify(result.stderr.slice(0, 200))}
+`
+      );
+    }
     if (result.exitCode !== 0) return [];
     return result.stdout.split("\n").map((x) => x.trim()).filter(Boolean);
-  } catch {
+  } catch (err) {
+    if (process.env.HAUS_DEBUG_GITSIG) {
+      const { appendFileSync } = await import("node:fs");
+      appendFileSync(
+        process.env.HAUS_DEBUG_GITSIG,
+        `GITSIG threw git ${args.join(" ")} cwd=${root} ms=${Date.now() - started} err=${JSON.stringify(String(err).slice(0, 300))}
+`
+      );
+    }
     return [];
   }
 }
@@ -7189,6 +7836,7 @@ async function readChangedFiles(root) {
 
 // src/recommender/recommend.ts
 async function recommend(root, context, opts = {}) {
+  const activePluginIds = opts.activePluginIds ?? [];
   const items = await loadCatalog(root);
   const sources = buildSourcesReport(items);
   const deep = await readJson(hausPath(root, "deep-context.json")) ?? {};
@@ -7246,6 +7894,15 @@ async function recommend(root, context, opts = {}) {
       "Catalog item is deprecated",
       "reviewStatus:deprecated"
     );
+    if (isItemSupersededByPlugin(item, activePluginIds)) {
+      add(
+        "superseded-by-global-plugin",
+        false,
+        "superseded-by-global-plugin",
+        "Provided by an installed global Claude Code plugin",
+        `plugin:${activePluginIds.join(",")}`
+      );
+    }
     if (normSource === "curated") {
       const rs = item.reviewStatus;
       add(
@@ -7585,7 +8242,7 @@ function buildOptInEligible(items, skipped) {
 }
 
 // src/commands/workspace/discover.ts
-import path45 from "node:path";
+import path46 from "node:path";
 import fg5 from "fast-glob";
 import YAML2 from "yaml";
 var DEFAULT_MAX_DEPTH = 3;
@@ -7626,10 +8283,10 @@ async function findRepoRoots(workspaceRoot, maxDepth = DEFAULT_MAX_DEPTH) {
   const gitDirs = /* @__PURE__ */ new Set();
   const manifestDirs = /* @__PURE__ */ new Set();
   for (const match of gitMatches) {
-    gitDirs.add(path45.posix.dirname(match));
+    gitDirs.add(path46.posix.dirname(match));
   }
   for (const match of manifestMatches) {
-    manifestDirs.add(path45.posix.dirname(match));
+    manifestDirs.add(path46.posix.dirname(match));
   }
   const repoRoots = [...gitDirs];
   const manifestSorted = [...manifestDirs].sort(
@@ -7646,9 +8303,9 @@ async function findRepoRoots(workspaceRoot, maxDepth = DEFAULT_MAX_DEPTH) {
 async function discoverRepos(workspaceRoot, maxDepth = DEFAULT_MAX_DEPTH) {
   const repoRoots = (await findRepoRoots(workspaceRoot, maxDepth)).filter((dir) => dir !== ".");
   return mapWithConcurrency(repoRoots, async (relDir) => {
-    const absDir = path45.resolve(workspaceRoot, relDir);
-    const pkg = await readJson(path45.join(absDir, "package.json"));
-    const name = typeof pkg?.name === "string" && pkg.name.length > 0 ? pkg.name : path45.basename(absDir);
+    const absDir = path46.resolve(workspaceRoot, relDir);
+    const pkg = await readJson(path46.join(absDir, "package.json"));
+    const name = typeof pkg?.name === "string" && pkg.name.length > 0 ? pkg.name : path46.basename(absDir);
     let role = "auto";
     try {
       const scan = await scanProject(absDir);
@@ -7691,7 +8348,7 @@ function renderWorkspaceYaml(config) {
   });
 }
 async function runDiscover(workspaceRoot, opts = {}) {
-  const yamlPath = path45.join(workspaceRoot, "haus.workspace.yaml");
+  const yamlPath = path46.join(workspaceRoot, "haus.workspace.yaml");
   const existingText = await readText(yamlPath);
   const existing = parseWorkspaceConfig(existingText);
   if (existingText && !existing) {
@@ -7758,7 +8415,11 @@ async function runSetupCore(root, opts) {
   const siblingWarning = await hasMultipleSiblingRepos(root) ? [SIBLING_REPO_WARNING] : [];
   const context = await readContextOrScan(root);
   const priorManualIncludes = await readPriorManualIncludes(root);
-  const recommendation = await recommend(root, context, { include: priorManualIncludes });
+  const activePluginIds = await activeGlobalPluginIds(root);
+  const recommendation = await recommend(root, context, {
+    include: priorManualIncludes,
+    activePluginIds
+  });
   if (recommendation.recommended.length === 0 && !force) {
     const warningLines2 = [
       .../* @__PURE__ */ new Set([...context.warnings, ...recommendation.warnings ?? [], ...siblingWarning])
@@ -7772,7 +8433,10 @@ async function runSetupCore(root, opts) {
       say(`Repo: ${context.repoName}`);
       for (const warning of warningLines2) say(`- WARN: ${warning}`);
     }
-    const message = "No catalog items matched this project at all (zero signal) \u2014 refusing to write recommendation.json/haus.lock.json. Re-run with `haus setup-project --force` to write anyway.";
+    const supersededCount = recommendation.skipped.filter(
+      (s) => s.skipReasons?.some((r) => r.code === "superseded-by-global-plugin")
+    ).length;
+    const message = supersededCount > 0 ? `No catalog items matched this project after ${supersededCount} item(s) were gated as already provided by an installed global plugin \u2014 refusing to write recommendation.json/haus.lock.json. Those skills are available globally; re-run with \`haus setup-project --force\` to write anyway.` : "No catalog items matched this project at all (zero signal) \u2014 refusing to write recommendation.json/haus.lock.json. Re-run with `haus setup-project --force` to write anyway.";
     warn(message);
     process.exitCode = 1;
     return {
@@ -7838,7 +8502,10 @@ async function runSetupCore(root, opts) {
       warn(formatGithubRateLimitMessage(sync.rateLimit));
     }
   }
-  const files = await writeClaudeFiles(root, dryRun ?? false, void 0, { quiet: opts.quiet });
+  const files = await writeClaudeFiles(root, dryRun ?? false, void 0, {
+    quiet: opts.quiet,
+    activePluginIds
+  });
   say("Applied files:");
   files.forEach((f) => say(`- ${displayPath(root, f)}`));
   const hooksAfter = await verifyProjectSettingsHooksContract(root);
@@ -7869,7 +8536,7 @@ async function runSetupProject(options) {
 // src/commands/init.ts
 async function runInit(options) {
   const root = process.cwd();
-  const hausDir = path46.join(root, ".haus-workflow");
+  const hausDir = path47.join(root, ".haus-workflow");
   const alreadyInit = await fs33.pathExists(hausDir);
   if (alreadyInit) {
     log("Haus AI already initialized in this project.");
@@ -7934,7 +8601,19 @@ function printCompanionToolSuggestions(deps = {}) {
 }
 
 // src/commands/install.ts
-async function runInstall(options) {
+function toManifestPlugin(pin) {
+  return {
+    id: pin.id,
+    plugin: pin.plugin,
+    marketplace: pin.marketplace,
+    url: pin.url,
+    ref: pin.ref,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function runInstall(options, deps = {}) {
+  const ensure = deps.ensureGlobalPlugins ?? ensureGlobalPlugins;
+  const probe = deps.probePluginEnv ?? probePluginEnv;
   try {
     const result = await applyInstall({
       dryRun: options.dryRun,
@@ -7942,9 +8621,23 @@ async function runInstall(options) {
       check: options.check
     });
     if (!options.postinstall) printApplyResult(result, options.dryRun ?? false);
-    if (options.check && result.drift) {
-      process.exitCode = 1;
-    } else if (!options.check && !options.dryRun) {
+    const pins = [...DEFAULT_GLOBAL_PLUGINS];
+    if (options.check) {
+      const state = await probe();
+      const pluginDrift = pluginDriftStatus(planPluginActions(pins, state), { matchRef: false });
+      if (pluginDrift === true) {
+        log("Global plugin drift: a haus-managed plugin is missing or disabled.");
+      }
+      if (result.drift || pluginDrift === true) process.exitCode = 1;
+      return;
+    }
+    const ensured = await ensure(pins, { dryRun: options.dryRun });
+    if (!options.dryRun) {
+      await recordManifestPlugins(
+        pins.filter((pin) => ensured.ensured.includes(pin.id)).map(toManifestPlugin)
+      );
+    }
+    if (!options.dryRun) {
       printCompanionToolSuggestions();
       const total = result.created.length + result.updated.length;
       if (options.postinstall) {
@@ -7956,6 +8649,9 @@ async function runInstall(options) {
           parts.length ? `  \u2022 ${parts.join(", ")} in ~/.claude (skills, slash commands)` : "  \u2022 already up to date \u2014 no files changed"
         );
         log(`  \u2022 ensured hooks + security rules are present in ~/.claude/settings.json`);
+        if (ensured.ensured.length) {
+          log(`  \u2022 global plugin(s) pinned: ${ensured.ensured.join(", ")}`);
+        }
         log("Undo any time with:  haus uninstall");
         log("Disable this on install:  HAUS_NO_POSTINSTALL=1");
       } else {
@@ -7975,7 +8671,8 @@ async function runRecommend(options) {
   const root = process.cwd();
   const context = await readContextOrScan(root);
   const include = parseIdList(options.include);
-  const result = await recommend(root, context, { include });
+  const activePluginIds = await activeGlobalPluginIds(root);
+  const result = await recommend(root, context, { include, activePluginIds });
   await writeJson(hausPath(root, "recommendation.json"), result);
   if (options.json) {
     log(JSON.stringify(result, null, 2));
@@ -7996,7 +8693,14 @@ async function runRecommend(options) {
 async function runRefresh() {
   const root = process.cwd();
   const context = await scanProject(root);
-  const recommendation = await recommend(root, context);
+  try {
+    await ensureGlobalPlugins(await loadCatalogPluginPins(root));
+  } catch (err) {
+    warn(`Could not refresh global plugins: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const recommendation = await recommend(root, context, {
+    activePluginIds: await activeGlobalPluginIds(root)
+  });
   await writeJson(hausPath(root, "recommendation.json"), recommendation);
   log("Haus refresh complete");
   log(`Roles: ${context.repoRoles.join(", ") || "unknown"}`);
@@ -8005,7 +8709,7 @@ async function runRefresh() {
 }
 
 // src/install/scaffold.ts
-import path47 from "node:path";
+import path48 from "node:path";
 import fs34 from "fs-extra";
 async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
   const scaffolded = [];
@@ -8022,9 +8726,9 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
   const realRoot = await fs34.realpath(catalogRoot).catch(() => null);
   for (const item of items) {
     if (item.type !== "config") continue;
-    const sourcePath = path47.resolve(catalogRoot, item.path);
-    const rel = path47.relative(catalogRoot, sourcePath);
-    const escapes = rel === "" || path47.isAbsolute(rel) || rel.split(/[/\\]/).some((seg) => seg === "..");
+    const sourcePath = path48.resolve(catalogRoot, item.path);
+    const rel = path48.relative(catalogRoot, sourcePath);
+    const escapes = rel === "" || path48.isAbsolute(rel) || rel.split(/[/\\]/).some((seg) => seg === "..");
     if (escapes) {
       warn(`Skipping ${item.id}: path '${item.path}' escapes the catalog root`);
       continue;
@@ -8034,8 +8738,8 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
       warn(`Skipping ${item.id}: source not found at ${sourcePath}`);
       continue;
     }
-    const realRel = path47.relative(realRoot, realSource);
-    if (realRel !== "" && (path47.isAbsolute(realRel) || realRel.split(/[/\\]/)[0] === "..")) {
+    const realRel = path48.relative(realRoot, realSource);
+    if (realRel !== "" && (path48.isAbsolute(realRel) || realRel.split(/[/\\]/)[0] === "..")) {
       warn(`Skipping ${item.id}: path '${item.path}' resolves outside the catalog root`);
       continue;
     }
@@ -8049,14 +8753,14 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
       continue;
     }
     if (stat.isFile()) {
-      const filename = path47.basename(sourcePath);
-      const dest = path47.join(projectRoot, filename);
+      const filename = path48.basename(sourcePath);
+      const dest = path48.join(projectRoot, filename);
       record(filename, await scaffoldFile(sourcePath, dest, item.id, projectRoot, opts));
     } else if (stat.isDirectory()) {
       const entries = await fs34.readdir(sourcePath);
       for (const entry of entries) {
-        const src = path47.join(sourcePath, entry);
-        const dest = path47.join(projectRoot, entry);
+        const src = path48.join(sourcePath, entry);
+        const dest = path48.join(projectRoot, entry);
         record(entry, await scaffoldFile(src, dest, item.id, projectRoot, opts));
       }
     }
@@ -8064,14 +8768,14 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
   return { scaffolded, skipped, skippedExisting };
 }
 async function scaffoldFile(src, dest, itemId, projectRoot, opts) {
-  const destDisplay = path47.relative(projectRoot, dest) || path47.basename(dest);
+  const destDisplay = path48.relative(projectRoot, dest) || path48.basename(dest);
   const srcStat = await fs34.lstat(src).catch(() => null);
   if (!srcStat) {
-    warn(`Skipping ${path47.basename(src)}: source not found`);
+    warn(`Skipping ${path48.basename(src)}: source not found`);
     return "skipped-refused";
   }
   if (srcStat.isSymbolicLink()) {
-    warn(`Skipping ${path47.basename(src)}: source is a symlink`);
+    warn(`Skipping ${path48.basename(src)}: source is a symlink`);
     return "skipped-refused";
   }
   const exists = await fs34.pathExists(dest);
@@ -8080,13 +8784,13 @@ async function scaffoldFile(src, dest, itemId, projectRoot, opts) {
     return "skipped-exists";
   }
   if (opts.dryRun) {
-    log(`[dry-run] would ${exists ? "overwrite" : "create"} ${path47.basename(dest)} (${itemId})`);
+    log(`[dry-run] would ${exists ? "overwrite" : "create"} ${path48.basename(dest)} (${itemId})`);
     return "scaffolded";
   }
   if (exists && opts.force) {
     await fs34.remove(dest);
   }
-  await fs34.ensureDir(path47.dirname(dest));
+  await fs34.ensureDir(path48.dirname(dest));
   await fs34.copy(src, dest, {
     overwrite: true,
     dereference: false,
@@ -8099,7 +8803,7 @@ async function scaffoldFile(src, dest, itemId, projectRoot, opts) {
       }
     }
   });
-  log(`${exists ? "Overwrote" : "Created"} ${path47.basename(dest)} (${itemId})`);
+  log(`${exists ? "Overwrote" : "Created"} ${path48.basename(dest)} (${itemId})`);
   return "scaffolded";
 }
 
@@ -8164,7 +8868,7 @@ async function runScan(options) {
 }
 
 // src/commands/undo.ts
-import path48 from "node:path";
+import path49 from "node:path";
 import fs35 from "fs-extra";
 
 // src/claude/managed-paths.ts
@@ -8192,18 +8896,18 @@ async function collectLockTrackedPaths(root) {
     const relPaths = row.paths ?? [];
     const existingRel = [];
     for (const rel of relPaths) {
-      if (await fs35.pathExists(path48.resolve(root, rel))) existingRel.push(rel);
+      if (await fs35.pathExists(path49.resolve(root, rel))) existingRel.push(rel);
     }
     if (existingRel.length === 0) continue;
     if (row.hash === void 0) {
-      removable.push(...existingRel.map((rel) => path48.resolve(root, rel)));
+      removable.push(...existingRel.map((rel) => path49.resolve(root, rel)));
       continue;
     }
     const currentHash = await hashInstalledPaths(root, existingRel);
     if (currentHash === row.hash) {
-      removable.push(...existingRel.map((rel) => path48.resolve(root, rel)));
+      removable.push(...existingRel.map((rel) => path49.resolve(root, rel)));
     } else {
-      preserved.push(...existingRel.map((rel) => path48.resolve(root, rel)));
+      preserved.push(...existingRel.map((rel) => path49.resolve(root, rel)));
       log(`Preserving locally-modified ${row.id ?? "(unknown item)"}: ${existingRel.join(", ")}`);
     }
   }
@@ -8216,7 +8920,7 @@ async function settingsHasHausContent(root) {
   return settings._haus != null;
 }
 async function claudeMdHasHausBlock(root) {
-  const filePath = path48.join(root, "CLAUDE.md");
+  const filePath = path49.join(root, "CLAUDE.md");
   if (!await fs35.pathExists(filePath)) return false;
   const text = await fs35.readFile(filePath, "utf8");
   return text.includes(BLOCK_BEGIN);
@@ -8229,15 +8933,15 @@ async function stripProjectSettings(root) {
   const hasContent = Object.keys(settings).length > 0;
   if (hasContent) {
     await writeProjectSettings(root, settings);
-    log(`Stripped haus rules from ${path48.relative(root, settingsPath)} (user settings preserved).`);
+    log(`Stripped haus rules from ${path49.relative(root, settingsPath)} (user settings preserved).`);
     return true;
   }
   await fs35.remove(settingsPath);
-  log(`Removed ${path48.relative(root, settingsPath)} (no user-owned settings remained).`);
+  log(`Removed ${path49.relative(root, settingsPath)} (no user-owned settings remained).`);
   return true;
 }
 async function stripRootClaudeMd(root) {
-  const filePath = path48.join(root, "CLAUDE.md");
+  const filePath = path49.join(root, "CLAUDE.md");
   if (!await fs35.pathExists(filePath)) return false;
   const prev = await fs35.readFile(filePath, "utf8");
   if (!prev.includes(BLOCK_BEGIN)) return false;
@@ -8265,12 +8969,12 @@ async function backupManagedFilesBeforeUndo(root, managedAbsPaths) {
   const backupRoot = hausPath(root, "backups", `undo-${stamp}`);
   for (const abs of managedAbsPaths) {
     if (!await fs35.pathExists(abs)) continue;
-    const rel = path48.relative(root, abs);
-    const backupPath = path48.join(backupRoot, rel);
-    await fs35.ensureDir(path48.dirname(backupPath));
+    const rel = path49.relative(root, abs);
+    const backupPath = path49.join(backupRoot, rel);
+    await fs35.ensureDir(path49.dirname(backupPath));
     await fs35.copy(abs, backupPath);
   }
-  log(`Backed up ${managedAbsPaths.length} managed file(s) to ${path48.relative(root, backupRoot)}.`);
+  log(`Backed up ${managedAbsPaths.length} managed file(s) to ${path49.relative(root, backupRoot)}.`);
 }
 async function runUndo(options) {
   const root = options.root ?? process.cwd();
@@ -8283,7 +8987,7 @@ async function runUndo(options) {
     log("Nothing to remove: no haus-managed files found in this directory.");
     return;
   }
-  const relTargets = managed.map((p) => path48.relative(root, p));
+  const relTargets = managed.map((p) => path49.relative(root, p));
   const summaryParts = [...relTargets];
   if (stripSettings) summaryParts.push(".claude/settings.json (haus rules only)");
   if (stripClaudeMd) summaryParts.push("CLAUDE.md (haus import block only)");
@@ -8307,7 +9011,7 @@ User-owned .claude/ files will be preserved.`
   for (const abs of managed) {
     if (!await fs35.pathExists(abs)) continue;
     await fs35.remove(abs);
-    log(`Removed ${path48.relative(root, abs)}`);
+    log(`Removed ${path49.relative(root, abs)}`);
   }
   if (stripSettings) await stripProjectSettings(root);
   if (stripClaudeMd) await stripRootClaudeMd(root);
@@ -8318,16 +9022,43 @@ User-owned .claude/ files will be preserved.`
 
 // src/install/uninstall.ts
 import crypto3 from "node:crypto";
-import path49 from "node:path";
+import path50 from "node:path";
 import fs36 from "fs-extra";
 async function runUninstall(options = {}) {
-  const { force = false } = options;
+  const { force = false, removePlugins = removeGlobalPlugins } = options;
   const manifest = await readManifest();
-  const result = { deleted: [], skipped: [], hooksStripped: false };
+  const result = {
+    deleted: [],
+    skipped: [],
+    hooksStripped: false,
+    pluginsRemoved: []
+  };
   if (!manifest) {
     warn("No install manifest found \u2014 nothing to uninstall.");
     return result;
   }
+  const recordedPlugins = Array.isArray(manifest.plugins) ? manifest.plugins : [];
+  const malformed = recordedPlugins.filter((entry) => !isValidPin(entry)).length;
+  if (malformed > 0) {
+    warn(
+      `Ignoring ${malformed} malformed plugin record(s) in the install manifest \u2014 continuing with the rest of the uninstall.`
+    );
+  }
+  const managedPlugins = recordedPlugins.filter(isValidPin).map((p) => ({
+    id: p.id,
+    plugin: p.plugin,
+    marketplace: p.marketplace,
+    url: p.url,
+    ref: p.ref
+  }));
+  try {
+    const pluginRemoval = await removePlugins(managedPlugins);
+    result.pluginsRemoved = pluginRemoval.removed;
+  } catch (err) {
+    warn(
+      `Could not remove global plugin(s): ${err instanceof Error ? err.message : String(err)} \u2014 continuing with the rest of the uninstall.`
+    );
+  }
   for (const entry of manifest.files) {
     const exists = fs36.pathExistsSync(entry.destPath);
     if (!exists) continue;
@@ -8348,14 +9079,14 @@ async function runUninstall(options = {}) {
       continue;
     }
     await fs36.remove(entry.destPath);
-    await pruneEmptyDir(path49.dirname(entry.destPath));
+    await pruneEmptyDir(path50.dirname(entry.destPath));
     result.deleted.push(entry.destPath);
   }
   const settings = await readSettings();
   const stripped = stripHausHooks(stripHausAsk(stripHausAllow(stripHausDeny(settings))));
   await writeSettings(stripped);
   result.hooksStripped = true;
-  const hausDir = path49.join(globalClaudeDir(), "haus");
+  const hausDir = path50.join(globalClaudeDir(), "haus");
   const manifestPath2 = hausManifestPath();
   if (fs36.pathExistsSync(manifestPath2)) {
     await fs36.remove(manifestPath2);
@@ -8381,6 +9112,10 @@ function printUninstallResult(result) {
   if (result.hooksStripped) {
     log("Haus hook entries removed from ~/.claude/settings.json");
   }
+  if (result.pluginsRemoved.length) {
+    log(`Global plugin(s) removed: ${result.pluginsRemoved.join(", ")}`);
+    log("Projects relying on those plugin skills get them back by reinstalling haus.");
+  }
 }
 
 // src/commands/uninstall.ts
@@ -8409,11 +9144,11 @@ async function runUninstallCommand(options) {
 }
 
 // src/commands/validate-catalog.ts
-import path51 from "node:path";
+import path52 from "node:path";
 
 // src/catalog/validate-core.ts
 import fs37 from "node:fs";
-import path50 from "node:path";
+import path51 from "node:path";
 var ITEM_SEMVER_RE = /^\d+\.\d+\.\d+$/;
 var ITEM_ID_PATTERN = /^haus\./;
 function auditForbiddenStacks(items) {
@@ -8562,7 +9297,7 @@ function readForAudit(absPath, label, failures) {
   }
 }
 function auditTemplateContent(manifestDir, absPath, itemId) {
-  const rel = path50.relative(manifestDir, absPath);
+  const rel = path51.relative(manifestDir, absPath);
   const failures = [];
   const text = readForAudit(absPath, `${itemId}: ${rel}`, failures);
   if (text === null) return failures;
@@ -8584,25 +9319,25 @@ function auditShippedFiles(manifestDir, items) {
   const failures = [];
   for (const item of items) {
     if (!item.path || !isSafeCatalogPath(item.path)) continue;
-    const absPath = path50.join(manifestDir, item.path);
+    const absPath = path51.join(manifestDir, item.path);
     if (item.type === "skill") {
-      const skillMd = path50.join(absPath, "SKILL.md");
+      const skillMd = path51.join(absPath, "SKILL.md");
       if (!fs37.existsSync(skillMd)) {
-        failures.push(`${item.id}: missing ${path50.relative(manifestDir, skillMd)}`);
+        failures.push(`${item.id}: missing ${path51.relative(manifestDir, skillMd)}`);
         continue;
       }
       const text = readForAudit(skillMd, `${item.id}: SKILL.md`, failures);
       if (text === null) continue;
       failures.push(...checkRequiredFrontmatter(text, `${item.id}: SKILL.md`));
       failures.push(
-        ...auditForbiddenTagsInText(text, `${item.id}: ${path50.relative(manifestDir, skillMd)}`)
+        ...auditForbiddenTagsInText(text, `${item.id}: ${path51.relative(manifestDir, skillMd)}`)
       );
     } else if (item.type === "agent") {
       if (!fs37.existsSync(absPath)) {
         failures.push(`${item.id}: missing agent file ${item.path}`);
         continue;
       }
-      const rel = path50.relative(manifestDir, absPath);
+      const rel = path51.relative(manifestDir, absPath);
       const text = readForAudit(absPath, `${item.id}: ${rel}`, failures);
       if (text === null) continue;
       failures.push(...checkRequiredFrontmatter(text, `${item.id}: ${rel}`));
@@ -8618,7 +9353,7 @@ function auditShippedFiles(manifestDir, items) {
         failures.push(`${item.id}: missing command file ${item.path}`);
         continue;
       }
-      const rel = path50.relative(manifestDir, absPath);
+      const rel = path51.relative(manifestDir, absPath);
       const text = readForAudit(absPath, `${item.id}: ${rel}`, failures);
       if (text === null) continue;
       failures.push(...checkRequiredFrontmatter(text, `${item.id}: ${rel}`));
@@ -8650,7 +9385,7 @@ function walkAllFiles(dir, fn, failures) {
   }
   for (const entry of entries) {
     if (entry.name === ".DS_Store") continue;
-    const full = path50.join(dir, entry.name);
+    const full = path51.join(dir, entry.name);
     if (entry.isDirectory()) walkAllFiles(full, fn, failures);
     else fn(full);
   }
@@ -8668,12 +9403,12 @@ function auditDiskOrphans(manifestDir, items) {
   const failures = [];
   const claimedPaths = items.filter((item) => item.path && isSafeCatalogPath(item.path)).map((item) => item.path.replace(/\\/g, "/"));
   for (const dir of CONTENT_ROOTS) {
-    const abs = path50.join(manifestDir, dir);
+    const abs = path51.join(manifestDir, dir);
     if (!fs37.existsSync(abs)) continue;
     walkAllFiles(
       abs,
       (file) => {
-        const relPath = path50.relative(manifestDir, file).replace(/\\/g, "/");
+        const relPath = path51.relative(manifestDir, file).replace(/\\/g, "/");
         if (!isPathClaimed(relPath, claimedPaths)) {
           failures.push(`orphaned on disk, claimed by no manifest item: ${relPath}`);
         }
@@ -8694,7 +9429,7 @@ function walkMd(dir, fn, failures) {
     return;
   }
   for (const entry of entries) {
-    const full = path50.join(dir, entry.name);
+    const full = path51.join(dir, entry.name);
     if (entry.isDirectory()) walkMd(full, fn, failures);
     else if (entry.name.endsWith(".md")) fn(full);
   }
@@ -8703,13 +9438,13 @@ function auditMarkdownContent(manifestDir, items) {
   const failures = [];
   const pathSourceMap = buildItemPathSourceMap(items);
   for (const dir of ["skills", "agents", "templates", "commands"]) {
-    const abs = path50.join(manifestDir, dir);
+    const abs = path51.join(manifestDir, dir);
     if (!fs37.existsSync(abs)) continue;
     const dirType = DIR_ITEM_TYPE[dir] ?? "";
     walkMd(
       abs,
       (file) => {
-        const rel = path50.relative(manifestDir, file);
+        const rel = path51.relative(manifestDir, file);
         const text = readForAudit(file, rel, failures);
         if (text === null) return;
         const norm = rel.replace(/\\/g, "/");
@@ -8754,8 +9489,8 @@ async function runValidateCatalog(manifestPath2) {
     process.exitCode = 1;
     return;
   }
-  const abs = path51.resolve(process.cwd(), manifestPath2);
-  const manifestDir = path51.dirname(abs);
+  const abs = path52.resolve(process.cwd(), manifestPath2);
+  const manifestDir = path52.dirname(abs);
   const data = await readJson(abs);
   if (!data?.items) {
     error(`Could not read catalog manifest at ${abs}`);
@@ -8772,7 +9507,7 @@ async function runValidateCatalog(manifestPath2) {
 }
 
 // src/workspace/worktree/add.ts
-import path58 from "node:path";
+import path59 from "node:path";
 import fs41 from "fs-extra";
 
 // src/workspace/worktree/git-worktree.ts
@@ -8892,12 +9627,12 @@ async function hasUnpushedWork(cwd) {
 }
 
 // src/workspace/worktree/hydrate.ts
-import path54 from "node:path";
+import path55 from "node:path";
 import fs39 from "fs-extra";
 
 // src/workspace/worktree/cow-copy.ts
 init_exec();
-import path52 from "node:path";
+import path53 from "node:path";
 import fs38 from "fs-extra";
 async function getMacFilesystemType(dir) {
   const df = await runCommand("df", ["-P", dir]);
@@ -8932,11 +9667,11 @@ async function cowCopyDir(src, dest) {
   const srcExists = await fs38.pathExists(src);
   if (!srcExists)
     return { strategy: "unsupported", attempted: false, ok: false, error: "source missing" };
-  const strategy = await detectCowStrategy(path52.dirname(dest));
+  const strategy = await detectCowStrategy(path53.dirname(dest));
   if (strategy === "unsupported" || strategy === "unknown-platform") {
     return { strategy, attempted: false, ok: false };
   }
-  await fs38.ensureDir(path52.dirname(dest));
+  await fs38.ensureDir(path53.dirname(dest));
   const args = strategy === "darwin-clonefile" ? ["-c", "-R", src, dest] : ["-a", "--reflink=always", src, dest];
   const result = await runCommand("cp", args);
   return {
@@ -8950,7 +9685,7 @@ async function cowCopyDir(src, dest) {
 // src/workspace/worktree/install.ts
 init_exec();
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
-import path53 from "node:path";
+import path54 from "node:path";
 import fg6 from "fast-glob";
 function detectInstallPlan(signals) {
   if (signals.hasYarnLock) {
@@ -8971,10 +9706,10 @@ function detectInstallPlan(signals) {
   return { manager: "none" };
 }
 async function computeLockfileSignals(dir) {
-  const hasYarnLock = existsSync3(path53.join(dir, "yarn.lock"));
-  const hasPnpmLock = existsSync3(path53.join(dir, "pnpm-lock.yaml"));
-  const hasPackageLock = existsSync3(path53.join(dir, "package-lock.json"));
-  const hasComposerLock = existsSync3(path53.join(dir, "composer.lock"));
+  const hasYarnLock = existsSync3(path54.join(dir, "yarn.lock"));
+  const hasPnpmLock = existsSync3(path54.join(dir, "pnpm-lock.yaml"));
+  const hasPackageLock = existsSync3(path54.join(dir, "package-lock.json"));
+  const hasComposerLock = existsSync3(path54.join(dir, "composer.lock"));
   const dotnetFiles = await fg6(["**/*.csproj", "**/*.sln"], {
     cwd: dir,
     onlyFiles: true,
@@ -8988,7 +9723,7 @@ async function computeLockfileSignals(dir) {
   });
   const hasDotnetProject = dotnetFiles.length > 0;
   let hasPackageManagerField = false;
-  const pkgPath = path53.join(dir, "package.json");
+  const pkgPath = path54.join(dir, "package.json");
   if (existsSync3(pkgPath)) {
     try {
       const pkg = JSON.parse(readFileSync3(pkgPath, "utf8"));
@@ -9029,8 +9764,8 @@ async function hydrateMember(mainMemberPath, worktreeMemberPath, opts = {}) {
   const start = Date.now();
   const targets = [];
   for (const target of HYDRATION_TARGETS) {
-    const src = path54.join(mainMemberPath, target);
-    const dest = path54.join(worktreeMemberPath, target);
+    const src = path55.join(mainMemberPath, target);
+    const dest = path55.join(worktreeMemberPath, target);
     if (!await fs39.pathExists(src)) continue;
     const destExists = await fs39.pathExists(dest);
     if (!opts.force && destExists) continue;
@@ -9048,11 +9783,11 @@ async function hydrateMember(mainMemberPath, worktreeMemberPath, opts = {}) {
 
 // src/workspace/worktree/local-files.ts
 init_exec();
-import path55 from "node:path";
+import path56 from "node:path";
 import fs40 from "fs-extra";
 var MACHINE_LOCAL_FILES = [
   "docker-compose.local.yml",
-  path55.join(".claude", "settings.local.json")
+  path56.join(".claude", "settings.local.json")
 ];
 async function isTracked(repoRoot, relFile) {
   const gitPath = relFile.replace(/\\/g, "/");
@@ -9062,11 +9797,11 @@ async function isTracked(repoRoot, relFile) {
 async function copyMachineLocalFiles(mainMemberPath, worktreeMemberPath) {
   const copied = [];
   for (const rel of MACHINE_LOCAL_FILES) {
-    const src = path55.join(mainMemberPath, rel);
+    const src = path56.join(mainMemberPath, rel);
     if (!await fs40.pathExists(src)) continue;
     if (await isTracked(mainMemberPath, rel)) continue;
-    const dest = path55.join(worktreeMemberPath, rel);
-    await fs40.ensureDir(path55.dirname(dest));
+    const dest = path56.join(worktreeMemberPath, rel);
+    await fs40.ensureDir(path56.dirname(dest));
     await fs40.copy(src, dest, { overwrite: true });
     copied.push(rel);
   }
@@ -9075,15 +9810,15 @@ async function copyMachineLocalFiles(mainMemberPath, worktreeMemberPath) {
 
 // src/workspace/worktree/root.ts
 import { existsSync as existsSync4 } from "node:fs";
-import path56 from "node:path";
+import path57 from "node:path";
 async function resolveWorkspaceForWorktree(start) {
   const rootInfo = await resolveRoots(start);
   if (!rootInfo.isGitRepo) {
     return { ok: false, reason: "Not inside a git repository." };
   }
   const workspaceRoot = rootInfo.mainRoot;
-  const hasYaml = existsSync4(path56.join(workspaceRoot, WORKSPACE_FILE));
-  const hasManifest = existsSync4(path56.join(workspaceRoot, REPOS_MANIFEST_FILE));
+  const hasYaml = existsSync4(path57.join(workspaceRoot, WORKSPACE_FILE));
+  const hasManifest = existsSync4(path57.join(workspaceRoot, REPOS_MANIFEST_FILE));
   if (!hasYaml && !hasManifest) {
     return {
       ok: false,
@@ -9108,10 +9843,10 @@ function selectMembers(members, only) {
 }
 
 // src/workspace/worktree/state.ts
-import path57 from "node:path";
+import path58 from "node:path";
 var WORKTREE_STATE_FILE = ".haus-worktree.json";
 function worktreesDir(mainRoot) {
-  return path57.join(mainRoot, ".claude", "worktrees");
+  return path58.join(mainRoot, ".claude", "worktrees");
 }
 function isValidWorktreeSlug(slug) {
   if (slug === "" || slug === "." || slug === "..") return false;
@@ -9124,15 +9859,15 @@ function worktreePath(mainRoot, slug) {
       `Invalid worktree slug ${JSON.stringify(slug)} \u2014 slugs may only contain letters, digits, ".", "_", "-" (no path separators, and not "." or "..").`
     );
   }
-  return path57.join(worktreesDir(mainRoot), slug);
+  return path58.join(worktreesDir(mainRoot), slug);
 }
 async function readWorktreeState(worktreeRoot) {
-  const state = await readJson(path57.join(worktreeRoot, WORKTREE_STATE_FILE));
+  const state = await readJson(path58.join(worktreeRoot, WORKTREE_STATE_FILE));
   if (state == null || typeof state !== "object" || !Array.isArray(state.members)) return void 0;
   return state;
 }
 async function writeWorktreeState(worktreeRoot, state) {
-  await writeJson(path57.join(worktreeRoot, WORKTREE_STATE_FILE), state);
+  await writeJson(path58.join(worktreeRoot, WORKTREE_STATE_FILE), state);
 }
 
 // src/workspace/worktree/add.ts
@@ -9166,7 +9901,7 @@ async function runAdd(opts) {
   const memberResults = [];
   for (const member of selected) {
     const start = Date.now();
-    const memberWorktreePath = path58.join(wsWorktreePath, member.folder);
+    const memberWorktreePath = path59.join(wsWorktreePath, member.folder);
     const outcome = await addWorktree(member.absPath, memberWorktreePath, branch, {
       preferDefaultBranchFrom: true
     });
@@ -9196,7 +9931,7 @@ async function runAdd(opts) {
   await mapWithConcurrency(okResults, async (result) => {
     const member = selected.find((m) => m.id === result.member);
     if (!member) return;
-    const memberWorktreePath = path58.join(wsWorktreePath, member.folder);
+    const memberWorktreePath = path59.join(wsWorktreePath, member.folder);
     const hydrationStart = Date.now();
     if (opts.hydrate !== false) {
       result.hydration = await hydrateMember(member.absPath, memberWorktreePath);
@@ -9263,10 +9998,10 @@ async function runDryRun(args) {
 
 // src/workspace/worktree/doctor.ts
 import { existsSync as existsSync5 } from "node:fs";
-import path59 from "node:path";
+import path60 from "node:path";
 var HYDRATION_MARKERS = ["node_modules", "vendor", "obj", "bin"];
 function looksHydrated(memberPath) {
-  return HYDRATION_MARKERS.some((marker) => existsSync5(path59.join(memberPath, marker)));
+  return HYDRATION_MARKERS.some((marker) => existsSync5(path60.join(memberPath, marker)));
 }
 async function runDoctor2() {
   const rootInfo = await resolveRoots();
@@ -9280,7 +10015,7 @@ async function runDoctor2() {
     };
   }
   const workspaceRoot = rootInfo.mainRoot;
-  const isWorkspace = existsSync5(path59.join(workspaceRoot, WORKSPACE_FILE)) || existsSync5(path59.join(workspaceRoot, REPOS_MANIFEST_FILE));
+  const isWorkspace = existsSync5(path60.join(workspaceRoot, WORKSPACE_FILE)) || existsSync5(path60.join(workspaceRoot, REPOS_MANIFEST_FILE));
   if (!isWorkspace) {
     return {
       isWorkspace: false,
@@ -9293,7 +10028,7 @@ async function runDoctor2() {
     };
   }
   const wsWorktreesDir = worktreesDir(workspaceRoot);
-  const underWorktreesDir = rootInfo.repoRoot.startsWith(`${wsWorktreesDir}${path59.sep}`);
+  const underWorktreesDir = rootInfo.repoRoot.startsWith(`${wsWorktreesDir}${path60.sep}`);
   const inWorkspaceWorktree = rootInfo.isLinkedWorktree && underWorktreesDir;
   const members = await readMembers(rootInfo);
   const problems = [];
@@ -9301,10 +10036,10 @@ async function runDoctor2() {
   let slug;
   if (inWorkspaceWorktree) {
     const wtPath = rootInfo.repoRoot;
-    slug = rootInfo.worktreeName ?? path59.basename(wtPath);
+    slug = rootInfo.worktreeName ?? path60.basename(wtPath);
     const state = await readWorktreeState(wtPath);
     for (const member of members) {
-      const memberPath = path59.join(wtPath, member.folder);
+      const memberPath = path60.join(wtPath, member.folder);
       const materialized = existsSync5(memberPath);
       const expectedBranch = state?.members.find((m) => m.folder === member.folder)?.branch ?? state?.branch;
       const actualBranch = materialized ? await currentBranch(memberPath) : void 0;
@@ -9335,16 +10070,16 @@ async function runDoctor2() {
   for (const member of members) {
     const entries = await listWorktrees(member.absPath);
     for (const entry of entries) {
-      const entryPath = path59.normalize(entry.path);
-      const marker = `${path59.sep}.claude${path59.sep}worktrees${path59.sep}`;
+      const entryPath = path60.normalize(entry.path);
+      const marker = `${path60.sep}.claude${path60.sep}worktrees${path60.sep}`;
       const idx = entryPath.indexOf(marker);
       if (idx === -1) continue;
       const rest = entryPath.slice(idx + marker.length);
-      const slugName = rest.split(path59.sep)[0];
+      const slugName = rest.split(path60.sep)[0];
       if (!slugName) continue;
-      if (!existsSync5(path59.join(wsWorktreesDir, slugName))) {
+      if (!existsSync5(path60.join(wsWorktreesDir, slugName))) {
         orphans.push(
-          `${member.id}: worktree registered at ${entry.path} but ${path59.join(wsWorktreesDir, slugName)} no longer exists \u2014 run \`git -C "${member.absPath}" worktree prune\`.`
+          `${member.id}: worktree registered at ${entry.path} but ${path60.join(wsWorktreesDir, slugName)} no longer exists \u2014 run \`git -C "${member.absPath}" worktree prune\`.`
         );
       }
     }
@@ -9355,7 +10090,7 @@ async function runDoctor2() {
 
 // src/workspace/worktree/hydrate-command.ts
 import { existsSync as existsSync6 } from "node:fs";
-import path60 from "node:path";
+import path61 from "node:path";
 async function runHydrateWorktree(opts) {
   const rootInfo = await resolveRoots();
   if (!rootInfo.isGitRepo || !rootInfo.isLinkedWorktree) {
@@ -9366,7 +10101,7 @@ async function runHydrateWorktree(opts) {
   }
   const workspaceRoot = rootInfo.mainRoot;
   const wtPath = rootInfo.repoRoot;
-  if (!wtPath.startsWith(`${worktreesDir(workspaceRoot)}${path60.sep}`)) {
+  if (!wtPath.startsWith(`${worktreesDir(workspaceRoot)}${path61.sep}`)) {
     return {
       ok: false,
       error: "Current worktree is not one of this workspace's .claude/worktrees/<slug> checkouts."
@@ -9378,13 +10113,13 @@ async function runHydrateWorktree(opts) {
     return { ok: false, error: `Unknown --only repo(s): ${unknown.join(", ")}` };
   }
   const state = await readWorktreeState(wtPath);
-  const slug = state?.slug ?? path60.basename(wtPath);
+  const slug = state?.slug ?? path61.basename(wtPath);
   const detectedBranch = await currentBranch(wtPath);
   const targetBranch = state?.branch ?? (detectedBranch !== "HEAD" ? detectedBranch : void 0) ?? slug;
   if (opts.dryRun) {
     const results2 = await Promise.all(
       selected.map(async (member) => {
-        const memberPath = path60.join(wtPath, member.folder);
+        const memberPath = path61.join(wtPath, member.folder);
         if (existsSync6(memberPath)) {
           return { member: member.id, folder: member.folder, status: "planned" };
         }
@@ -9405,7 +10140,7 @@ async function runHydrateWorktree(opts) {
   const results = await mapWithConcurrency(
     selected,
     async (member) => {
-      const memberPath = path60.join(wtPath, member.folder);
+      const memberPath = path61.join(wtPath, member.folder);
       let branchAction;
       if (!existsSync6(memberPath)) {
         if (!opts.materialize) {
@@ -9468,7 +10203,7 @@ async function runHydrateWorktree(opts) {
 }
 
 // src/workspace/worktree/list.ts
-import path61 from "node:path";
+import path62 from "node:path";
 import fs42 from "fs-extra";
 async function runList2() {
   const resolved = await resolveWorkspaceForWorktree();
@@ -9481,12 +10216,12 @@ async function runList2() {
   const configuredMembers = await readMembers(rootInfo);
   const worktrees = [];
   for (const slug of slugs) {
-    const wtPath = path61.join(dir, slug);
+    const wtPath = path62.join(dir, slug);
     const state = await readWorktreeState(wtPath);
     const members = [];
     const source = state?.members ?? configuredMembers.map((m) => ({ id: m.id, folder: m.folder }));
     for (const m of source) {
-      const memberPath = path61.join(wtPath, m.folder);
+      const memberPath = path62.join(wtPath, m.folder);
       const materialized = await fs42.pathExists(memberPath);
       const actualBranch = materialized ? await currentBranch(memberPath) : void 0;
       members.push({
@@ -9508,7 +10243,7 @@ async function runList2() {
 }
 
 // src/workspace/worktree/remove.ts
-import path62 from "node:path";
+import path63 from "node:path";
 import fs43 from "fs-extra";
 async function runRemove(opts) {
   const resolved = await resolveWorkspaceForWorktree();
@@ -9535,7 +10270,7 @@ async function runRemove(opts) {
     targets.push({
       repo: configMember?.id ?? stateMember.id,
       ownerRepo,
-      path: path62.join(wsWorktreePath, stateMember.folder)
+      path: path63.join(wsWorktreePath, stateMember.folder)
     });
   }
   const existingTargets = [];
@@ -9603,12 +10338,6 @@ async function runRemove(opts) {
 }
 
 // src/commands/workspace/worktree.ts
-function normalizeOnly(only) {
-  if (!only) return void 0;
-  const list = Array.isArray(only) ? only : only.split(/[\s,]+/);
-  const cleaned = list.map((s) => s.trim()).filter(Boolean);
-  return cleaned.length > 0 ? cleaned : void 0;
-}
 function describeInstall(hydration) {
   if (hydration.install.plan.manager === "none") return "no install step (no recognized lockfile)";
   if (!hydration.install.ran)
@@ -9812,7 +10541,7 @@ async function runWorktree(action, opts = {}) {
 
 // src/commands/workspace.ts
 import { existsSync as existsSync10, statSync as statSync3 } from "node:fs";
-import path71 from "node:path";
+import path72 from "node:path";
 
 // src/commands/workspace/aggregate.ts
 async function writeWorkspaceArtifacts(workspaceRoot, repos, relationships = []) {
@@ -9867,18 +10596,18 @@ ${summaries.map(
 
 // src/commands/workspace/doctor.ts
 import { existsSync as existsSync7 } from "node:fs";
-import path64 from "node:path";
+import path65 from "node:path";
 
 // src/commands/workspace/manifest.ts
 import { readFileSync as readFileSync4 } from "node:fs";
-import path63 from "node:path";
+import path64 from "node:path";
 var MANIFEST_FILE = "workspace.manifest.json";
 function manifestPath(workspaceRoot) {
   return hausPath(workspaceRoot, MANIFEST_FILE);
 }
 function hausVersion() {
   try {
-    const pkg = JSON.parse(readFileSync4(path63.join(packageRoot(), "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync4(path64.join(packageRoot(), "package.json"), "utf8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -9970,7 +10699,7 @@ async function runWorkspaceDoctor(workspaceRoot, opts = {}) {
   const manifestByName = new Map(manifest.repos.map((r) => [r.name, r]));
   const catalogRefByRepo = [];
   for (const repo of config.repos) {
-    const repoRoot = path64.resolve(workspaceRoot, repo.path);
+    const repoRoot = path65.resolve(workspaceRoot, repo.path);
     const entry = manifestByName.get(repo.name);
     if (!entry) {
       flag({
@@ -10043,7 +10772,7 @@ async function runWorkspaceDoctor(workspaceRoot, opts = {}) {
         });
         continue;
       }
-      if (!existsSync7(path64.join(workspaceRoot, entry.path))) {
+      if (!existsSync7(path65.join(workspaceRoot, entry.path))) {
         flag({
           repo: entry.repo,
           kind: "missing-linked-context-copy",
@@ -10086,15 +10815,15 @@ function emit(args) {
 }
 
 // src/workspace/link-context/link.ts
-import path67 from "node:path";
+import path68 from "node:path";
 import fs46 from "fs-extra";
 
 // src/workspace/link-context/plan.ts
-import path66 from "node:path";
+import path67 from "node:path";
 import fs45 from "fs-extra";
 
 // src/workspace/link-context/scan-source.ts
-import path65 from "node:path";
+import path66 from "node:path";
 import fs44 from "fs-extra";
 var ASSET_SUBDIR = {
   skill: "skills",
@@ -10103,36 +10832,36 @@ var ASSET_SUBDIR = {
 };
 async function hasLinkableContext(member) {
   for (const subdir of Object.values(ASSET_SUBDIR)) {
-    if (await fs44.pathExists(path65.join(member.absPath, ".claude", subdir))) return true;
+    if (await fs44.pathExists(path66.join(member.absPath, ".claude", subdir))) return true;
   }
   return false;
 }
 async function collectSkills(member) {
-  const dir = path65.join(member.absPath, ".claude", "skills");
+  const dir = path66.join(member.absPath, ".claude", "skills");
   if (!await fs44.pathExists(dir)) return [];
   const names = await fs44.readdir(dir);
   const out = [];
   for (const name of [...names].sort()) {
-    const abs = path65.join(dir, name);
+    const abs = path66.join(dir, name);
     const stat = await fs44.lstat(abs);
     if (!stat.isDirectory()) continue;
-    if (!await fs44.pathExists(path65.join(abs, "SKILL.md"))) continue;
-    out.push({ type: "skill", name, sourceRelPath: path65.posix.join(".claude", "skills", name) });
+    if (!await fs44.pathExists(path66.join(abs, "SKILL.md"))) continue;
+    out.push({ type: "skill", name, sourceRelPath: path66.posix.join(".claude", "skills", name) });
   }
   return out;
 }
 async function collectFlatMarkdown(member, type) {
   const subdir = ASSET_SUBDIR[type];
-  const dir = path65.join(member.absPath, ".claude", subdir);
+  const dir = path66.join(member.absPath, ".claude", subdir);
   if (!await fs44.pathExists(dir)) return [];
   const names = await fs44.readdir(dir);
   const out = [];
   for (const fileName of [...names].sort()) {
     if (!fileName.endsWith(".md")) continue;
-    const abs = path65.join(dir, fileName);
+    const abs = path66.join(dir, fileName);
     if (!(await fs44.lstat(abs)).isFile()) continue;
     const name = fileName.slice(0, -".md".length);
-    out.push({ type, name, sourceRelPath: path65.posix.join(".claude", subdir, fileName) });
+    out.push({ type, name, sourceRelPath: path66.posix.join(".claude", subdir, fileName) });
   }
   return out;
 }
@@ -10147,9 +10876,9 @@ async function collectSourceAssets(member) {
 
 // src/workspace/link-context/plan.ts
 function repoFolderPrefix(member) {
-  const base = path66.posix.basename(member.folder);
+  const base = path67.posix.basename(member.folder);
   if (base && base !== "." && base !== "/") return base;
-  const fromAbs = path66.basename(member.absPath);
+  const fromAbs = path67.basename(member.absPath);
   return fromAbs || member.id;
 }
 function assetKey(type, destKey) {
@@ -10206,7 +10935,7 @@ async function buildLinkPlan(members) {
       name: asset.name,
       destKey,
       sourceRelPath: asset.sourceRelPath,
-      sourceAbsPath: path66.join(member.absPath, asset.sourceRelPath),
+      sourceAbsPath: path67.join(member.absPath, asset.sourceRelPath),
       sourceHash
     });
   }
@@ -10217,7 +10946,7 @@ async function buildLinkPlan(members) {
 function destRelPathFor(type, destKey) {
   const subdir = `${type}s`;
   const leaf = type === "skill" ? destKey : `${destKey}.md`;
-  return path67.posix.join(".claude", subdir, leaf);
+  return path68.posix.join(".claude", subdir, leaf);
 }
 async function runLinkContext(workspaceRoot, opts = {}) {
   const write = opts.write ?? false;
@@ -10243,9 +10972,9 @@ async function runLinkContext(workspaceRoot, opts = {}) {
   const linkedAt = (/* @__PURE__ */ new Date()).toISOString();
   for (const entry of plan.entries) {
     const destRel = destRelPathFor(entry.type, entry.destKey);
-    const destAbs = path67.join(workspaceRoot, destRel);
+    const destAbs = path68.join(workspaceRoot, destRel);
     if (write) {
-      await fs46.ensureDir(path67.dirname(destAbs));
+      await fs46.ensureDir(path68.dirname(destAbs));
       if (await fs46.pathExists(destAbs)) await fs46.remove(destAbs);
       await fs46.copy(entry.sourceAbsPath, destAbs, {
         overwrite: true,
@@ -10334,10 +11063,10 @@ async function runWorkspaceLinkContext(workspaceRoot, opts = {}) {
 
 // src/commands/workspace/setup.ts
 import { existsSync as existsSync8, statSync } from "node:fs";
-import path69 from "node:path";
+import path70 from "node:path";
 
 // src/claude/write-workspace-claude-md.ts
-import path68 from "node:path";
+import path69 from "node:path";
 import fs47 from "fs-extra";
 var WORKSPACE_SENTINELS = { begin: WORKSPACE_BLOCK_BEGIN, end: WORKSPACE_BLOCK_END };
 function buildWorkspaceImportBlock(client, members) {
@@ -10357,7 +11086,7 @@ ${WORKSPACE_BLOCK_END}`;
 async function writeWorkspaceClaudeMd(workspaceRoot, opts) {
   const block = buildWorkspaceImportBlock(opts.client, opts.members);
   const dryRun = opts.dryRun ?? false;
-  const filePath = opts.collision ? hausPath(workspaceRoot, "WORKSPACE.md") : path68.join(workspaceRoot, "CLAUDE.md");
+  const filePath = opts.collision ? hausPath(workspaceRoot, "WORKSPACE.md") : path69.join(workspaceRoot, "CLAUDE.md");
   const say = opts.quiet ? () => {
   } : log;
   const existed = await fs47.pathExists(filePath);
@@ -10388,20 +11117,20 @@ async function writeWorkspaceClaudeMd(workspaceRoot, opts) {
 
 // src/commands/workspace/setup.ts
 function resolveWorkspaceRoot(start = process.cwd()) {
-  let dir = path69.resolve(start);
+  let dir = path70.resolve(start);
   for (; ; ) {
-    if (existsSync8(path69.join(dir, WORKSPACE_FILE))) return dir;
-    const parent = path69.dirname(dir);
-    if (parent === dir) return path69.resolve(start);
+    if (existsSync8(path70.join(dir, WORKSPACE_FILE))) return dir;
+    const parent = path70.dirname(dir);
+    if (parent === dir) return path70.resolve(start);
     dir = parent;
   }
 }
 function isRootRepo(workspaceRoot, repoPath) {
-  return path69.resolve(workspaceRoot, repoPath) === path69.resolve(workspaceRoot);
+  return path70.resolve(workspaceRoot, repoPath) === path70.resolve(workspaceRoot);
 }
 async function runWorkspaceSetup(workspaceRoot, options = {}) {
   const apply = options.write ?? false;
-  const configText = await readText(path69.join(workspaceRoot, WORKSPACE_FILE));
+  const configText = await readText(path70.join(workspaceRoot, WORKSPACE_FILE));
   if (!configText) {
     error(`Missing ${WORKSPACE_FILE}. Run \`haus workspace discover\` or \`init\` first.`);
     process.exitCode = 1;
@@ -10428,7 +11157,7 @@ async function runWorkspaceSetup(workspaceRoot, options = {}) {
   const statuses = [];
   const aggregateInputs = [];
   for (const repo of repos) {
-    const repoRoot = path69.resolve(workspaceRoot, repo.path);
+    const repoRoot = path70.resolve(workspaceRoot, repo.path);
     say(`
 \u2192 ${repo.name} (${repo.path})`);
     try {
@@ -10468,7 +11197,7 @@ async function runWorkspaceSetup(workspaceRoot, options = {}) {
           process.exitCode = 1;
           return result2;
         }
-        throw err;
+        throw new Error(`Setup failed for ${repo.name}: ${message}`, { cause: err });
       }
       error(`Setup failed for ${repo.name}: ${message}`);
     }
@@ -10518,7 +11247,7 @@ async function runWorkspaceSetup(workspaceRoot, options = {}) {
       const status = statusByName.get(repo.name);
       const role = repo.role ?? status?.roles?.[0] ?? "auto";
       if (status?.status === "ok") {
-        const lock = await checkLock(path69.resolve(workspaceRoot, repo.path));
+        const lock = await checkLock(path70.resolve(workspaceRoot, repo.path));
         manifestRepos.push({
           name: repo.name,
           path: repo.path,
@@ -10574,7 +11303,7 @@ async function runWorkspaceSetup(workspaceRoot, options = {}) {
     try {
       const linkResult = await runLinkContext(workspaceRoot, { write: true, json: options.json });
       if (linkResult.ok) {
-        written.push(...linkResult.added.map((rel) => path69.join(workspaceRoot, rel)));
+        written.push(...linkResult.added.map((rel) => path70.join(workspaceRoot, rel)));
         if (!options.json) {
           say(
             `Linked ${linkResult.linked.length} cross-repo skill/agent/command copy(ies) into .claude/ (${linkResult.added.length} new, ${linkResult.removed.length} removed)${linkResult.skipped.length > 0 ? ` \u2014 ${linkResult.skipped.length} member(s) skipped, see above` : ""}.`
@@ -10606,7 +11335,7 @@ Workspace setup complete: ${ok} ok, ${failed} failed. Wrote ${written.length} fi
 
 // src/commands/workspace/undo.ts
 import { existsSync as existsSync9, statSync as statSync2 } from "node:fs";
-import path70 from "node:path";
+import path71 from "node:path";
 import fs48 from "fs-extra";
 var WORKSPACE_AGGREGATE_FILES = [
   "workspace-summary.json",
@@ -10643,7 +11372,7 @@ async function runWorkspaceUndo(workspaceRoot, options = {}) {
   }
   let anyRepoFailed = false;
   for (const repo of config.repos) {
-    const repoRoot = path70.resolve(workspaceRoot, repo.path);
+    const repoRoot = path71.resolve(workspaceRoot, repo.path);
     log(`
 \u2192 ${repo.name} (${repo.path})`);
     try {
@@ -10672,20 +11401,20 @@ async function runWorkspaceUndo(workspaceRoot, options = {}) {
     const abs = hausPath(workspaceRoot, rel);
     if (await fs48.pathExists(abs)) {
       await fs48.remove(abs);
-      log(`Removed ${path70.relative(workspaceRoot, abs)}`);
+      log(`Removed ${path71.relative(workspaceRoot, abs)}`);
     }
   }
   const manifestFile = manifestPath(workspaceRoot);
   if (await fs48.pathExists(manifestFile)) {
     await fs48.remove(manifestFile);
-    log(`Removed ${path70.relative(workspaceRoot, manifestFile)}`);
+    log(`Removed ${path71.relative(workspaceRoot, manifestFile)}`);
   }
   const workspaceMdPath = hausPath(workspaceRoot, "WORKSPACE.md");
   if (await fs48.pathExists(workspaceMdPath)) {
     await fs48.remove(workspaceMdPath);
-    log(`Removed ${path70.relative(workspaceRoot, workspaceMdPath)}`);
+    log(`Removed ${path71.relative(workspaceRoot, workspaceMdPath)}`);
   } else {
-    const claudeMdPath = path70.join(workspaceRoot, "CLAUDE.md");
+    const claudeMdPath = path71.join(workspaceRoot, "CLAUDE.md");
     if (existsSync9(claudeMdPath)) {
       const prev = await readText(claudeMdPath);
       if (prev?.includes(WORKSPACE_BLOCK_BEGIN)) {
@@ -10724,12 +11453,6 @@ async function runWorkspaceUndo(workspaceRoot, options = {}) {
 }
 
 // src/commands/workspace.ts
-function normalizeOnly2(only) {
-  if (!only) return void 0;
-  const list = Array.isArray(only) ? only : only.split(/[\s,]+/);
-  const cleaned = list.map((s) => s.trim()).filter(Boolean);
-  return cleaned.length > 0 ? cleaned : void 0;
-}
 function normalizeMaxDepth(maxDepth) {
   if (maxDepth === void 0) return void 0;
   const n = typeof maxDepth === "number" ? maxDepth : Number.parseInt(maxDepth, 10);
@@ -10760,7 +11483,7 @@ relationships: []
   log("Workspace initialized.");
 }
 async function scanWorkspace(workspaceRoot, opts) {
-  const configText = await readText(path71.join(workspaceRoot, WORKSPACE_FILE));
+  const configText = await readText(path72.join(workspaceRoot, WORKSPACE_FILE));
   if (!configText) {
     error(`Missing ${WORKSPACE_FILE}. Run \`haus workspace discover\` or \`init\` first.`);
     process.exitCode = 1;
@@ -10782,7 +11505,7 @@ async function scanWorkspace(workspaceRoot, opts) {
   const inputs = [];
   const failures = [];
   for (const repo of config.repos) {
-    const repoRoot = path71.resolve(workspaceRoot, repo.path);
+    const repoRoot = path72.resolve(workspaceRoot, repo.path);
     try {
       if (!existsSync10(repoRoot) || !statSync3(repoRoot).isDirectory()) {
         throw new Error("path is not a directory");
@@ -10830,7 +11553,7 @@ async function runWorkspace(action, options = {}) {
         dryRun: options.dryRun,
         json: options.json,
         continueOnError: options.continueOnError,
-        only: normalizeOnly2(options.only)
+        only: normalizeOnly(options.only)
       });
       return;
     case "doctor":
@@ -10848,7 +11571,7 @@ async function runWorkspace(action, options = {}) {
 // src/cli.ts
 function cliVersion() {
   try {
-    const pkgPath = path72.join(packageRoot(), "package.json");
+    const pkgPath = path73.join(packageRoot(), "package.json");
     const pkg = JSON.parse(readFileSync5(pkgPath, "utf8"));
     return pkg.version ?? "0.0.0";
   } catch {
@@ -10858,7 +11581,7 @@ function cliVersion() {
 var program = new Command();
 function validateRuntimeNodeVersion() {
   try {
-    const pkgPath = path72.join(packageRoot(), "package.json");
+    const pkgPath = path73.join(packageRoot(), "package.json");
     const pkg = JSON.parse(readFileSync5(pkgPath, "utf8"));
     const requiredRange = pkg.engines?.node;
     if (requiredRange && !satisfiesVersion(process.version, requiredRange)) {
@@ -10872,18 +11595,22 @@ function validateRuntimeNodeVersion() {
 }
 validateRuntimeNodeVersion();
 program.name("haus").description("Haus AI workflow CLI").version(cliVersion());
-program.command("scan").option("--json").action(runScan);
-program.command("recommend").option("--json").option(
+program.command("scan").description(
+  "Scan the repo for roles, dependencies, and package manager; writes context-map.json"
+).option("--json").action(runScan);
+program.command("recommend").description("Score catalog items against the scanned context and write recommendation.json").option("--json").option(
   "--include <ids...>",
   "Force opt-in catalog items into the recommendation as manual selections (space- or comma-separated ids)"
 ).action(runRecommend);
-program.command("setup-project").option("--json").option(
+program.command("setup-project").description("Fast full setup: scan, recommend, and optionally apply Claude files").option("--json").option(
   "--force",
   "Write recommendation.json/haus.lock.json even when zero catalog items matched at all"
 ).action(runSetupProject);
-program.command("doctor").option("--hooks", "Verify .claude/settings.json matches the hook contract").action(runDoctor);
+program.command("doctor").description(
+  "Validate project setup: hooks contract, managed files, cache freshness, CLI version"
+).option("--hooks", "Verify .claude/settings.json matches the hook contract").action(runDoctor);
 program.command("fetch-refs").description("Fetch and cache llms.txt content from catalog item references").option("--all", "Fetch for all catalog items (default)").option("--id <id>", "Fetch for a single catalog item by id").option("--json", "Emit machine-readable JSON summary to stdout").action(runFetchRefs);
-program.command("apply").option("--dry-run").option("--write").option("--select", "Interactively select catalog items before applying").option(
+program.command("apply").description("Write recommended catalog items and core Claude files to .claude/").option("--dry-run").option("--write").option("--select", "Interactively select catalog items before applying").option(
   "--ids <ids...>",
   "Install exactly these recommended item ids non-interactively (skill backend; space- or comma-separated)"
 ).option(
@@ -10896,33 +11623,33 @@ program.command("apply").option("--dry-run").option("--write").option("--select"
   "--prune",
   "Remove lock-tracked catalog items no longer in the current recommendation (hash-gated, backed up first)"
 ).action(runApply);
-program.command("undo").option("-y, --yes", "Skip confirmation").action(runUndo);
-var backups = program.command("backups");
+program.command("undo").description("Remove haus-managed project files; preserves user-owned .claude/ content").option("-y, --yes", "Skip confirmation").action(runUndo);
+var backups = program.command("backups").description("List, restore, or prune backups under .haus-workflow/backups/");
 backups.command("list").description("List backups under .haus-workflow/backups/").action(() => runBackups("list"));
 backups.command("restore <id>").description("Restore a specific backup by id (see `haus backups list`)").option("-y, --yes", "Skip confirmation").action((id, opts) => runBackups("restore", { id, yes: opts.yes }));
 backups.command("prune").description("Delete old backups by age and/or count (requires --older-than or --keep)").option("--older-than <days>", "Remove backups older than N days").option("--keep <n>", "Keep only the N most recent backups").option("-y, --yes", "Skip confirmation").action(
   (opts) => runBackups("prune", { olderThan: opts.olderThan, keep: opts.keep, yes: opts.yes })
 );
-program.command("explain-recommendation").option("--json").action(runExplainRecommendation);
-program.command("init").option("--json").action(runInit);
+program.command("explain-recommendation").description("Print a per-item breakdown of the current recommendation, with skip reasons").option("--json").action(runExplainRecommendation);
+program.command("init").description("First-run setup; delegates to setup-project if .haus-workflow/ does not exist").option("--json").action(runInit);
 program.command("clone").description("Clone a single git repository by URL").argument("<url>", "Git URL to clone").argument("[dir]", "Target directory (default: repo name derived from the URL)").option("--dry-run", "Print what would happen without cloning").action(
   (url, dir, opts) => runClone(url, { dir, dryRun: opts.dryRun })
 );
-program.command("refresh").action(runRefresh);
-program.command("catalog-audit").action(runCatalogAudit);
-program.command("validate-catalog").argument("[manifest]").action(runValidateCatalog);
-program.command("update").option("--check").option("--fast", "With --check, skip per-item content hashing (cheap count+ref only)").option("--from-hook", "Emit JSON for the Claude Code SessionStart hook (silent if up to date)").action(runUpdate);
+program.command("refresh").description("Re-scan the project, refresh recommendations, and update scan artifacts").action(runRefresh);
+program.command("catalog-audit").description("Check the bundled catalog manifest for unsupported or forbidden stacks").action(runCatalogAudit);
+program.command("validate-catalog").description("Validate a catalog manifest at an explicit path").argument("[manifest]").action(runValidateCatalog);
+program.command("update").description("Sync the remote catalog cache, refresh the lockfile, and check for CLI updates").option("--check").option("--fast", "With --check, skip per-item content hashing (cheap count+ref only)").option("--from-hook", "Emit JSON for the Claude Code SessionStart hook (silent if up to date)").action(runUpdate);
 program.command("ci-gate").description(
   "Aggregate `doctor` + `decisions check` + `update --check --fast` into one pass/fail gate for CI. Uses the fast/cheap update-check tier (no per-item content hashing) to keep CI runs quick \u2014 run `haus update --check` directly for the fully-hashed tier. Each constituent command remains independently runnable with its own unchanged exit-code contract."
 ).option("--json", "Emit machine-readable {doctor, decisions, update, ok}").action((opts) => runCiGate(opts));
-program.command("install").option("--dry-run").option("--force").option("--check", "Exit non-zero if any HAUS-MANAGED file is out of date").option("--postinstall", "Run by the npm postinstall hook; prints a plain-language change notice").action(runInstall);
+program.command("install").description("Seed ~/.claude/ with Haus-managed skills, agents, and hook settings").option("--dry-run").option("--force").option("--check", "Exit non-zero if any HAUS-MANAGED file is out of date").option("--postinstall", "Run by the npm postinstall hook; prints a plain-language change notice").action(runInstall);
 program.command("scaffold [ids...]").description(
   "Copy catalog config items (ESLint, Prettier) into the project root. Pass item IDs to scaffold specific items, or omit to scaffold all available config items."
 ).option("--force", "Overwrite existing files").option("--dry-run", "Preview what would be written without changing anything").option("--root <path>", "Project root (defaults to cwd)", process.cwd()).action(runScaffold);
-program.command("uninstall").option("--force").option("-y, --yes", "Skip confirmation").action(runUninstallCommand);
-var guard = program.command("guard");
-guard.command("file-access").option("--from-hook").action((opts) => runGuard("file-access", opts));
-guard.command("bash").option("--from-hook").action((opts) => runGuard("bash", opts));
+program.command("uninstall").description("Remove Haus-managed skills, agents, and hook entries from ~/.claude/").option("--force").option("-y, --yes", "Skip confirmation").action(runUninstallCommand);
+var guard = program.command("guard").description("PreToolUse hook guards: block dangerous bash commands and sensitive file access");
+guard.command("file-access").description("Block reads/edits of sensitive paths (run by the Claude Code hook)").option("--from-hook").action((opts) => runGuard("file-access", opts));
+guard.command("bash").description("Block dangerous shell commands (run by the Claude Code hook)").option("--from-hook").action((opts) => runGuard("bash", opts));
 function registerDecisionsCommand(name) {
   const cmd = program.command(name).description("Architecture decision records (ADR) gate and drafts");
   cmd.command("check").option("--staged", "Check staged changes only").option("--range <range>", "Git revision range (e.g. origin/main..HEAD)").action((opts) => runDecisions("check", void 0, opts));
@@ -10935,7 +11662,7 @@ function registerDecisionsCommand(name) {
 }
 registerDecisionsCommand("decisions");
 registerDecisionsCommand("adr");
-var workspace = program.command("workspace");
+var workspace = program.command("workspace").description("Multi-repo workspace commands: discover, setup, link-context, worktree, doctor");
 workspace.command("init").option("-y, --yes", "Skip confirmation when haus.workspace.yaml already exists").action((opts) => runWorkspace("init", opts));
 workspace.command("discover").description("Auto-find member repos and write/merge haus.workspace.yaml").option("--write", "Persist haus.workspace.yaml (default previews only)").option("--json", "Output the discovered repos and proposed config as JSON").option("--max-depth <n>", "Max directory depth to traverse (default 3)").option("--client <name>", "Set the workspace client name").action((opts) => runWorkspace("discover", opts));
 workspace.command("scan").description("Aggregate a cross-repo summary from a fast scan of each repo").option("--json", "Output the written artifact paths as JSON").action((opts) => runWorkspace("scan", opts));