@haus-tech/haus-workflow 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.22.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.21.0...v0.22.0) (2026-06-11)
+
+### Features
+
+- **audit:** offline, perf cleanup, CI ([#92](https://github.com/WeAreHausTech/haus-workflow/issues/92)) ([a133f06](https://github.com/WeAreHausTech/haus-workflow/commit/a133f06d52b9a9e2a15f949c443c7042ed125735))
+- **catalog:** ingest chokepoint ([#91](https://github.com/WeAreHausTech/haus-workflow/issues/91)) ([712d72b](https://github.com/WeAreHausTech/haus-workflow/commit/712d72b252ae3181bcdb9ce02614ede098c5bab5))
+
+### Bug Fixes
+
+- **cloneandsetup:** read repo setup docs before file-heuristics ([#95](https://github.com/WeAreHausTech/haus-workflow/issues/95)) ([8219b92](https://github.com/WeAreHausTech/haus-workflow/commit/8219b92d1c40b71ecb78661929ca57e1fe858603))
+
 ## [0.21.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.20.0...v0.21.0) (2026-06-11)
 
 ### Features

package/README.md

@@ -34,12 +34,14 @@ The `project:*` tasks act on the current repo. The unprefixed verbs (`update`,
 (`~/.claude` + npm), like `npm install -g`. The short legacy names still work.
 
 ```
-/haus-workflow                 # interactive menu — pick a task
-/haus-workflow project:init    # [project] add haus to an EXISTING repo — AI skills, commands, workflow + docs
-/haus-workflow project:refresh # [project] refresh .claude/ and regenerate CLAUDE.md imports
-/haus-workflow project:doctor  # [project] health check for drift
-/haus-workflow update          # [global]  update npm package + catalog + ~/.claude/
-/haus-workflow catalog         # [global]  fetch only the latest catalog
+/haus-workflow                              # interactive menu — pick a task
+/haus-workflow project:init                 # [project] add haus to an EXISTING repo — AI skills, commands, workflow + docs
+/haus-workflow project:clone [name]         # [project] clone a workspace's repos (repos.manifest.json), or find & clone one repo by name from GitHub
+/haus-workflow project:cloneandsetup [name] # [project] like project:clone, then set up each repo locally (node version, deps, .env)
+/haus-workflow project:refresh              # [project] refresh .claude/ and regenerate CLAUDE.md imports
+/haus-workflow project:doctor               # [project] health check for drift
+/haus-workflow update                       # [global]  update npm package + catalog + ~/.claude/
+/haus-workflow catalog                      # [global]  fetch only the latest catalog
 ```
 
 Without an argument, the skill presents a menu so you can pick the task. With an argument, it runs immediately.
@@ -63,6 +65,7 @@ Scans the repo, recommends context assets, and writes `.claude/` and `.haus-work
 ```bash
 haus init              # first-run setup (scan → recommend → apply)
 haus setup-project     # re-run setup on existing project
+haus clone <url> [dir] # clone a single git repo by URL (the primitive project:clone / project:cloneandsetup loop over)
 haus scan              # scan repo and write context-map
 haus recommend         # recommend catalog items (binary eligibility)
 haus apply --dry-run   # preview what would be written

package/dist/cli.js

@@ -12,8 +12,66 @@ import fs12 from "fs-extra";
 
 // src/catalog/remote-catalog.ts
 import os from "os";
+import path2 from "path";
+import fs2 from "fs-extra";
+
+// src/utils/fs.ts
+import crypto from "crypto";
 import path from "path";
+import fg from "fast-glob";
 import fs from "fs-extra";
+async function readJson(file) {
+  try {
+    return await fs.readJson(file);
+  } catch {
+    return void 0;
+  }
+}
+async function writeJson(file, value) {
+  await fs.ensureDir(path.dirname(file));
+  await fs.writeFile(file, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+async function pruneEmptyDir(dir) {
+  try {
+    const entries = await fs.readdir(dir);
+    if (entries.length === 0) await fs.remove(dir);
+  } catch {
+  }
+}
+async function readText(file) {
+  try {
+    return await fs.readFile(file, "utf8");
+  } catch {
+    return void 0;
+  }
+}
+async function writeText(file, value) {
+  await fs.ensureDir(path.dirname(file));
+  await fs.writeFile(file, value, "utf8");
+}
+async function listFiles(root, patterns) {
+  const files = await fg(patterns, {
+    cwd: root,
+    dot: true,
+    onlyFiles: true,
+    ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**"]
+  });
+  return files.sort((a, b) => a.localeCompare(b));
+}
+function hashText(value) {
+  return `sha256-${crypto.createHash("sha256").update(value).digest("hex")}`;
+}
+async function mapWithConcurrency(items, fn, concurrency = 24) {
+  const size = Number.isFinite(concurrency) ? Math.max(1, Math.floor(concurrency)) : 24;
+  const results = new Array(items.length);
+  for (let i = 0; i < items.length; i += size) {
+    const batch = items.slice(i, i + size);
+    const settled = await Promise.all(batch.map((item, j) => fn(item, i + j)));
+    for (let j = 0; j < settled.length; j += 1) results[i + j] = settled[j];
+  }
+  return results;
+}
 
 // src/utils/logger.ts
 var log = (msg, ...args) => {
@@ -28,15 +86,362 @@ var error = (msg, ...args) => {
 
 // src/catalog/constants.ts
 var CATALOG_REPO_URL = "https://raw.githubusercontent.com/wearehaustech/haus-workflow-catalog";
-var CATALOG_REF = process.env.HAUS_CATALOG_REF ?? "main";
+var CATALOG_REF = process.env.HAUS_CATALOG_REF;
 var CATALOG_CACHE_SUBDIR = ".claude/haus/catalog-cache";
 
+// library/catalog/validation-rules.json
+var validation_rules_default = {
+  forbiddenTags: [
+    "python",
+    "django",
+    "go",
+    "rust",
+    "java",
+    "spring",
+    "kotlin",
+    "swift",
+    "android",
+    "flutter",
+    "dart",
+    "c++",
+    "perl",
+    "defi",
+    "trading"
+  ],
+  bannedAgentPhrases: ["autonomous", "swarm", "delegate", "orchestrat", "marketplace"],
+  requiredSkillFrontmatter: ["description"],
+  requiredAgentSections: ["## Use when", "## Do not use when", "## Verification"],
+  riskyInstallPatterns: [
+    { source: "\\bnpx\\s+-y\\b", flags: "i" },
+    { source: "\\bnpx\\s+--yes\\b", flags: "i" },
+    { source: "\\byarn\\s+dlx\\b", flags: "i" },
+    { source: "\\bpnpm\\s+dlx\\b", flags: "i" }
+  ],
+  allowedNpxPattern: { source: "\\bnpx\\s+tsx\\b", flags: "i" },
+  anyNpxPattern: { source: "\\bnpx\\s+\\S+", flags: "i" },
+  httpUrlPattern: { source: "^http:\\/\\/", flags: "i" },
+  placeholderPattern: { source: "\\bTODO\\b|\\bPLACEHOLDER\\b", flags: "i" },
+  allowedStacks: [
+    "haus",
+    "security",
+    "quality",
+    "frontend",
+    "backend",
+    "testing",
+    "review",
+    "workflow",
+    "reference-pack",
+    "core-skill",
+    "workflow-skill",
+    "stack-skill",
+    "review-skill",
+    "agent",
+    "hook",
+    "rule",
+    "react",
+    "typescript",
+    "php",
+    "csharp",
+    "vendure",
+    "vendure3",
+    "nestjs",
+    "graphql",
+    "nx21",
+    "turbo",
+    "nextjs",
+    "react19",
+    "typescript5",
+    "vite8",
+    "tanstack-query",
+    "tanstack-router",
+    "radix",
+    "radix-ui",
+    "shadcn",
+    "shadcn-ui",
+    "tailwind",
+    "tailwindcss",
+    "scss",
+    "scss-modules",
+    "vue",
+    "expressjs",
+    "soup-base",
+    "laravel",
+    "laravel-nova",
+    "wordpress",
+    "bedrock",
+    "elementor-pro",
+    "acf-pro",
+    "jetengine",
+    "dotnet",
+    "oidc",
+    "azure-ad",
+    "bankid",
+    "myid",
+    "cgi",
+    "crypto",
+    "collection2",
+    "postgresql",
+    "mariadb",
+    "mssql",
+    "elasticsearch",
+    "yarn4",
+    "pnpm89",
+    "playwright",
+    "testing-library",
+    "phpunit",
+    "storybook",
+    "wisest",
+    "vitest",
+    "jest",
+    "redis",
+    "sanity",
+    "strapi",
+    "prisma",
+    "cms",
+    "database",
+    "mysql",
+    "saml2",
+    "next-auth",
+    "auth",
+    "expo",
+    "react-native",
+    "mobile",
+    "i18next",
+    "i18n",
+    "bullmq",
+    "queue",
+    "sentry",
+    "observability",
+    "tooling",
+    "prettier",
+    "eslint",
+    "missing-prettier",
+    "missing-eslint",
+    "docker",
+    "pm2",
+    "deployer-php",
+    "stripe",
+    "qliro",
+    "supabase",
+    "payments"
+  ],
+  alwaysAllowedTags: [
+    "haus",
+    "security",
+    "quality",
+    "review",
+    "workflow",
+    "baseline",
+    "project-instructions"
+  ],
+  patternTagSuffixes: ["-patterns"]
+};
+
+// src/catalog/validation-rules.ts
+var toRegExp = (r) => new RegExp(r.source, r.flags);
+var FORBIDDEN_TAGS = validation_rules_default.forbiddenTags;
+var BANNED_AGENT_PHRASES = validation_rules_default.bannedAgentPhrases;
+var REQUIRED_SKILL_FRONTMATTER = validation_rules_default.requiredSkillFrontmatter;
+var REQUIRED_AGENT_SECTIONS = validation_rules_default.requiredAgentSections;
+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 HTTP_URL_PATTERN = toRegExp(validation_rules_default.httpUrlPattern);
+var PLACEHOLDER_PATTERN = toRegExp(validation_rules_default.placeholderPattern);
+var ALLOWED_STACKS = validation_rules_default.allowedStacks;
+var ALWAYS_ALLOWED_TAGS = validation_rules_default.alwaysAllowedTags;
+var PATTERN_TAG_SUFFIXES = validation_rules_default.patternTagSuffixes;
+var ALLOWED_SET = new Set([...ALLOWED_STACKS, ...ALWAYS_ALLOWED_TAGS].map((t) => t.toLowerCase()));
+function isTagAllowed(tag) {
+  const lower = tag.toLowerCase();
+  if (ALLOWED_SET.has(lower)) return true;
+  return PATTERN_TAG_SUFFIXES.some((suffix) => lower.endsWith(suffix));
+}
+function auditDisallowedTags(items) {
+  const failures = [];
+  for (const item of items) {
+    if (!item.id) continue;
+    for (const tag of Array.isArray(item.tags) ? item.tags : []) {
+      if (!isTagAllowed(tag)) failures.push(`${item.id}: tag not in allowlist: "${tag}"`);
+    }
+  }
+  return failures;
+}
+
+// src/catalog/forbidden-content.ts
+var PROSE_FORBIDDEN_TAGS = FORBIDDEN_TAGS.filter((t) => t.toLowerCase() !== "go");
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function extractUseWhenSection(text) {
+  const marker = "## Use when";
+  const idx = text.toLowerCase().indexOf(marker.toLowerCase());
+  if (idx < 0) return "";
+  const tail = text.slice(idx + marker.length);
+  const next = tail.search(/\n##\s+/);
+  return next < 0 ? tail : tail.slice(0, next);
+}
+function isYamlBlockScalarHeader(rest) {
+  return /^[>|][-+]?(\d+)?(?:\s+#.*)?$/.test(rest);
+}
+function extractFrontmatterValue(text, key) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return "";
+  const lines = m[1].split(/\r?\n/);
+  const keyRe = new RegExp(`^${escapeRegExp(key)}:[ \\t]*`);
+  const idx = lines.findIndex((l) => keyRe.test(l));
+  if (idx < 0) return "";
+  const rest = lines[idx].replace(keyRe, "").trim();
+  if (!rest) return "";
+  if (!isYamlBlockScalarHeader(rest)) {
+    return rest.replace(/^["']|["']$/g, "").trim();
+  }
+  const body = [];
+  for (let j = idx + 1; j < lines.length; j++) {
+    const line2 = lines[j];
+    if (/^[a-zA-Z_][\w.-]*:[ \t]/.test(line2)) break;
+    if (line2.trim() === "") continue;
+    if (/^\s+/.test(line2)) body.push(line2.trimStart());
+    else break;
+  }
+  return body.join(" ").replace(/\s+/g, " ").trim();
+}
+function extractFrontmatterDescription(text) {
+  return extractFrontmatterValue(text, "description");
+}
+function auditForbiddenTagsInText(text, label) {
+  const body = `${extractFrontmatterDescription(text)}
+${extractUseWhenSection(text)}`;
+  if (!body.trim()) return [];
+  const failures = [];
+  for (const word of PROSE_FORBIDDEN_TAGS) {
+    const re = new RegExp(`\\b${escapeRegExp(word)}\\b`, "i");
+    if (re.test(body)) failures.push(`${label}: forbidden stack/tag "${word}" in content`);
+  }
+  return failures;
+}
+
+// src/catalog/ingest-catalog.ts
+function validateCatalogItem(item, content2) {
+  const label = item.id;
+  const lines = content2.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line2 = lines[i] ?? "";
+    if (RISKY_INSTALL_PATTERNS.some((re) => re.test(line2))) {
+      return { ok: false, reason: `${label}: risky install pattern at line ${i + 1}` };
+    }
+    if (ANY_NPX_PATTERN.test(line2) && !ALLOWED_NPX_PATTERN.test(line2)) {
+      return { ok: false, reason: `${label}: disallowed npx at line ${i + 1}` };
+    }
+  }
+  const lower = content2.toLowerCase();
+  for (const phrase of BANNED_AGENT_PHRASES) {
+    if (lower.includes(phrase)) {
+      return { ok: false, reason: `${label}: banned phrase "${phrase}"` };
+    }
+  }
+  const tagFailures = auditForbiddenTagsInText(content2, label);
+  if (tagFailures.length > 0) {
+    return { ok: false, reason: tagFailures[0] };
+  }
+  return { ok: true };
+}
+
+// src/catalog/manifest-schema.ts
+var POLLUTION_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function safeParse(json) {
+  return JSON.parse(json, (key, value) => {
+    if (POLLUTION_KEYS.has(key)) return void 0;
+    return value;
+  });
+}
+function parseManifest(json) {
+  let data;
+  try {
+    data = safeParse(json);
+  } catch {
+    return { ok: false, error: "invalid JSON" };
+  }
+  if (!data || typeof data !== "object") {
+    return { ok: false, error: "manifest must be an object" };
+  }
+  const root = data;
+  if (!isNonEmptyString(root.version)) {
+    return { ok: false, error: "missing version" };
+  }
+  if (!Array.isArray(root.items)) {
+    return { ok: false, error: "missing items array" };
+  }
+  const items = [];
+  const seenIds = /* @__PURE__ */ new Set();
+  const seenPaths = /* @__PURE__ */ new Set();
+  for (let i = 0; i < root.items.length; i++) {
+    const raw = root.items[i];
+    if (!raw || typeof raw !== "object") {
+      return { ok: false, error: `item[${i}]: invalid entry` };
+    }
+    const item = raw;
+    if (!isNonEmptyString(item.id)) {
+      return { ok: false, error: `item[${i}]: missing id` };
+    }
+    if (!isNonEmptyString(item.type)) {
+      return { ok: false, error: `${item.id}: missing type` };
+    }
+    if (!isNonEmptyString(item.path)) {
+      return { ok: false, error: `${item.id}: missing path` };
+    }
+    if (seenIds.has(item.id)) {
+      return { ok: false, error: `${item.id}: duplicate id` };
+    }
+    seenIds.add(item.id);
+    const normPath = item.path.replace(/\\/g, "/");
+    if (seenPaths.has(normPath)) {
+      return { ok: false, error: `${item.id}: duplicate path "${normPath}"` };
+    }
+    seenPaths.add(normPath);
+    if (item.source === "curated") {
+      if (!isNonEmptyString(item.reviewStatus)) {
+        return { ok: false, error: `${item.id}: curated item missing reviewStatus` };
+      }
+      if (!isNonEmptyString(item.riskLevel)) {
+        return { ok: false, error: `${item.id}: curated item missing riskLevel` };
+      }
+    }
+    items.push(raw);
+  }
+  return { ok: true, manifest: { version: root.version, items } };
+}
+
 // src/catalog/remote-catalog.ts
 function getCacheDir() {
-  return process.env["HAUS_CATALOG_CACHE_DIR_OVERRIDE"] ?? path.join(os.homedir(), CATALOG_CACHE_SUBDIR);
+  return process.env["HAUS_CATALOG_CACHE_DIR_OVERRIDE"] ?? path2.join(os.homedir(), CATALOG_CACHE_SUBDIR);
+}
+var cachedCatalogRef;
+function getResolvedCatalogRef() {
+  return cachedCatalogRef ?? process.env["HAUS_CATALOG_REF"] ?? "main";
+}
+function isCatalogRefResolved() {
+  return cachedCatalogRef !== void 0 || process.env["HAUS_CATALOG_REF"] !== void 0;
+}
+async function resolveCatalogRef(opts) {
+  const env = opts?.env ?? process.env;
+  if (env["HAUS_CATALOG_REF"]) return env["HAUS_CATALOG_REF"];
+  const fetchLatest = opts?.fetchLatestTag ?? fetchLatestCatalogTag;
+  const tag = await fetchLatest();
+  return tag ?? "main";
+}
+async function remoteBase() {
+  if (process.env["HAUS_CATALOG_REMOTE_BASE"]) {
+    return process.env["HAUS_CATALOG_REMOTE_BASE"];
+  }
+  if (cachedCatalogRef === void 0) {
+    cachedCatalogRef = await resolveCatalogRef();
+  }
+  return `${CATALOG_REPO_URL}/${cachedCatalogRef}`;
 }
-var REMOTE_BASE = process.env["HAUS_CATALOG_REMOTE_BASE"] ?? `${CATALOG_REPO_URL}/${CATALOG_REF}`;
-var REMOTE_MANIFEST_URL = `${REMOTE_BASE}/manifest.json`;
 async function fetchText(url) {
   try {
     const res = await fetch(url, { signal: AbortSignal.timeout(1e4) });
@@ -47,55 +452,59 @@ async function fetchText(url) {
   }
 }
 async function fetchRemoteManifest() {
-  const text = await fetchText(REMOTE_MANIFEST_URL);
+  const base = await remoteBase();
+  const text = await fetchText(`${base}/manifest.json`);
   if (!text) return null;
-  try {
-    const data = JSON.parse(text);
-    return data?.items?.length ? data.items : null;
-  } catch {
+  const parsed = parseManifest(text);
+  if (!parsed.ok) {
+    warn(`Remote manifest failed schema validation: ${parsed.error}`);
     return null;
   }
+  if (!parsed.manifest.items.length) return null;
+  return parsed.manifest;
 }
 async function writeTextIfChanged(dest, text) {
-  if (await fs.pathExists(dest)) {
-    const local = await fs.readFile(dest, "utf8");
+  if (await fs2.pathExists(dest)) {
+    const local = await fs2.readFile(dest, "utf8");
     if (local === text) return "unchanged";
-    await fs.writeFile(dest, text, "utf8");
+    await fs2.writeFile(dest, text, "utf8");
     return "updated";
   }
-  await fs.ensureDir(path.dirname(dest));
-  await fs.writeFile(dest, text, "utf8");
+  await fs2.ensureDir(path2.dirname(dest));
+  await fs2.writeFile(dest, text, "utf8");
   return "created";
 }
 var WORKFLOW_TEMPLATE_REL = "templates/agentic-workflow-standard.md";
 async function readWorkflowTemplate(opts = {}) {
-  const dest = path.join(getCacheDir(), WORKFLOW_TEMPLATE_REL);
-  const text = await fetchText(`${REMOTE_BASE}/${WORKFLOW_TEMPLATE_REL}`);
+  const dest = path2.join(getCacheDir(), WORKFLOW_TEMPLATE_REL);
+  const base = await remoteBase();
+  const text = await fetchText(`${base}/${WORKFLOW_TEMPLATE_REL}`);
   if (text === null) {
-    if (await fs.pathExists(dest)) return fs.readFile(dest, "utf8");
+    if (await fs2.pathExists(dest)) return fs2.readFile(dest, "utf8");
     return null;
   }
   if (!opts.dryRun) {
     await writeTextIfChanged(dest, text);
-  } else if (await fs.pathExists(dest)) {
-    return fs.readFile(dest, "utf8");
+  } else if (await fs2.pathExists(dest)) {
+    return fs2.readFile(dest, "utf8");
   }
   return text;
 }
 function isSafeCatalogPath(itemPath) {
-  if (!itemPath || path.isAbsolute(itemPath) || itemPath.includes("\\")) return false;
-  const normalized = path.normalize(itemPath);
+  if (!itemPath || path2.isAbsolute(itemPath) || itemPath.includes("\\")) return false;
+  const normalized = path2.normalize(itemPath);
   return !normalized.startsWith("..") && !normalized.includes("/..");
 }
 function safeJoin(base, itemPath) {
   if (!isSafeCatalogPath(itemPath)) return null;
-  const resolved = path.resolve(base, itemPath);
-  return resolved.startsWith(base + path.sep) || resolved === base ? resolved : null;
+  const resolved = path2.resolve(base, itemPath);
+  return resolved.startsWith(base + path2.sep) || resolved === base ? resolved : null;
 }
+var KNOWN_ITEM_TYPES = /* @__PURE__ */ new Set(["skill", "agent", "template", "command"]);
 function isExternalReference(ref) {
   return /^[a-z][a-z0-9+.-]*:\/\//i.test(ref);
 }
-async function downloadSkillReferences(item, destDir) {
+async function downloadSkillReferences(item, destDir, base) {
   for (const ref of item.references ?? []) {
     if (isExternalReference(ref)) continue;
     const refDest = safeJoin(destDir, ref);
@@ -103,7 +512,7 @@ async function downloadSkillReferences(item, destDir) {
       warn(`Skipping reference "${ref}" for ${item.id}: path traversal detected`);
       continue;
     }
-    const text = await fetchText(`${REMOTE_BASE}/${item.path}/${ref}`);
+    const text = await fetchText(`${base}/${item.path}/${ref}`);
     if (text === null) {
       warn(`Failed to fetch reference "${ref}" for ${item.id}`);
       continue;
@@ -111,18 +520,79 @@ async function downloadSkillReferences(item, destDir) {
     await writeTextIfChanged(refDest, text);
   }
 }
+async function syncOneItem(item, base) {
+  if (!KNOWN_ITEM_TYPES.has(item.type)) {
+    warn(
+      `Skipping ${item.id}: type "${item.type}" is unknown to this haus version \u2014 upgrade to use it`
+    );
+    return "failed";
+  }
+  if (!item.path) return "failed";
+  if (!isSafeCatalogPath(item.path)) {
+    warn(`Skipping ${item.id}: invalid path "${item.path}"`);
+    return "failed";
+  }
+  if (item.type === "skill") {
+    const destDir = safeJoin(getCacheDir(), item.path);
+    if (!destDir) {
+      warn(`Skipping ${item.id}: path traversal detected`);
+      return "failed";
+    }
+    const dest2 = path2.join(destDir, "SKILL.md");
+    const text2 = await fetchText(`${base}/${item.path}/SKILL.md`);
+    if (!text2) {
+      warn(`Failed to fetch content for ${item.id}`);
+      return "failed";
+    }
+    const verdict2 = validateCatalogItem(item, text2);
+    if (!verdict2.ok) {
+      warn(`Rejected ${item.id} at ingest: ${verdict2.reason}`);
+      return "failed";
+    }
+    try {
+      const outcome = await writeTextIfChanged(dest2, text2);
+      await downloadSkillReferences(item, destDir, base);
+      return outcome;
+    } catch (err) {
+      warn(`Failed to cache ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
+      return "failed";
+    }
+  }
+  const dest = safeJoin(getCacheDir(), item.path);
+  if (!dest) {
+    warn(`Skipping ${item.id}: path traversal detected`);
+    return "failed";
+  }
+  const text = await fetchText(`${base}/${item.path}`);
+  if (!text) {
+    warn(`Failed to fetch content for ${item.id}`);
+    return "failed";
+  }
+  const verdict = validateCatalogItem(item, text);
+  if (!verdict.ok) {
+    warn(`Rejected ${item.id} at ingest: ${verdict.reason}`);
+    return "failed";
+  }
+  try {
+    return await writeTextIfChanged(dest, text);
+  } catch (err) {
+    warn(`Failed to cache ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
+    return "failed";
+  }
+}
 async function syncRemoteCatalog() {
-  const items = await fetchRemoteManifest();
-  if (!items) {
+  const manifest = await fetchRemoteManifest();
+  if (!manifest) {
     warn("Remote catalog fetch failed \u2014 using bundled catalog");
     return { newItems: [], refreshed: [], unchanged: 0, failed: [] };
   }
+  const { version, items } = manifest;
   const cacheDir = getCacheDir();
   try {
-    await fs.ensureDir(cacheDir);
-    await fs.writeFile(
-      path.join(cacheDir, "manifest.json"),
-      `${JSON.stringify({ items }, null, 2)}
+    await fs2.ensureDir(cacheDir);
+    await fs2.writeFile(
+      path2.join(cacheDir, "manifest.json"),
+      `${JSON.stringify({ version, items }, null, 2)}
 `,
       "utf8"
     );
@@ -136,63 +606,15 @@ async function syncRemoteCatalog() {
   const refreshed = [];
   let unchanged = 0;
   const failed = [];
-  for (const item of items) {
-    if (item.type !== "skill" && item.type !== "agent" && item.type !== "template" && item.type !== "command" || !item.path)
-      continue;
-    if (!isSafeCatalogPath(item.path)) {
-      warn(`Skipping ${item.id}: invalid path "${item.path}"`);
-      failed.push(item.id);
-      continue;
-    }
-    if (item.type === "skill") {
-      const destDir = safeJoin(getCacheDir(), item.path);
-      if (!destDir) {
-        warn(`Skipping ${item.id}: path traversal detected`);
-        failed.push(item.id);
-        continue;
-      }
-      const dest = path.join(destDir, "SKILL.md");
-      const url = `${REMOTE_BASE}/${item.path}/SKILL.md`;
-      const text = await fetchText(url);
-      if (!text) {
-        warn(`Failed to fetch content for ${item.id}`);
-        failed.push(item.id);
-        continue;
-      }
-      try {
-        const outcome = await writeTextIfChanged(dest, text);
-        await downloadSkillReferences(item, destDir);
-        if (outcome === "created") newItems.push(item.id);
-        else if (outcome === "updated") refreshed.push(item.id);
-        else unchanged++;
-      } catch (err) {
-        warn(`Failed to cache ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
-        failed.push(item.id);
-      }
-    } else {
-      const dest = safeJoin(getCacheDir(), item.path);
-      if (!dest) {
-        warn(`Skipping ${item.id}: path traversal detected`);
-        failed.push(item.id);
-        continue;
-      }
-      const url = `${REMOTE_BASE}/${item.path}`;
-      const text = await fetchText(url);
-      if (!text) {
-        warn(`Failed to fetch content for ${item.id}`);
-        failed.push(item.id);
-        continue;
-      }
-      try {
-        const outcome = await writeTextIfChanged(dest, text);
-        if (outcome === "created") newItems.push(item.id);
-        else if (outcome === "updated") refreshed.push(item.id);
-        else unchanged++;
-      } catch (err) {
-        warn(`Failed to cache ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
-        failed.push(item.id);
-      }
-    }
+  const base = await remoteBase();
+  const outcomes = await mapWithConcurrency(items, (item) => syncOneItem(item, base), 8);
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    const outcome = outcomes[i];
+    if (outcome === "created") newItems.push(item.id);
+    else if (outcome === "updated") refreshed.push(item.id);
+    else if (outcome === "unchanged") unchanged++;
+    else if (outcome === "failed") failed.push(item.id);
   }
   return { newItems, refreshed, unchanged, failed };
 }
@@ -213,7 +635,7 @@ async function fetchLatestCatalogTag() {
 }
 async function getCacheManifestAge() {
   try {
-    const stat = await fs.stat(path.join(getCacheDir(), "manifest.json"));
+    const stat = await fs2.stat(path2.join(getCacheDir(), "manifest.json"));
     return Date.now() - stat.mtimeMs;
   } catch {
     return null;
@@ -237,64 +659,6 @@ function buildAllowRules() {
 import path4 from "path";
 import fs3 from "fs-extra";
 
-// src/utils/fs.ts
-import crypto from "crypto";
-import path2 from "path";
-import fg from "fast-glob";
-import fs2 from "fs-extra";
-async function readJson(file) {
-  try {
-    return await fs2.readJson(file);
-  } catch {
-    return void 0;
-  }
-}
-async function writeJson(file, value) {
-  await fs2.ensureDir(path2.dirname(file));
-  await fs2.writeFile(file, `${JSON.stringify(value, null, 2)}
-`, "utf8");
-}
-async function pruneEmptyDir(dir) {
-  try {
-    const entries = await fs2.readdir(dir);
-    if (entries.length === 0) await fs2.remove(dir);
-  } catch {
-  }
-}
-async function readText(file) {
-  try {
-    return await fs2.readFile(file, "utf8");
-  } catch {
-    return void 0;
-  }
-}
-async function writeText(file, value) {
-  await fs2.ensureDir(path2.dirname(file));
-  await fs2.writeFile(file, value, "utf8");
-}
-async function listFiles(root, patterns) {
-  const files = await fg(patterns, {
-    cwd: root,
-    dot: true,
-    onlyFiles: true,
-    ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**"]
-  });
-  return files.sort((a, b) => a.localeCompare(b));
-}
-function hashText(value) {
-  return `sha256-${crypto.createHash("sha256").update(value).digest("hex")}`;
-}
-async function mapWithConcurrency(items, fn, concurrency = 24) {
-  const size = Number.isFinite(concurrency) ? Math.max(1, Math.floor(concurrency)) : 24;
-  const results = new Array(items.length);
-  for (let i = 0; i < items.length; i += size) {
-    const batch = items.slice(i, i + size);
-    const settled = await Promise.all(batch.map((item, j) => fn(item, i + j)));
-    for (let j = 0; j < settled.length; j += 1) results[i + j] = settled[j];
-  }
-  return results;
-}
-
 // src/install/manifest.ts
 import os2 from "os";
 import path3 from "path";
@@ -1196,6 +1560,13 @@ ${templateContent}`;
 }
 
 // src/claude/write-claude-files.ts
+function targetDirForType(type) {
+  if (type === "agent") return "agents";
+  if (type === "template") return "templates";
+  if (type === "command") return "commands";
+  if (type === "skill") return "skills";
+  return null;
+}
 async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
   const rec = await readJson(hausPath(root, "recommendation.json")) ?? {
     mode: "fast",
@@ -1272,14 +1643,18 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
   const installedPathsByItem = /* @__PURE__ */ new Map();
   const installedIds = /* @__PURE__ */ new Set();
   const catalogItems = selectedIds !== void 0 ? rec.recommended.filter((r) => selectedIds.includes(r.id)) : rec.recommended;
+  let curatedReviewStatusSkips = 0;
   for (const item of catalogItems) {
     const manifestItem = manifestById.get(item.id);
     if (!manifestItem?.path) continue;
     if (manifestItem.source === "curated") {
       if (manifestItem.reviewStatus !== "approved") {
-        warn(
-          `Skipping curated item ${item.id}: reviewStatus is not approved (${manifestItem.reviewStatus ?? "unset"})`
-        );
+        curatedReviewStatusSkips++;
+        if (curatedReviewStatusSkips === 1) {
+          warn(
+            `Skipping curated item ${item.id}: reviewStatus is not approved (${manifestItem.reviewStatus ?? "unset"})`
+          );
+        }
         continue;
       }
       if (manifestItem.riskLevel === "blocked") {
@@ -1288,7 +1663,13 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
       }
     }
     const sourcePath = catalogItemContentPath(contentRoot, manifestItem);
-    const target = item.type === "agent" ? "agents" : item.type === "template" ? "templates" : item.type === "command" ? "commands" : "skills";
+    const target = targetDirForType(item.type);
+    if (!target) {
+      warn(
+        `Skipping ${item.id}: type "${item.type}" is unknown to this haus version \u2014 upgrade the CLI to use it`
+      );
+      continue;
+    }
     const destination = claudePath(root, target, path12.basename(sourcePath));
     if (await fs11.pathExists(sourcePath)) {
       if (dryRun) {
@@ -1310,9 +1691,19 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
       );
     }
   }
+  if (curatedReviewStatusSkips > 1) {
+    warn(
+      `${curatedReviewStatusSkips} curated items skipped: reviewStatus is not approved \u2014 possible catalog field rename upstream`
+    );
+  }
   await cleanupStaleCatalogItems(root, new Set(manifestById.keys()), 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"));
+  const prevRefById = new Map(
+    (prevLock ?? []).filter((e) => e.id && e.catalogRef).map((e) => [e.id, e.catalogRef])
+  );
+  const lockCatalogRef = (itemId) => isCatalogRefResolved() ? getResolvedCatalogRef() : prevRefById.get(itemId) ?? getResolvedCatalogRef();
   await writeManagedJson(
     root,
     hausPath(root, "selected-context.json"),
@@ -1334,7 +1725,7 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
         type: r.type,
         source: isCurated ? "curated" : "haus",
         version: hausVersion2,
-        catalogRef: CATALOG_REF,
+        catalogRef: lockCatalogRef(r.id),
         hash: await hashInstalledPaths(root, relPaths),
         installMode: "copied",
         paths: relPaths
@@ -1437,9 +1828,14 @@ async function runApply(options) {
     const rec = await readJson(hausPath(root, "recommendation.json"));
     const catalogItemCount = selectedIds !== void 0 ? selectedIds.length : rec?.recommended.length ?? 0;
     if (catalogItemCount > 0 && !await cacheHasItems()) {
-      warn(
-        isDryRun ? "Catalog cache is empty \u2014 `haus apply --write` will skip catalog items. Run `haus update` first." : "Catalog cache is empty \u2014 catalog items will be skipped. Run `haus update` first, or pass --allow-empty-cache to silence this warning."
-      );
+      const message = "No catalog content found. Run `haus update` first.";
+      if (isDryRun) {
+        warn(`Catalog cache is empty \u2014 dry-run will skip catalog items. ${message}`);
+      } else {
+        error(message);
+        process.exitCode = 1;
+        return;
+      }
     }
   }
   const files = await writeClaudeFiles(root, isDryRun, selectedIds, {
@@ -1466,185 +1862,6 @@ async function refreshProjectApply(root) {
   return writeClaudeFiles(root, false, void 0, { refillConfig: false });
 }
 
-// library/catalog/validation-rules.json
-var validation_rules_default = {
-  forbiddenTags: [
-    "python",
-    "django",
-    "go",
-    "rust",
-    "java",
-    "spring",
-    "kotlin",
-    "swift",
-    "android",
-    "flutter",
-    "dart",
-    "c++",
-    "perl",
-    "defi",
-    "trading"
-  ],
-  bannedAgentPhrases: ["autonomous", "swarm", "delegate", "orchestrat", "marketplace"],
-  requiredSkillFrontmatter: ["description"],
-  requiredAgentSections: ["## Use when", "## Do not use when", "## Verification"],
-  riskyInstallPatterns: [
-    { source: "\\bnpx\\s+-y\\b", flags: "i" },
-    { source: "\\bnpx\\s+--yes\\b", flags: "i" },
-    { source: "\\byarn\\s+dlx\\b", flags: "i" },
-    { source: "\\bpnpm\\s+dlx\\b", flags: "i" }
-  ],
-  allowedNpxPattern: { source: "\\bnpx\\s+tsx\\b", flags: "i" },
-  anyNpxPattern: { source: "\\bnpx\\s+\\S+", flags: "i" },
-  httpUrlPattern: { source: "^http:\\/\\/", flags: "i" },
-  placeholderPattern: { source: "\\bTODO\\b|\\bPLACEHOLDER\\b", flags: "i" },
-  allowedStacks: [
-    "haus",
-    "security",
-    "quality",
-    "frontend",
-    "backend",
-    "testing",
-    "review",
-    "workflow",
-    "reference-pack",
-    "core-skill",
-    "workflow-skill",
-    "stack-skill",
-    "review-skill",
-    "agent",
-    "hook",
-    "rule",
-    "react",
-    "typescript",
-    "php",
-    "csharp",
-    "vendure",
-    "vendure3",
-    "nestjs",
-    "graphql",
-    "nx21",
-    "turbo",
-    "nextjs",
-    "react19",
-    "typescript5",
-    "vite8",
-    "tanstack-query",
-    "tanstack-router",
-    "radix",
-    "radix-ui",
-    "shadcn",
-    "shadcn-ui",
-    "tailwind",
-    "tailwindcss",
-    "scss",
-    "scss-modules",
-    "vue",
-    "expressjs",
-    "soup-base",
-    "laravel",
-    "laravel-nova",
-    "wordpress",
-    "bedrock",
-    "elementor-pro",
-    "acf-pro",
-    "jetengine",
-    "dotnet",
-    "oidc",
-    "azure-ad",
-    "bankid",
-    "myid",
-    "cgi",
-    "crypto",
-    "collection2",
-    "postgresql",
-    "mariadb",
-    "mssql",
-    "elasticsearch",
-    "yarn4",
-    "pnpm89",
-    "playwright",
-    "testing-library",
-    "phpunit",
-    "storybook",
-    "wisest",
-    "vitest",
-    "jest",
-    "redis",
-    "sanity",
-    "strapi",
-    "prisma",
-    "cms",
-    "database",
-    "mysql",
-    "saml2",
-    "next-auth",
-    "auth",
-    "expo",
-    "react-native",
-    "mobile",
-    "i18next",
-    "i18n",
-    "bullmq",
-    "queue",
-    "sentry",
-    "observability",
-    "tooling",
-    "prettier",
-    "eslint",
-    "missing-prettier",
-    "missing-eslint",
-    "docker",
-    "pm2",
-    "deployer-php",
-    "stripe",
-    "qliro",
-    "supabase",
-    "payments"
-  ],
-  alwaysAllowedTags: [
-    "haus",
-    "security",
-    "quality",
-    "review",
-    "workflow",
-    "baseline",
-    "project-instructions"
-  ],
-  patternTagSuffixes: ["-patterns"]
-};
-
-// src/catalog/validation-rules.ts
-var toRegExp = (r) => new RegExp(r.source, r.flags);
-var FORBIDDEN_TAGS = validation_rules_default.forbiddenTags;
-var BANNED_AGENT_PHRASES = validation_rules_default.bannedAgentPhrases;
-var REQUIRED_SKILL_FRONTMATTER = validation_rules_default.requiredSkillFrontmatter;
-var REQUIRED_AGENT_SECTIONS = validation_rules_default.requiredAgentSections;
-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 HTTP_URL_PATTERN = toRegExp(validation_rules_default.httpUrlPattern);
-var PLACEHOLDER_PATTERN = toRegExp(validation_rules_default.placeholderPattern);
-var ALLOWED_STACKS = validation_rules_default.allowedStacks;
-var ALWAYS_ALLOWED_TAGS = validation_rules_default.alwaysAllowedTags;
-var PATTERN_TAG_SUFFIXES = validation_rules_default.patternTagSuffixes;
-var ALLOWED_SET = new Set([...ALLOWED_STACKS, ...ALWAYS_ALLOWED_TAGS].map((t) => t.toLowerCase()));
-function isTagAllowed(tag) {
-  const lower = tag.toLowerCase();
-  if (ALLOWED_SET.has(lower)) return true;
-  return PATTERN_TAG_SUFFIXES.some((suffix) => lower.endsWith(suffix));
-}
-function auditDisallowedTags(items) {
-  const failures = [];
-  for (const item of items) {
-    if (!item.id) continue;
-    for (const tag of Array.isArray(item.tags) ? item.tags : []) {
-      if (!isTagAllowed(tag)) failures.push(`${item.id}: tag not in allowlist: "${tag}"`);
-    }
-  }
-  return failures;
-}
-
 // src/commands/catalog-audit.ts
 function auditForbiddenTags(items) {
   const failures = [];
@@ -1758,6 +1975,17 @@ async function runConfig(key, action) {
   log(`${key} ${action}d`);
 }
 
+// src/recommender/token-estimate.ts
+var TOKENS_PER_ITEM = 320;
+function estimateContextTokens(selectedCount) {
+  return selectedCount * TOKENS_PER_ITEM;
+}
+function tokenReductionPct(selected, skipped) {
+  const total = selected + skipped;
+  if (total === 0) return 0;
+  return Math.max(0, Math.round(skipped / total * 100));
+}
+
 // src/recommender/explain-recommendation.ts
 function normalizeRecommendation(input2) {
   const recommended = (input2.recommended ?? []).map((item) => {
@@ -1792,13 +2020,10 @@ function normalizeRecommendation(input2) {
     recommended,
     skipped,
     warnings: input2.warnings ?? [],
-    estimatedContextTokens: input2.estimatedContextTokens ?? recommended.length * 320,
+    estimatedContextTokens: input2.estimatedContextTokens ?? estimateContextTokens(recommended.length),
     selectedRules: input2.selectedRules ?? recommended.length,
     skippedRules: input2.skippedRules ?? skipped.length,
-    estimatedTokenReductionPct: input2.estimatedTokenReductionPct ?? Math.max(
-      0,
-      Math.round(skipped.length / Math.max(recommended.length + skipped.length, 1) * 100)
-    )
+    estimatedTokenReductionPct: input2.estimatedTokenReductionPct ?? tokenReductionPct(recommended.length, skipped.length)
   };
 }
 function buildRecommendationExplanation(recommendation) {
@@ -3236,7 +3461,9 @@ async function recommend(root, context) {
       (t) => goals.includes(t) || goals.includes(t.replace(/-/g, " "))
     );
     if (goalMatch) push("goal-match", "guided goal match", `goal:${goalMatch}`);
-    if (item.tags.includes(context.packageManager) || item.tags.includes(`${context.packageManager}4`) || item.tags.includes(`${context.packageManager}89`)) {
+    const pm = context.packageManager;
+    const pmVersionedMatch = pm === "yarn" || pm === "pnpm" ? item.tags.includes(pm) || item.tags.includes(`${pm}4`) || item.tags.includes(`${pm}89`) : item.tags.includes(pm);
+    if (pmVersionedMatch) {
       push(
         "package-manager-match",
         "package manager match",
@@ -3287,13 +3514,10 @@ async function recommend(root, context) {
   }
   recommended.sort((a, b) => a.id.localeCompare(b.id));
   skipped.sort((a, b) => a.id.localeCompare(b.id));
-  const estimatedContextTokens = recommended.length * 320;
   const selectedRules = recommended.length;
   const skippedRules = skipped.length;
-  const estimatedTokenReductionPct = Math.max(
-    0,
-    Math.round(skippedRules / Math.max(selectedRules + skippedRules, 1) * 100)
-  );
+  const estimatedContextTokens = estimateContextTokens(selectedRules);
+  const estimatedTokenReductionPct = tokenReductionPct(selectedRules, skippedRules);
   return {
     mode: context.mode,
     recommended,
@@ -4167,61 +4391,6 @@ async function detectGlobalInstallDrift() {
 // src/commands/validate-catalog.ts
 import fs19 from "fs";
 import path27 from "path";
-
-// src/catalog/forbidden-content.ts
-var PROSE_FORBIDDEN_TAGS = FORBIDDEN_TAGS.filter((t) => t.toLowerCase() !== "go");
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function extractUseWhenSection(text) {
-  const marker = "## Use when";
-  const idx = text.toLowerCase().indexOf(marker.toLowerCase());
-  if (idx < 0) return "";
-  const tail = text.slice(idx + marker.length);
-  const next = tail.search(/\n##\s+/);
-  return next < 0 ? tail : tail.slice(0, next);
-}
-function isYamlBlockScalarHeader(rest) {
-  return /^[>|][-+]?(\d+)?(?:\s+#.*)?$/.test(rest);
-}
-function extractFrontmatterValue(text, key) {
-  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!m) return "";
-  const lines = m[1].split(/\r?\n/);
-  const keyRe = new RegExp(`^${escapeRegExp(key)}:[ \\t]*`);
-  const idx = lines.findIndex((l) => keyRe.test(l));
-  if (idx < 0) return "";
-  const rest = lines[idx].replace(keyRe, "").trim();
-  if (!rest) return "";
-  if (!isYamlBlockScalarHeader(rest)) {
-    return rest.replace(/^["']|["']$/g, "").trim();
-  }
-  const body = [];
-  for (let j = idx + 1; j < lines.length; j++) {
-    const line2 = lines[j];
-    if (/^[a-zA-Z_][\w.-]*:[ \t]/.test(line2)) break;
-    if (line2.trim() === "") continue;
-    if (/^\s+/.test(line2)) body.push(line2.trimStart());
-    else break;
-  }
-  return body.join(" ").replace(/\s+/g, " ").trim();
-}
-function extractFrontmatterDescription(text) {
-  return extractFrontmatterValue(text, "description");
-}
-function auditForbiddenTagsInText(text, label) {
-  const body = `${extractFrontmatterDescription(text)}
-${extractUseWhenSection(text)}`;
-  if (!body.trim()) return [];
-  const failures = [];
-  for (const word of PROSE_FORBIDDEN_TAGS) {
-    const re = new RegExp(`\\b${escapeRegExp(word)}\\b`, "i");
-    if (re.test(body)) failures.push(`${label}: forbidden stack/tag "${word}" in content`);
-  }
-  return failures;
-}
-
-// src/commands/validate-catalog.ts
 function auditForbiddenStacks(items) {
   const failures = [];
   for (const item of items) {

package/library/global/commands/haus-cloneandsetup.md

@@ -26,7 +26,9 @@ For each repo directory, run its setup **in that directory**, detecting what's n
 bash -lc 'export NVM_DIR="$HOME/.nvm"; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; cd "<repo>" && nvm install && corepack enable && yarn install'
 ```
 
-Adjust per repo:
+**Read the repo's own setup docs first — they win.** Before applying the file-heuristics below, look for the repo's canonical setup instructions: `docs/setup.md`, `CLAUDE.md`, `README.md` (or follow `docs/SUMMARY.md` to the setup page). If present, **follow them as authoritative** — they capture nested or non-standard builds a root file-scan can't see. Use the heuristics below only to fill gaps, or when the repo ships no setup doc. Example: a WordPress/Bedrock repo has **no root `package.json`** — its JS/theme build lives under `web/app/themes/<theme>` and is only described in the docs, so a root-only scan wrongly reports "no JS". When the docs point at a nested build, scan subdirectories for the relevant `package.json` / build script and run it.
+
+Adjust per repo (gap-fill, or when no setup doc exists):
 
 1. **Node version.** If `.nvmrc` (or `engines.node` in `package.json`) is present, select it with `nvm install` (reads `.nvmrc`, installs the version if missing, then switches to it). If the user uses `fnm` instead, `fnm use --install-if-missing`. If neither is available, tell the user the required version and continue on the current node.
 2. **JS dependencies.** Enable the pinned package manager with `corepack enable`, then install based on what's present:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haus-tech/haus-workflow",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Haus AI workflow CLI for Claude Code.",
   "type": "module",
   "bin": {