@haus-tech/haus-workflow 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.31.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.30.0...v0.31.0) (2026-06-23)
+
+### Features
+
+- opt-in UX for tiered skills + config scaffold ([#141](https://github.com/WeAreHausTech/haus-workflow/issues/141)) ([f60207b](https://github.com/WeAreHausTech/haus-workflow/commit/f60207b78af4651656d457c6f80665bd25deaa7f)), closes [#33](https://github.com/WeAreHausTech/haus-workflow/issues/33) [#33](https://github.com/WeAreHausTech/haus-workflow/issues/33)
+
+## [0.30.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.29.0...v0.30.0) (2026-06-22)
+
+### Features
+
+- auto recommend config setups ([#137](https://github.com/WeAreHausTech/haus-workflow/issues/137)) ([56e7941](https://github.com/WeAreHausTech/haus-workflow/commit/56e79413a6cfe00e35f5e48abd03baeeb377214f))
+- **cloneandsetup:** reuse local env values, never commit secrets ([#130](https://github.com/WeAreHausTech/haus-workflow/issues/130)) ([cf74a19](https://github.com/WeAreHausTech/haus-workflow/commit/cf74a196d369fbc59798de97e76bbcd3120155f7))
+- co-install suppression and recommender gates ([#134](https://github.com/WeAreHausTech/haus-workflow/issues/134)) ([4ca1f20](https://github.com/WeAreHausTech/haus-workflow/commit/4ca1f20a6b90645cd7007d195e6cc474558cc971))
+- curated source tools exempt from non-tsx npx ban and update archetype dependencies ([#132](https://github.com/WeAreHausTech/haus-workflow/issues/132)) ([a63d0b2](https://github.com/WeAreHausTech/haus-workflow/commit/a63d0b224ee9d1fd7b686b9aa3979562228f2333))
+- prune deprecated catalog items on apply/update ([#126](https://github.com/WeAreHausTech/haus-workflow/issues/126)) ([fdf6ecc](https://github.com/WeAreHausTech/haus-workflow/commit/fdf6ecc1d36f4eb090cdaa8d9b044381c5836c77))
+- stripe server gate [#139](https://github.com/WeAreHausTech/haus-workflow/issues/139) ([fb2dc35](https://github.com/WeAreHausTech/haus-workflow/commit/fb2dc35b0d332cdd6f3c7dcbaebef94dce06899c))
+
 ## [0.29.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.28.1...v0.29.0) (2026-06-17)
 
 ### Features

package/README.md

@@ -82,8 +82,14 @@ Content lives in [`haus-workflow-catalog`](https://github.com/WeAreHausTech/haus
 (version pinned in `library/catalog/manifest.json`). Fetched at runtime from the latest release tag (override with `HAUS_CATALOG_REF`; fallback `main` when no release tag resolves).
 Validation rules sync from catalog → `library/catalog/validation-rules.json` (ADR-0001).
 
-On `haus apply` / `haus update`, items **removed from the catalog** are pruned from the
-project when their on-disk copy still matches the lock hash; user-edited copies are kept.
+On `haus apply` / `haus update`, items **removed from the catalog** or marked
+**deprecated** are pruned from the project when their on-disk copy still matches the
+lock hash; user-edited copies are kept. Approved items deselected via `--select` are
+not pruned.
+
+> **Upgrading from a pre-`0.30.0` CLI:** deprecated-skill pruning shipped in `0.30.0`.
+> If an older CLI left deprecated skills on disk, upgrade first
+> (`npm i -g @haus-tech/haus-workflow`) then run `haus update` to prune them.
 
 ## Internal docs
 

package/dist/cli.js

@@ -154,7 +154,7 @@ var validation_rules_default = {
   ],
   allowedNpxPattern: { source: "\\bnpx\\s+tsx\\b", flags: "i" },
   anyNpxPattern: { source: "\\bnpx\\s+\\S+", flags: "i" },
-  npxTsxOnlyExemptTypes: ["agent"],
+  npxTsxOnlyExemptSources: ["curated"],
   httpUrlPattern: { source: "^http:\\/\\/", flags: "i" },
   placeholderPattern: { source: "\\bTODO\\b|\\bPLACEHOLDER\\b", flags: "i" },
   allowedStacks: [
@@ -274,7 +274,29 @@ var REQUIRED_SKILL_FRONTMATTER = validation_rules_default.requiredSkillFrontmatt
 var RISKY_INSTALL_PATTERNS = validation_rules_default.riskyInstallPatterns.map(toRegExp);
 var ALLOWED_NPX_PATTERN = toRegExp(validation_rules_default.allowedNpxPattern);
 var ANY_NPX_PATTERN = toRegExp(validation_rules_default.anyNpxPattern);
-var NPX_TSX_ONLY_EXEMPT_TYPES = validation_rules_default.npxTsxOnlyExemptTypes ?? [];
+var NPX_TSX_ONLY_EXEMPT_SOURCES = validation_rules_default.npxTsxOnlyExemptSources ?? [];
+function isNpxTsxOnlyExempt(_itemType, itemSource) {
+  return Boolean(itemSource && NPX_TSX_ONLY_EXEMPT_SOURCES.includes(itemSource));
+}
+function buildItemPathSourceMap(items) {
+  const map = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    if (!item.path) continue;
+    map.set(String(item.path).replace(/\\/g, "/"), item.source);
+  }
+  return map;
+}
+function resolveMarkdownItemSource(relPath, pathSourceMap) {
+  const norm = relPath.replace(/\\/g, "/");
+  let cursor = norm;
+  while (true) {
+    if (pathSourceMap.has(cursor)) return pathSourceMap.get(cursor);
+    const slash = cursor.lastIndexOf("/");
+    if (slash === -1) break;
+    cursor = cursor.slice(0, slash);
+  }
+  return void 0;
+}
 var HTTP_URL_PATTERN = toRegExp(validation_rules_default.httpUrlPattern);
 var PLACEHOLDER_PATTERN = toRegExp(validation_rules_default.placeholderPattern);
 var ALLOWED_STACKS = validation_rules_default.allowedStacks;
@@ -353,7 +375,7 @@ ${extractUseWhenSection(text)}`;
 // src/catalog/ingest-catalog.ts
 function validateCatalogItem(item, content2) {
   const label = item.id;
-  const checkNonTsxNpx = !NPX_TSX_ONLY_EXEMPT_TYPES.includes(item.type);
+  const checkNonTsxNpx = !isNpxTsxOnlyExempt(item.type, item.source);
   const lines = content2.split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
     const line2 = lines[i] ?? "";
@@ -803,7 +825,12 @@ async function syncDirectoryFromPrefix(item, catalogPrefix, destDir, base, opts)
     for (const file of fetched) {
       if (file.kind !== "text" || !isMarkdownPath(file.rel)) continue;
       const verdict = validateCatalogItem(
-        { id: item.id, type: "skill", path: catalogPrefix },
+        {
+          id: item.id,
+          type: "skill",
+          path: catalogPrefix,
+          ..."source" in item && item.source ? { source: item.source } : {}
+        },
         file.body
       );
       if (!verdict.ok) {
@@ -2291,7 +2318,7 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
       `${curatedReviewStatusSkips} curated items skipped: reviewStatus is not approved \u2014 possible catalog field rename upstream`
     );
   }
-  await cleanupStaleCatalogItems(root, new Set(manifestById.keys()), dryRun);
+  await cleanupStaleCatalogItems(root, manifestById, dryRun);
   if (dryRun) return [...new Set(files)];
   const installedItems = catalogItems.filter((r) => installedIds.has(r.id));
   const prevLock = await readJson(hausPath(root, "haus.lock.json"));
@@ -2328,11 +2355,15 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
   await writeManagedJson(root, hausPath(root, "haus.lock.json"), lock, false);
   return [...new Set(files)];
 }
-async function cleanupStaleCatalogItems(root, knownIds, dryRun) {
+async function cleanupStaleCatalogItems(root, manifestById, dryRun) {
   const prevLock = await readJson(hausPath(root, "haus.lock.json"));
   if (!prevLock?.length) return;
   for (const entry of prevLock) {
-    if (!entry.id || knownIds.has(entry.id)) continue;
+    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 relPaths = entry.paths ?? [];
     if (relPaths.length === 0) continue;
     const existing = [];
@@ -2340,37 +2371,48 @@ async function cleanupStaleCatalogItems(root, knownIds, dryRun) {
       if (await fs12.pathExists(path12.join(root, rel))) existing.push(rel);
     }
     if (existing.length === 0) continue;
+    const pruneReason = deprecated ? "deprecated" : "stale";
     if (entry.hash === void 0) {
       warn(
-        `Stale catalog item ${entry.id} has no lock hash \u2014 leaving in place: ${existing.join(", ")}`
+        `${deprecated ? "Deprecated" : "Stale"} catalog item ${entry.id} has no lock hash \u2014 leaving in place: ${existing.join(", ")}`
       );
       continue;
     }
     const currentHash = await hashInstalledPaths(root, relPaths);
     if (currentHash !== entry.hash) {
       warn(
-        `Stale catalog item ${entry.id} was modified locally \u2014 leaving in place: ${existing.join(", ")}`
+        `${deprecated ? "Deprecated" : "Stale"} catalog item ${entry.id} was modified locally \u2014 leaving in place: ${existing.join(", ")}`
       );
       continue;
     }
     for (const rel of existing) {
       const abs = path12.join(root, rel);
       if (dryRun) {
-        log(`[dry-run] would remove stale ${displayPath(root, abs)} (${entry.id})`);
+        log(`[dry-run] would remove ${pruneReason} ${displayPath(root, abs)} (${entry.id})`);
         continue;
       }
       await fs12.remove(abs);
       await pruneEmptyDir(path12.dirname(abs));
-      log(`Removed stale ${displayPath(root, abs)} (${entry.id})`);
+      log(`Removed ${pruneReason} ${displayPath(root, abs)} (${entry.id})`);
     }
   }
 }
 
+// src/utils/args.ts
+function parseIdList(value) {
+  if (!value) return [];
+  const raw = Array.isArray(value) ? value : [value];
+  return raw.flatMap((v) => v.split(",")).map((v) => v.trim()).filter((v) => v.length > 0);
+}
+
 // src/commands/apply.ts
 async function cacheHasItems() {
   const data = await readJson(path13.join(getCacheDir(), "manifest.json"));
   return Array.isArray(data?.items) && data.items.length > 0;
 }
+function installableRecommendedItems(recommended) {
+  return recommended.filter((item) => item.install !== false);
+}
 async function runApply(options) {
   if (!options.dryRun && !options.write) {
     log("Use --dry-run or --write");
@@ -2379,6 +2421,34 @@ async function runApply(options) {
   const root = process.cwd();
   const isDryRun = Boolean(options.dryRun) && !options.write;
   let selectedIds;
+  const explicitIds = parseIdList(options.ids);
+  if (explicitIds.length > 0) {
+    if (options.select) {
+      error("Use either --select (interactive) or --ids (explicit), not both");
+      process.exitCode = 1;
+      return;
+    }
+    const rec = await readJson(hausPath(root, "recommendation.json"));
+    const recommended = rec?.recommended ?? [];
+    const installableIds = new Set(installableRecommendedItems(recommended).map((i) => i.id));
+    const configIds = new Set(recommended.filter((i) => i.install === false).map((i) => i.id));
+    const skippedIds = new Set((rec?.skipped ?? []).map((s) => s.id));
+    for (const id of explicitIds.filter((id2) => !installableIds.has(id2))) {
+      if (configIds.has(id)) {
+        warn(`--ids: "${id}" is a config item \u2014 install it with \`haus scaffold ${id}\`. Ignoring.`);
+      } else if (skippedIds.has(id)) {
+        warn(
+          `--ids: "${id}" is not currently recommended (skipped) \u2014 add it with \`haus recommend --include ${id}\` first. Ignoring.`
+        );
+      } else {
+        warn(
+          `--ids: "${id}" is not in recommendation.json \u2014 run \`haus recommend\` (or \`--include ${id}\`) first. Ignoring.`
+        );
+      }
+    }
+    selectedIds = explicitIds.filter((id) => installableIds.has(id));
+    log(`Applying ${selectedIds.length} explicitly selected catalog item(s).`);
+  }
   if (options.select) {
     if (!process.stdin.isTTY) {
       error("--select requires an interactive terminal (stdin is not a TTY)");
@@ -2389,28 +2459,31 @@ async function runApply(options) {
     if (!rec) {
       log("No recommendation.json found \u2014 run `haus recommend` first. Writing core files only.");
       selectedIds = [];
-    } else if (rec.recommended.length === 0) {
-      log("Recommendation contains no catalog items. Writing core files only.");
-      selectedIds = [];
     } else {
-      const items = rec.recommended;
-      const choices = items.map((item) => ({
-        name: `${item.id}  [${item.selectionMode}] \u2014 ${item.reason}`,
-        value: item.id,
-        checked: true
-      }));
-      const chosen = await checkbox({
-        message: "Select catalog items to apply (space to toggle, enter to confirm):",
-        choices,
-        pageSize: Math.min(20, items.length + 2)
-      });
-      selectedIds = chosen;
-      log(`Selected ${selectedIds.length} of ${items.length} catalog items.`);
+      const items = installableRecommendedItems(rec.recommended);
+      if (items.length === 0) {
+        log("Recommendation contains no catalog items. Writing core files only.");
+        selectedIds = [];
+      } else {
+        const choices = items.map((item) => ({
+          name: `${item.id}  [${item.selectionMode}] \u2014 ${item.reason}`,
+          value: item.id,
+          checked: true
+        }));
+        const chosen = await checkbox({
+          message: "Select catalog items to apply (space to toggle, enter to confirm):",
+          choices,
+          pageSize: Math.min(20, items.length + 2)
+        });
+        selectedIds = chosen;
+        log(`Selected ${selectedIds.length} of ${items.length} catalog items.`);
+      }
     }
   }
   if (!options.allowEmptyCache && !process.env["HAUS_FIXTURE_CATALOG"]) {
     const rec = await readJson(hausPath(root, "recommendation.json"));
-    const catalogItemCount = selectedIds !== void 0 ? selectedIds.length : rec?.recommended.length ?? 0;
+    const installableRecommended = installableRecommendedItems(rec?.recommended ?? []);
+    const catalogItemCount = selectedIds !== void 0 ? selectedIds.length : installableRecommended.length;
     if (catalogItemCount > 0 && !await cacheHasItems()) {
       const message = "No catalog content found. Run `haus update` first.";
       if (isDryRun) {
@@ -2705,7 +2778,7 @@ var STACK_RULES = [
   { stack: ["tooling", "missing-eslint"], any: [depAbsent("eslint")] },
   {
     stack: ["tooling", "stripe"],
-    any: [dep("@stripe/stripe-js"), dep("@stripe/react-stripe-js")]
+    any: [dep("stripe"), dep("@stripe/stripe-js"), dep("@stripe/react-stripe-js")]
   },
   { stack: ["tooling", "qliro"], any: [dep("@haus-tech/qliro-plugin")] },
   {
@@ -3508,7 +3581,7 @@ function mergeRecommendationWarnings(context) {
 }
 
 // src/recommender/recommend.ts
-async function recommend(root, context) {
+async function recommend(root, context, opts = {}) {
   const items = await loadCatalog(root);
   const sources = await readJson(
     hausPath(root, "sources-report.json")
@@ -3543,15 +3616,6 @@ async function recommend(root, context) {
       skip(item.id, "unsupported-policy", "Unsupported stack policy");
       continue;
     }
-    if (item.type === "config") {
-      skip(
-        item.id,
-        "config-scaffold-only",
-        "Config item \u2014 install with `haus scaffold`",
-        "type:config"
-      );
-      continue;
-    }
     if (item.reviewStatus === "deprecated") {
       skip(item.id, "deprecated", "Catalog item is deprecated", "reviewStatus:deprecated");
       continue;
@@ -3608,6 +3672,19 @@ async function recommend(root, context) {
       );
       continue;
     }
+    if (item.id === "haus.ecc-database-reviewer" && !roleSet.has("database")) {
+      skip(item.id, "required-role-missing", "Required role missing: database", "role:database");
+      continue;
+    }
+    if (item.id === "haus.ecc-typescript-reviewer" && (stackSet.has("react") || stackSet.has("react19") || stackSet.has("nextjs") || stackSet.has("next") || roleSet.has("react-app") || roleSet.has("next-app"))) {
+      skip(
+        item.id,
+        "co-install-react-reviewer",
+        "Skip typescript-reviewer on React/Next stacks (use react-reviewer)",
+        "stack:react|nextjs|role:react-app|next-app"
+      );
+      continue;
+    }
     const isDefaultBaseline = item.default === true;
     const reasons = [];
     const push = (code, message, signal) => reasons.push({ code, message, signal });
@@ -3652,13 +3729,22 @@ async function recommend(root, context) {
     }
     const hasEvidence = reasons.some((r) => r.code !== "default-baseline");
     if (isDefaultBaseline || hasEvidence) {
+      const isConfig = item.type === "config";
+      const entryReasons = isConfig ? [
+        ...reasons,
+        {
+          code: "config-scaffold",
+          message: "Install with `haus scaffold`",
+          signal: "type:config"
+        }
+      ] : reasons;
       recommended.push({
         id: item.id,
         type: item.type,
-        reason: reasons.length ? reasons.map((x) => x.message).join(", ") : "eligible",
-        reasons,
+        reason: entryReasons.length ? entryReasons.map((x) => x.message).join(", ") : "eligible",
+        reasons: entryReasons,
         selectionMode: isDefaultBaseline && !hasEvidence ? "baseline" : "matched",
-        install: true,
+        install: !isConfig,
         tags: item.tags,
         ecosystem: item.ecosystem,
         tokenEstimate: item.tokenEstimate
@@ -3667,16 +3753,21 @@ async function recommend(root, context) {
       skip(item.id, "no-role-stack-match", "No role/stack match");
     }
   }
+  applyCoInstallSuppression(recommended, skipped);
+  const includeWarnings = applyManualIncludes(opts.include ?? [], items, recommended, skipped);
+  const optInEligible = buildOptInEligible(items, skipped);
   recommended.sort((a, b) => a.id.localeCompare(b.id));
   skipped.sort((a, b) => a.id.localeCompare(b.id));
-  const selectedRules = recommended.length;
+  const installableRecommended = recommended.filter((item) => item.install);
+  const selectedRules = installableRecommended.length;
   const skippedRules = skipped.length;
   const estimatedContextTokens = estimateContextTokens(selectedRules);
   const estimatedTokenReductionPct = tokenReductionPct(selectedRules, skippedRules);
   return {
     recommended,
     skipped,
-    warnings: mergeRecommendationWarnings(context),
+    optInEligible,
+    warnings: [...mergeRecommendationWarnings(context), ...includeWarnings],
     estimatedContextTokens,
     selectedRules,
     skippedRules,
@@ -3690,6 +3781,152 @@ function buildStackSet(context) {
     )
   );
 }
+function applyCoInstallSuppression(recommended, skipped) {
+  const recommendedIds = new Set(recommended.map((r) => r.id));
+  const rules = [
+    {
+      suppress: "haus.sentry-sentry-workflow",
+      whenAnyRecommended: [
+        "haus.sentry-sentry-php-sdk",
+        "haus.sentry-sentry-nextjs-sdk",
+        "haus.sentry-sentry-node-sdk",
+        "haus.sentry-sentry-nestjs-sdk"
+      ],
+      code: "co-install-sentry-sdk",
+      message: "Skip sentry-workflow when a stack-specific Sentry SDK skill is selected",
+      signal: "co-install:sentry-sdk"
+    },
+    {
+      suppress: "haus.ecc-e2e-runner",
+      whenAnyRecommended: ["haus.ecc-e2e-testing"],
+      code: "co-install-e2e-skill",
+      message: "Skip e2e-runner when e2e-testing skill covers patterns",
+      signal: "co-install:e2e-testing"
+    },
+    {
+      suppress: "haus.oh-my-claudecode-test-engineer",
+      whenAnyRecommended: ["haus.ecc-e2e-testing", "haus.ecc-e2e-runner"],
+      code: "co-install-e2e-coverage",
+      message: "Skip oh-my test-engineer when ECC e2e skill or agent is selected",
+      signal: "co-install:e2e-coverage"
+    },
+    {
+      suppress: "haus.wshobson-js-testing-patterns",
+      whenAnyRecommended: ["haus.ecc-react-testing"],
+      code: "co-install-react-testing",
+      message: "Skip js-testing-patterns when ecc-react-testing covers component tests",
+      signal: "co-install:react-testing"
+    },
+    {
+      suppress: "haus.superpowers-test-driven-development",
+      whenAnyRecommended: ["haus.wshobson-js-testing-patterns", "haus.ecc-react-testing"],
+      code: "co-install-stack-testing",
+      message: "Skip TDD superpower when a stack testing skill is selected",
+      signal: "co-install:stack-testing"
+    },
+    {
+      suppress: "haus.superpowers-specifying-gates",
+      whenAnyRecommended: ["haus.superpowers-checking-gates"],
+      code: "co-install-gate-workflow",
+      message: "Skip specifying-gates when checking-gates is selected",
+      signal: "co-install:checking-gates"
+    },
+    {
+      suppress: "haus.ecc-redis-patterns",
+      whenAnyRecommended: ["haus.redis-redis-connections"],
+      code: "co-install-redis-official",
+      message: "Skip ecc-redis-patterns when official redis-connections skill is selected",
+      signal: "co-install:redis-connections"
+    }
+  ];
+  for (const rule of rules) {
+    if (!recommendedIds.has(rule.suppress)) continue;
+    if (!rule.whenAnyRecommended.some((id) => recommendedIds.has(id))) continue;
+    const idx = recommended.findIndex((r) => r.id === rule.suppress);
+    if (idx === -1) continue;
+    const [removed] = recommended.splice(idx, 1);
+    recommendedIds.delete(rule.suppress);
+    skipped.push({
+      id: removed.id,
+      reason: rule.message,
+      skipReasons: [{ code: rule.code, message: rule.message, signal: rule.signal }]
+    });
+  }
+}
+var HARD_SKIP_CODES = /* @__PURE__ */ new Set([
+  "unsupported-policy",
+  "deprecated",
+  "curated-not-approved",
+  "curated-risk-blocked",
+  "sensitive-policy",
+  "source-trust",
+  "source-approval"
+]);
+function applyManualIncludes(include, items, recommended, skipped) {
+  const warnings = [];
+  if (include.length === 0) return warnings;
+  const byId = new Map(items.map((i) => [i.id, i]));
+  const recommendedIds = new Set(recommended.map((r) => r.id));
+  for (const id of include) {
+    const item = byId.get(id);
+    if (!item) {
+      warnings.push(`--include: unknown catalog id "${id}" (not in manifest)`);
+      continue;
+    }
+    if (recommendedIds.has(id)) continue;
+    const skipIdx = skipped.findIndex((s) => s.id === id);
+    const skipCode = skipIdx >= 0 ? skipped[skipIdx].skipReasons[0]?.code : void 0;
+    if (skipCode && HARD_SKIP_CODES.has(skipCode)) {
+      warnings.push(`--include: "${id}" cannot be force-installed (blocked by ${skipCode})`);
+      continue;
+    }
+    if (skipCode === "requires-any-unsatisfied") {
+      warnings.push(`--include: "${id}" added manually though its requiresAny gate is unsatisfied`);
+    }
+    if (skipIdx >= 0) skipped.splice(skipIdx, 1);
+    const isConfig = item.type === "config";
+    recommended.push({
+      id: item.id,
+      type: item.type,
+      reason: "manually included",
+      reasons: [
+        {
+          code: "manual-include",
+          message: "manually included via --include",
+          signal: "selection:manual"
+        }
+      ],
+      selectionMode: "manual",
+      install: !isConfig,
+      tags: item.tags,
+      ecosystem: item.ecosystem,
+      tokenEstimate: item.tokenEstimate
+    });
+    recommendedIds.add(id);
+  }
+  return warnings;
+}
+function buildOptInEligible(items, skipped) {
+  const byId = new Map(items.map((i) => [i.id, i]));
+  const eligible = [];
+  for (const entry of skipped) {
+    if (entry.skipReasons[0]?.code !== "requires-any-unsatisfied") continue;
+    const item = byId.get(entry.id);
+    if (!item?.optInTier || !item.optInGroup) continue;
+    eligible.push({
+      id: item.id,
+      type: item.type,
+      title: item.title,
+      optInTier: item.optInTier,
+      optInGroup: item.optInGroup,
+      purpose: item.purpose,
+      tokenEstimate: item.tokenEstimate,
+      requires: entry.skipReasons[0]?.signal ?? describeRequiresAny(item.requiresAny ?? [])
+    });
+  }
+  eligible.sort((a, b) => a.optInGroup.localeCompare(b.optInGroup) || a.id.localeCompare(b.id));
+  return eligible;
+}
 
 // src/commands/setup-core.ts
 async function runSetupCore(root, opts) {
@@ -4150,7 +4387,8 @@ async function runInstall(options) {
 async function runRecommend(options) {
   const root = process.cwd();
   const context = await readContextOrScan(root);
-  const result = await recommend(root, context);
+  const include = parseIdList(options.include);
+  const result = await recommend(root, context, { include });
   await writeJson(hausPath(root, "recommendation.json"), result);
   if (options.json) {
     log(JSON.stringify(result, null, 2));
@@ -4159,6 +4397,12 @@ async function runRecommend(options) {
   log("Haus recommendation ready");
   log(`Recommended: ${result.recommended.length}`);
   log(`Skipped: ${result.skipped.length}`);
+  if (result.optInEligible && result.optInEligible.length > 0) {
+    log(
+      `Opt-in available: ${result.optInEligible.length} (add with \`haus recommend --include <id>\`)`
+    );
+  }
+  for (const w of result.warnings.filter((w2) => w2.startsWith("--include:"))) log(w);
 }
 
 // src/commands/refresh.ts
@@ -4220,19 +4464,20 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
     if (stat.isFile()) {
       const filename = path22.basename(sourcePath);
       const dest = path22.join(projectRoot, filename);
-      record(filename, await scaffoldFile(sourcePath, dest, item.id, opts));
+      record(filename, await scaffoldFile(sourcePath, dest, item.id, projectRoot, opts));
     } else if (stat.isDirectory()) {
       const entries = await fs17.readdir(sourcePath);
       for (const entry of entries) {
         const src = path22.join(sourcePath, entry);
         const dest = path22.join(projectRoot, entry);
-        record(entry, await scaffoldFile(src, dest, item.id, opts));
+        record(entry, await scaffoldFile(src, dest, item.id, projectRoot, opts));
       }
     }
   }
   return { scaffolded, skipped, skippedExisting };
 }
-async function scaffoldFile(src, dest, itemId, opts) {
+async function scaffoldFile(src, dest, itemId, projectRoot, opts) {
+  const destDisplay = path22.relative(projectRoot, dest) || path22.basename(dest);
   const srcStat = await fs17.lstat(src).catch(() => null);
   if (!srcStat) {
     warn(`Skipping ${path22.basename(src)}: source not found`);
@@ -4244,7 +4489,7 @@ async function scaffoldFile(src, dest, itemId, opts) {
   }
   const exists = await fs17.pathExists(dest);
   if (exists && !opts.force) {
-    warn(`Skipping ${path22.basename(dest)}: already exists (use --force to overwrite)`);
+    warn(`Skipping ${destDisplay}: already exists \u2014 re-run with --force to overwrite it`);
     return "skipped-exists";
   }
   if (opts.dryRun) {
@@ -4760,6 +5005,39 @@ function auditForbiddenStacks(items) {
   }
   return failures;
 }
+var OPT_IN_TIERS = /* @__PURE__ */ new Set(["workflow", "ops", "review", "design"]);
+function auditOptInMetadata(items) {
+  const failures = [];
+  for (const item of items) {
+    const hasTier = item.optInTier !== void 0;
+    const hasGroup = item.optInGroup !== void 0;
+    if (hasTier !== hasGroup) {
+      failures.push(`${item.id}: optInTier and optInGroup must be set together`);
+    }
+    if (hasTier) {
+      if (!OPT_IN_TIERS.has(item.optInTier)) {
+        failures.push(
+          `${item.id}: invalid optInTier "${item.optInTier}" (expected one of ${[...OPT_IN_TIERS].join(", ")})`
+        );
+      }
+      if (typeof item.optInGroup !== "string" || item.optInGroup.length === 0) {
+        failures.push(`${item.id}: optInGroup must be a non-empty string`);
+      }
+      if (item.default === true) {
+        failures.push(`${item.id}: opt-in items (optInTier set) must not be default:true`);
+      }
+      if (typeof item.purpose !== "string" || item.purpose.length === 0) {
+        failures.push(`${item.id}: opt-in items (optInTier set) must have a non-empty purpose`);
+      }
+    }
+    const requiresAny = Array.isArray(item.requiresAny) ? item.requiresAny : [];
+    const roleOnly = requiresAny.length > 0 && requiresAny.every((clause) => clause && clause.role);
+    if (item.default !== true && roleOnly && !hasTier) {
+      failures.push(`${item.id}: role-gated opt-in item missing optInTier/optInGroup`);
+    }
+  }
+  return failures;
+}
 function auditManifestStructure(manifestVersion, items) {
   const failures = [];
   const seenIds = /* @__PURE__ */ new Map();
@@ -4903,15 +5181,19 @@ function walkMd(dir, fn) {
     else if (entry.name.endsWith(".md")) fn(full);
   }
 }
-function auditMarkdownContent(manifestDir) {
+function auditMarkdownContent(manifestDir, items) {
   const failures = [];
+  const pathSourceMap = buildItemPathSourceMap(items);
   for (const dir of ["skills", "agents", "templates", "commands"]) {
     const abs = path27.join(manifestDir, dir);
     if (!fs21.existsSync(abs)) continue;
-    const checkNonTsxNpx = !NPX_TSX_ONLY_EXEMPT_TYPES.includes(DIR_ITEM_TYPE[dir] ?? "");
+    const dirType = DIR_ITEM_TYPE[dir] ?? "";
     walkMd(abs, (file) => {
       const text = fs21.readFileSync(file, "utf8");
       const rel = path27.relative(manifestDir, file);
+      const norm = rel.replace(/\\/g, "/");
+      const source = resolveMarkdownItemSource(norm, pathSourceMap);
+      const checkNonTsxNpx = !isNpxTsxOnlyExempt(dirType, source);
       const lines = text.split(/\r?\n/);
       for (let i = 0; i < lines.length; i++) {
         const line2 = lines[i] ?? "";
@@ -4921,7 +5203,7 @@ function auditMarkdownContent(manifestDir) {
           failures.push(`${rel}:${i + 1}: disallowed npx (only npx tsx allowed)`);
         }
       }
-      if (!rel.includes("/references/")) failures.push(...auditForbiddenTagsInText(text, rel));
+      if (!norm.includes("/references/")) failures.push(...auditForbiddenTagsInText(text, rel));
     });
   }
   return failures;
@@ -4929,9 +5211,10 @@ function auditMarkdownContent(manifestDir) {
 function validateCatalogData(manifestDir, manifestVersion, items) {
   const failures = [
     ...auditManifestStructure(manifestVersion, items),
+    ...auditOptInMetadata(items),
     ...auditForbiddenStacks(items),
     ...auditShippedFiles(manifestDir, items),
-    ...auditMarkdownContent(manifestDir),
+    ...auditMarkdownContent(manifestDir, items),
     ...auditDisallowedTags(items)
   ];
   return { ok: failures.length === 0, failures, items };
@@ -5641,10 +5924,16 @@ 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").action(runRecommend);
+program.command("recommend").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").action(runSetupProject);
 program.command("doctor").option("--hooks", "Verify .claude/settings.json matches the hook contract").action(runDoctor);
 program.command("apply").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(
   "--allow-empty-cache",
   "Apply core files only when catalog cache is empty (skip catalog items without error)"
 ).option(