@haus-tech/haus-workflow 0.23.1 → 0.24.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.24.1](https://github.com/WeAreHausTech/haus-workflow/compare/v0.24.0...v0.24.1) (2026-06-12)
+
+### Bug Fixes
+
+- **settings:** reconcile haus permission rules on update/apply ([#104](https://github.com/WeAreHausTech/haus-workflow/issues/104)) ([8ab070c](https://github.com/WeAreHausTech/haus-workflow/commit/8ab070c006943f600b6dccb7582b8330d452d3c1))
+
+## [0.24.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.23.1...v0.24.0) (2026-06-12)
+
+### Features
+
+- **cloneandsetup:** local-dev orchestration via localdev.yml ([#97](https://github.com/WeAreHausTech/haus-workflow/issues/97)) ([8a2b5d3](https://github.com/WeAreHausTech/haus-workflow/commit/8a2b5d3e9a767bfe92152189b37921d58878818b))
+
 ## [0.23.1](https://github.com/WeAreHausTech/haus-workflow/compare/v0.23.0...v0.23.1) (2026-06-12)
 
 ## [0.23.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.22.1...v0.23.0) (2026-06-12)

package/README.md

@@ -8,21 +8,24 @@
 
 Requires Node 22+.
 
+**Terminal:**
+
 ```bash
 npm install -g @haus-tech/haus-workflow
 ```
 
+**Or paste this into Claude Code:**
+
+```
+Install the haus-workflow CLI globally by running `npm install -g @haus-tech/haus-workflow`.
+```
+
 A **global** install auto-runs `haus install` via a postinstall hook — it seeds
 `~/.claude/` with Haus-managed skills, global slash commands, and hooks, merges
 security rules into `~/.claude/settings.json`, and prints a notice of what changed.
 It is non-fatal, idempotent, and global-only. Skip it with `HAUS_NO_POSTINSTALL=1`;
 re-run or repair any time with `haus install`. Undo with `haus uninstall`.
 
-**Driving it from Claude Code (no terminal):** once installed, every project's `/`
-menu has `/haus-setup`, `/haus-doctor`, and `/haus-fix`. Run `/haus-setup` (or just
-ask "set up my project") and the agent scans, asks a few plain-language questions,
-and configures the repo for you.
-
 ---
 
 ## haus-workflow skill
@@ -30,7 +33,7 @@ and configures the repo for you.
 Once installed, Claude Code gains a `/haus-workflow` slash command.
 
 The `project:*` tasks act on the current repo. The unprefixed verbs (`update`,
-`catalog`, `install`, `uninstall`) manage the haus tool itself on your machine
+`install`, `uninstall`) manage the haus tool itself on your machine
 (`~/.claude` + npm), like `npm install -g`. The short legacy names still work.
 
 ```
@@ -41,25 +44,12 @@ The `project:*` tasks act on the current repo. The unprefixed verbs (`update`,
 /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.
 
 ---
 
-## Per-project setup
-
-Run once inside each project:
-
-```bash
-haus init
-```
-
-Scans the repo, recommends context assets, and writes `.claude/` and `.haus-workflow/`.
-
----
-
 ## Commands
 
 ```bash
@@ -73,12 +63,13 @@ haus apply --write     # write .claude/ files (skills, agents, commands, templat
 haus apply --select    # interactively choose which recommended items to install
 haus apply --refill-config    # fill still-blank workflow-config.md fields, keep edits
 haus context --task "<task>"  # select context rules for a task (token-budgeted)
-haus update                   # sync remote catalog + re-apply project files
+haus update                   # check npm for new CLI + sync catalog + refresh ~/.claude/ and this project
 haus update --check           # check for updates without applying
 haus undo                     # remove haus-managed project files (lock-tracked paths)
 haus doctor                   # health check: hooks, CLAUDE.md, imports, catalog cache
 haus config                   # manage hook configuration
-haus guard                    # test bash/file-access guards
+haus guard                    # security guard hook (bash + file-access); invoked by PreToolUse
+haus workspace                # multi-repo ops: discover, scan, setup, doctor across a workspace
 haus uninstall                # remove Haus-managed files from ~/.claude/
 ```
 
@@ -87,24 +78,16 @@ haus uninstall                # remove Haus-managed files from ~/.claude/
 
 ---
 
-## Development
-
-```bash
-yarn install
-yarn verify   # typecheck + lint + build + test
-yarn dev <cmd>  # run CLI without building (tsx)
-```
-
-### Catalog
+## Catalog
 
 Content lives in [`haus-workflow-catalog`](https://github.com/WeAreHausTech/haus-workflow-catalog)
-(71 items; version pinned in `library/catalog/manifest.json`). Fetched at runtime from `main` (override with `HAUS_CATALOG_REF`).
+(version pinned in `library/catalog/manifest.json`). Fetched at runtime from `main` (override with `HAUS_CATALOG_REF`).
 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.
 
-### Internal docs
+## Internal docs
 
 - [Architecture](docs/architecture.md)
 - [CLI reference](docs/cli.md)

package/dist/cli.js

@@ -936,53 +936,63 @@ function mergeHooks(settings, fragments) {
   };
   return { settings: updated, addedIds };
 }
+function reconcileManagedRules(existing, prevTracked, newRules) {
+  const prevTrackedSet = new Set(prevTracked);
+  const userRules = [];
+  const userSet = /* @__PURE__ */ new Set();
+  for (const rule of existing) {
+    if (prevTrackedSet.has(rule) || userSet.has(rule)) continue;
+    userSet.add(rule);
+    userRules.push(rule);
+  }
+  const tracked = [];
+  const trackedSet = /* @__PURE__ */ new Set();
+  for (const rule of newRules) {
+    if (userSet.has(rule) || trackedSet.has(rule)) continue;
+    trackedSet.add(rule);
+    tracked.push(rule);
+  }
+  const existingSet = new Set(existing);
+  const added = tracked.filter((rule) => !existingSet.has(rule));
+  const newSet = /* @__PURE__ */ new Set([...userSet, ...trackedSet]);
+  const removed = existing.filter((rule) => !newSet.has(rule));
+  return { rules: [...userRules, ...tracked], tracked, added, removed };
+}
 function mergeDenyRules(settings, rules) {
   const existingDeny = settings.permissions?.deny ?? [];
-  const seen = new Set(existingDeny);
   const trackedDeny = settings._haus?.denyRules ?? [];
-  const addedRules = [];
-  for (const rule of rules) {
-    if (seen.has(rule)) continue;
-    seen.add(rule);
-    addedRules.push(rule);
-  }
+  const { rules: deny2, tracked, added } = reconcileManagedRules(existingDeny, trackedDeny, rules);
   const updated = { ...settings };
   updated.permissions = {
     ...settings.permissions ?? {},
-    deny: [...existingDeny, ...addedRules]
+    deny: deny2
   };
   updated._haus = {
     hooks: settings._haus?.hooks ?? [],
     ...settings._haus?.hookCommands ? { hookCommands: settings._haus.hookCommands } : {},
-    denyRules: [...trackedDeny, ...addedRules],
+    denyRules: tracked,
     ...settings._haus?.allowRules ? { allowRules: settings._haus.allowRules } : {},
     ...settings._haus?.askRules ? { askRules: settings._haus.askRules } : {}
   };
-  return { settings: updated, addedRules };
+  return { settings: updated, addedRules: added };
 }
 function mergeAllowRules(settings, rules) {
   const existingAllow = settings.permissions?.allow ?? [];
-  const seen = new Set(existingAllow);
   const trackedAllow = settings._haus?.allowRules ?? [];
-  const addedRules = [];
-  for (const rule of rules) {
-    if (seen.has(rule)) continue;
-    seen.add(rule);
-    addedRules.push(rule);
-  }
+  const { rules: allow, tracked, added } = reconcileManagedRules(existingAllow, trackedAllow, rules);
   const updated = { ...settings };
   updated.permissions = {
     ...settings.permissions ?? {},
-    allow: [...existingAllow, ...addedRules]
+    allow
   };
   updated._haus = {
     hooks: settings._haus?.hooks ?? [],
     ...settings._haus?.hookCommands ? { hookCommands: settings._haus.hookCommands } : {},
     ...settings._haus?.denyRules ? { denyRules: settings._haus.denyRules } : {},
-    allowRules: [...trackedAllow, ...addedRules],
+    allowRules: tracked,
     ...settings._haus?.askRules ? { askRules: settings._haus.askRules } : {}
   };
-  return { settings: updated, addedRules };
+  return { settings: updated, addedRules: added };
 }
 function stripHausAllow(settings) {
   const prevHaus = settings._haus;
@@ -1039,27 +1049,21 @@ function stripHausHooks(settings) {
 }
 function mergeAskRules(settings, rules) {
   const existingAsk = settings.permissions?.ask ?? [];
-  const seen = new Set(existingAsk);
   const trackedAsk = settings._haus?.askRules ?? [];
-  const addedRules = [];
-  for (const rule of rules) {
-    if (seen.has(rule)) continue;
-    seen.add(rule);
-    addedRules.push(rule);
-  }
+  const { rules: ask2, tracked, added } = reconcileManagedRules(existingAsk, trackedAsk, rules);
   const updated = { ...settings };
   updated.permissions = {
     ...settings.permissions ?? {},
-    ask: [...existingAsk, ...addedRules]
+    ask: ask2
   };
   updated._haus = {
     hooks: settings._haus?.hooks ?? [],
     ...settings._haus?.hookCommands ? { hookCommands: settings._haus.hookCommands } : {},
     ...settings._haus?.denyRules ? { denyRules: settings._haus.denyRules } : {},
     ...settings._haus?.allowRules ? { allowRules: settings._haus.allowRules } : {},
-    askRules: [...trackedAsk, ...addedRules]
+    askRules: tracked
   };
-  return { settings: updated, addedRules };
+  return { settings: updated, addedRules: added };
 }
 function stripHausAsk(settings) {
   const prevHaus = settings._haus;
@@ -1523,31 +1527,9 @@ var CANONICAL_HOOKS = {
     ]
   }
 };
-var STABLE_HOOK_IDS = {
-  "haus context --from-hook": "haus.context-hook",
-  "haus guard file-access --from-hook": "haus.guard-file",
-  "haus guard bash --from-hook": "haus.guard-bash"
-};
 async function loadClaudeHooksSettings() {
   return { ...CANONICAL_HOOKS, permissions: { deny: buildDenyRules(), ask: buildAskRules() } };
 }
-function flattenRecommendedHooks(settings) {
-  const out = [];
-  let generic = 0;
-  for (const block of settings.hooks.UserPromptSubmit) {
-    for (const h of block.hooks) {
-      const id = STABLE_HOOK_IDS[h.command] ?? `haus.hook.user-${generic++}`;
-      out.push({ id, command: h.command });
-    }
-  }
-  for (const block of settings.hooks.PreToolUse) {
-    for (const h of block.hooks) {
-      const id = STABLE_HOOK_IDS[h.command] ?? `haus.hook.pre-${generic++}`;
-      out.push({ id, command: h.command });
-    }
-  }
-  return out;
-}
 
 // src/claude/verify-hooks-contract.ts
 function collectHookCommands(settings) {
@@ -1748,7 +1730,6 @@ function refillContent(existing, v) {
   }).join("\n");
 }
 var FALLBACK_CONTEXT = {
-  mode: "fast",
   generatedAt: "",
   root: "",
   repoName: "",
@@ -1871,7 +1852,6 @@ function targetDirForType(type) {
 }
 async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
   const rec = await readJson(hausPath(root, "recommendation.json")) ?? {
-    mode: "fast",
     recommended: [],
     skipped: [],
     warnings: [],
@@ -1885,7 +1865,6 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
   const coreFiles = [
     claudePath(root, "settings.json"),
     claudePath(root, "rules", "haus.md"),
-    claudePath(root, "rules", "security.md"),
     claudePath(root, "commands", "haus-doctor.md")
   ];
   const rootClaudeMdPath = await writeRootClaudeMd(root, dryRun);
@@ -1898,12 +1877,7 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
     ...workflowPath ? [workflowPath] : [],
     ...workflowConfigPath ? [workflowConfigPath] : []
   ];
-  const files = dryRun ? [...coreFiles, ...p6Files] : [
-    ...coreFiles,
-    ...p6Files,
-    hausPath(root, "selected-context.json"),
-    hausPath(root, "haus.lock.json")
-  ];
+  const files = dryRun ? [...coreFiles, ...p6Files] : [...coreFiles, ...p6Files, hausPath(root, "haus.lock.json")];
   if (dryRun) {
     const mergedSettings = await mergeProjectSettings(root);
     await writeManagedJson(root, claudePath(root, "settings.json"), mergedSettings, true);
@@ -1938,15 +1912,58 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
   await writeManagedText(
     root,
     claudePath(root, "rules", "haus.md"),
-    "- Keep context minimal.\n- Follow project conventions.\n\n## Driving haus\nWhen the user asks to set up, configure, check, or fix the project, run `haus setup-project` or `haus doctor` and narrate results in plain language \u2014 never make them use a terminal or read JSON. The `/haus-setup`, `/haus-doctor`, and `/haus-fix` commands do the same.\n",
-    dryRun
-  );
-  await writeManagedText(
-    root,
-    claudePath(root, "rules", "security.md"),
-    "- Never read secrets.\n- Block dangerous shell commands.\n",
+    [
+      "- Keep context minimal.",
+      "- Follow project conventions.",
+      "- Never read secrets.",
+      "- Block dangerous shell commands.",
+      "- NEVER hand-edit haus-managed blocks (`<!-- HAUS:BEGIN \u2026 -->` \u2026 `<!-- HAUS:END \u2026 -->`)",
+      "  or haus-owned files under `.claude/` / `.haus-workflow/` \u2014 regenerate via `haus apply`.",
+      "  Hand-edits are silently overwritten or flagged as drift.",
+      "",
+      "## Driving haus",
+      "haus owns `.claude/` and `.haus-workflow/`. When the user asks to set up, configure,",
+      "check, fix, refresh, or update the project, run the matching `haus` command and narrate",
+      "results in plain language \u2014 never make them use a terminal or read JSON.",
+      "- Set up / configure / fix / check \u2192 `haus setup-project`, `haus apply --write`, `haus doctor`",
+      "- Update package + catalog \u2192 `haus update`",
+      "- The `/haus-workflow`, `/haus-setup`, `/haus-doctor`, and `/haus-fix` commands do the same.",
+      ""
+    ].join("\n"),
     dryRun
   );
+  const legacySecurityPath = claudePath(root, "rules", "security.md");
+  if (await fs12.pathExists(legacySecurityPath)) {
+    const content2 = await fs12.readFile(legacySecurityPath, "utf8");
+    const stub = "- Never read secrets.\n- Block dangerous shell commands.";
+    if (content2 === stub || content2 === `${stub}
+` || content2 === `${stub}\r
+`) {
+      if (dryRun) {
+        log(`[dry-run] would remove stale ${displayPath(root, legacySecurityPath)}`);
+      } else {
+        await fs12.remove(legacySecurityPath);
+      }
+    }
+  }
+  const LEGACY_PRUNED_ARTIFACTS = [
+    "selected-context.json",
+    "dependency-map.json",
+    "scan-hashes.json",
+    "recommended-hooks.json",
+    "recommended-rules.json",
+    "repo-summary.md"
+  ];
+  for (const rel of LEGACY_PRUNED_ARTIFACTS) {
+    const legacyPath = hausPath(root, rel);
+    if (await fs12.pathExists(legacyPath)) {
+      if (dryRun) {
+        log(`[dry-run] would remove stale ${displayPath(root, legacyPath)}`);
+      } else {
+        await fs12.remove(legacyPath);
+      }
+    }
+  }
   const { items: manifestItems, contentRoot } = await loadCatalogContext(root);
   const manifestById = new Map(manifestItems.map((item) => [item.id, item]));
   const installedPathsByItem = /* @__PURE__ */ new Map();
@@ -2028,17 +2045,6 @@ async function writeClaudeFiles(root, dryRun, selectedIds, opts = {}) {
     (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"),
-    installedItems.map((r) => ({
-      id: r.id,
-      type: r.type,
-      reason: r.reason,
-      selectionMode: r.selectionMode
-    })),
-    false
-  );
   const lock = await Promise.all(
     installedItems.map(async (r) => {
       const relPaths = installedPathsByItem.get(r.id) ?? [];
@@ -2354,7 +2360,6 @@ function normalizeRecommendation(input2) {
     })) ?? [{ code: "legacy-skip-reason", message: item.reason ?? "legacy skipped reason" }]
   }));
   return {
-    mode: input2.mode === "guided" ? "guided" : "fast",
     recommended,
     skipped,
     warnings: input2.warnings ?? [],
@@ -2677,7 +2682,6 @@ function selectRules(recommended, task, taskIntents) {
 }
 
 // src/scanner/scan-project.ts
-import { readFile as readFile2 } from "fs/promises";
 import path20 from "path";
 
 // src/utils/audit-checks.ts
@@ -3143,7 +3147,7 @@ var SAFE_FILES = [
   "build.gradle.kts",
   "Gemfile"
 ];
-async function scanProject(root, mode = "fast") {
+async function scanProject(root) {
   const pkg = await readJson(path20.join(root, "package.json"));
   const composer = await readJson(path20.join(root, "composer.json"));
   const files = await listFiles(root, SAFE_FILES);
@@ -3159,9 +3163,6 @@ async function scanProject(root, mode = "fast") {
   const warnings = [];
   const securityRisks = [];
   const crossRepoHints = [];
-  if (!safeFiles.some((f) => f.endsWith(".env.example"))) warnings.push("No .env.example found");
-  if (!(pkg && isRecord(pkg.scripts) && String(pkg.scripts.test ?? "").length > 0))
-    warnings.push("No package.json test script found");
   const nodeEngine = isRecord(pkg?.engines) ? String(pkg.engines.node ?? "") : "";
   if (nodeEngine && !satisfiesVersion(process.version, nodeEngine)) {
     warnings.push(`Current Node ${process.version} does not satisfy package engine ${nodeEngine}`);
@@ -3170,13 +3171,11 @@ async function scanProject(root, mode = "fast") {
     crossRepoHints.push("Containerized services detected");
   if (safeFiles.some((f) => f.includes("turbo.json") || f.includes("nx.json")))
     crossRepoHints.push("Monorepo orchestration detected");
-  if (!safeFiles.some((f) => f.endsWith(".env.example"))) securityRisks.push("Missing env template");
   if (safeFiles.some((f) => f.includes("wp-content/uploads")))
     securityRisks.push("Uploads directory present");
   const unsupportedSignals = collectUnsupportedSignals(safeFiles);
   const detectionStatus = computeDetectionStatus(roles, stacks, unsupportedSignals);
   const context = {
-    mode,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     root,
     repoName: String(pkg?.name ?? path20.basename(root)),
@@ -3190,30 +3189,16 @@ async function scanProject(root, mode = "fast") {
     detectionStatus,
     unsupportedSignals
   };
-  const dependencyMap = {
-    node: deps.filter((d) => !d.includes("/")),
-    composer: isRecord(composer?.require) ? Object.keys(composer.require) : []
-  };
-  const scanHashes = Object.fromEntries(
-    await mapWithConcurrency(
-      safeFiles,
-      async (f) => [f, hashText(await readFile2(path20.join(root, f), "utf8"))]
-    )
-  );
-  const repoSummary = renderSummary(context);
   await writeJson(hausPath(root, "context-map.json"), context);
-  await writeJson(hausPath(root, "dependency-map.json"), dependencyMap);
-  await writeJson(hausPath(root, "scan-hashes.json"), scanHashes);
-  await writeText(hausPath(root, "repo-summary.md"), repoSummary);
   await writeSourcesReport(root);
-  return { ...context, dependencyMap, scanHashes, repoSummary };
+  return context;
 }
 
 // src/scanner/read-context.ts
 async function readContextOrScan(root) {
   const context = await readJson(hausPath(root, "context-map.json"));
   if (context) return context;
-  const scan = await scanProject(root, "fast");
+  const scan = await scanProject(root);
   return scan;
 }
 
@@ -3236,7 +3221,7 @@ async function runContext(options) {
     return;
   }
   const context = await readContextOrScan(root);
-  const summary = await readText(hausPath(root, "repo-summary.md")) ?? "";
+  const summary = renderSummary(context);
   const recommendationRaw = await readJson(hausPath(root, "recommendation.json"));
   const recommendation = recommendationRaw ? normalizeRecommendation(recommendationRaw) : void 0;
   const taskIntents = options.task ? classifyTaskIntents(options.task) : /* @__PURE__ */ new Set();
@@ -3529,7 +3514,6 @@ function formatReasonWithSignal(reason) {
 function formatRecommendationHuman(rec) {
   const lines = [];
   lines.push("Recommendation explanation");
-  lines.push(`  mode: ${rec.mode}`);
   lines.push(
     `  selected: ${rec.selectedRules} | skipped: ${rec.skippedRules} | estimated token reduction: ${rec.estimatedTokenReductionPct}%`
   );
@@ -3725,7 +3709,6 @@ function mergeRecommendationWarnings(context) {
 // src/recommender/recommend.ts
 async function recommend(root, context) {
   const items = await loadCatalog(root);
-  const setupAnswers = await readJson(hausPath(root, "setup-answers.json")) ?? {};
   const sources = await readJson(
     hausPath(root, "sources-report.json")
   ) ?? {};
@@ -3746,7 +3729,6 @@ async function recommend(root, context) {
   const depSet = scannerDeps;
   const recommended = [];
   const skipped = [];
-  const goals = Object.values(setupAnswers).join(" ").toLowerCase();
   const sourceTrust = new Map((sources.items ?? []).map((x) => [x.id, x.status ?? "candidate"]));
   const changedFiles = await readChangedFiles(root);
   const skip = (id, code, message, signal) => {
@@ -3820,10 +3802,6 @@ async function recommend(root, context) {
     if (roleMatch) push("repo-role-match", "repo role match", roleSignal(roleMatch));
     const tagMatch = item.tags.find((t) => stackSet.has(t.toLowerCase()));
     if (tagMatch) push("stack-match", "stack/dependency match", stackSignal(tagMatch));
-    const goalMatch = item.tags.find(
-      (t) => goals.includes(t) || goals.includes(t.replace(/-/g, " "))
-    );
-    if (goalMatch) push("goal-match", "guided goal match", `goal:${goalMatch}`);
     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) {
@@ -3882,7 +3860,6 @@ async function recommend(root, context) {
   const estimatedContextTokens = estimateContextTokens(selectedRules);
   const estimatedTokenReductionPct = tokenReductionPct(selectedRules, skippedRules);
   return {
-    mode: context.mode,
     recommended,
     skipped,
     warnings: mergeRecommendationWarnings(context),
@@ -3902,8 +3879,8 @@ function buildStackSet(context) {
 
 // src/commands/setup-core.ts
 async function runSetupCore(root, opts) {
-  const { mode, json, apply, dryRun, confirm: confirm2 } = opts;
-  const scanResult = await scanProject(root, mode);
+  const { json, apply, dryRun, confirm: confirm2 } = opts;
+  const scanResult = await scanProject(root);
   if (json) {
     log(JSON.stringify(scanResult, null, 2));
   } else {
@@ -3914,12 +3891,6 @@ async function runSetupCore(root, opts) {
   const context = await readContextOrScan(root);
   const recommendation = await recommend(root, context);
   await writeJson(hausPath(root, "recommendation.json"), recommendation);
-  const hookSettings = await loadClaudeHooksSettings();
-  await writeJson(hausPath(root, "recommended-hooks.json"), flattenRecommendedHooks(hookSettings));
-  await writeJson(hausPath(root, "recommended-rules.json"), [
-    { id: "haus.rule.context-minimal", enabled: true },
-    { id: "haus.rule.security", enabled: true }
-  ]);
   if (json) {
     log(JSON.stringify(recommendation, null, 2));
   } else {
@@ -3987,7 +3958,6 @@ async function runSetupCore(root, opts) {
 async function runSetupProject(options) {
   const root = process.cwd();
   await runSetupCore(root, {
-    mode: "fast",
     json: options.json,
     apply: !options.json,
     dryRun: false,
@@ -4317,12 +4287,6 @@ async function runRecommend(options) {
   const context = await readContextOrScan(root);
   const result = await recommend(root, context);
   await writeJson(hausPath(root, "recommendation.json"), result);
-  const hookSettings = await loadClaudeHooksSettings();
-  await writeJson(hausPath(root, "recommended-hooks.json"), flattenRecommendedHooks(hookSettings));
-  await writeJson(hausPath(root, "recommended-rules.json"), [
-    { id: "haus.rule.context-minimal", enabled: true },
-    { id: "haus.rule.security", enabled: true }
-  ]);
   if (options.json) {
     log(JSON.stringify(result, null, 2));
     return;
@@ -4335,7 +4299,7 @@ async function runRecommend(options) {
 // src/commands/refresh.ts
 async function runRefresh() {
   const root = process.cwd();
-  const context = await scanProject(root, "fast");
+  const context = await scanProject(root);
   const recommendation = await recommend(root, context);
   await writeJson(hausPath(root, "recommendation.json"), recommendation);
   log("Haus refresh complete");
@@ -4346,8 +4310,7 @@ async function runRefresh() {
 
 // src/commands/scan.ts
 async function runScan(options) {
-  const mode = options.mode ?? "fast";
-  const result = await scanProject(process.cwd(), mode);
+  const result = await scanProject(process.cwd());
   if (options.json) {
     log(JSON.stringify(result, null, 2));
     return;
@@ -4362,16 +4325,8 @@ import path24 from "path";
 import fs18 from "fs-extra";
 
 // src/claude/managed-paths.ts
-var PROJECT_MANAGED_CLAUDE_REL = [
-  "rules/haus.md",
-  "rules/security.md",
-  "commands/haus-doctor.md"
-];
-var PROJECT_MANAGED_HAUS_REL = [
-  "selected-context.json",
-  "haus.lock.json",
-  "config.json"
-];
+var PROJECT_MANAGED_CLAUDE_REL = ["rules/haus.md", "commands/haus-doctor.md"];
+var PROJECT_MANAGED_HAUS_REL = ["haus.lock.json", "config.json"];
 function coreManagedAbsolutePaths(root) {
   const claude = PROJECT_MANAGED_CLAUDE_REL.map((rel) => claudePath(root, rel));
   const haus = PROJECT_MANAGED_HAUS_REL.map((rel) => hausPath(root, rel));
@@ -4579,7 +4534,7 @@ function summarizeLockDiff(before, after) {
 }
 
 // src/update/lockfile.ts
-import { mkdir, readFile as readFile3, copyFile } from "fs/promises";
+import { mkdir, readFile as readFile2, copyFile } from "fs/promises";
 import path26 from "path";
 async function checkLock(root) {
   const lock = await readJson(hausPath(root, "haus.lock.json")) ?? [];
@@ -4603,7 +4558,7 @@ async function applyLock(root) {
   const lockPath = hausPath(root, "haus.lock.json");
   let before = "[]";
   try {
-    before = await readFile3(lockPath, "utf8");
+    before = await readFile2(lockPath, "utf8");
   } catch {
     before = "[]";
   }
@@ -4633,7 +4588,7 @@ function diffLock(before, after) {
 }
 async function hasLocalOverrides(root) {
   try {
-    await readFile3(path26.join(root, ".claude", "settings.json"), "utf8");
+    await readFile2(path26.join(root, ".claude", "settings.json"), "utf8");
     return true;
   } catch {
     return false;
@@ -5091,7 +5046,7 @@ async function discoverRepos(workspaceRoot, maxDepth = DEFAULT_MAX_DEPTH) {
     const name = typeof pkg?.name === "string" && pkg.name.length > 0 ? pkg.name : path30.basename(relDir === "." ? workspaceRoot : absDir);
     let role = "auto";
     try {
-      const scan = await scanProject(absDir, "fast");
+      const scan = await scanProject(absDir);
       if (scan.repoRoles[0]) role = scan.repoRoles[0];
     } catch {
     }
@@ -5376,7 +5331,6 @@ function isRootRepo(workspaceRoot, repoPath) {
   return path34.resolve(workspaceRoot, repoPath) === path34.resolve(workspaceRoot);
 }
 async function runWorkspaceSetup(workspaceRoot, options = {}) {
-  const mode = options.mode ?? "fast";
   const apply = options.write ?? false;
   const configText = await readText(path34.join(workspaceRoot, WORKSPACE_FILE));
   if (!configText) {
@@ -5403,7 +5357,6 @@ async function runWorkspaceSetup(workspaceRoot, options = {}) {
         throw new Error(`Repo path is not a directory: ${repo.path}`);
       }
       const res = await runSetupCore(repoRoot, {
-        mode,
         json: options.json,
         apply,
         dryRun: options.dryRun
@@ -5569,7 +5522,7 @@ async function scanWorkspace(workspaceRoot, opts) {
     if (!existsSync5(repoRoot) || !statSync2(repoRoot).isDirectory()) {
       throw new Error(`Repo path is not a directory: ${repo.path}`);
     }
-    const result = await scanProject(repoRoot, "fast");
+    const result = await scanProject(repoRoot);
     inputs.push({ name: repo.name, path: repo.path, context: result });
   }
   const written = await writeWorkspaceArtifacts(workspaceRoot, inputs, config2.relationships);
@@ -5599,7 +5552,6 @@ async function runWorkspace(action, options = {}) {
       return;
     case "setup":
       await runWorkspaceSetup(workspaceRoot, {
-        mode: options.guided ? "guided" : "fast",
         write: options.write,
         dryRun: options.dryRun,
         json: options.json,
@@ -5675,7 +5627,7 @@ var workspace = program.command("workspace");
 workspace.command("init").action(() => runWorkspace("init"));
 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));
-workspace.command("setup").description("Per-repo setup loop + workspace layer + manifest").option("--write", "Apply changes (default previews only)").option("--dry-run", "Preview changes without writing").option("--json", "Emit machine-readable per-repo output").option("--fast", "Skip interactive prompts (default)").option("--guided", "Enable guided Q&A per repo").option("--continue-on-error", "Keep going past a failed repo (default fail-fast)").option("--only <names>", "Restrict to comma-separated repo names").action((opts) => runWorkspace("setup", opts));
+workspace.command("setup").description("Per-repo setup loop + workspace layer + manifest").option("--write", "Apply changes (default previews only)").option("--dry-run", "Preview changes without writing").option("--json", "Emit machine-readable per-repo output").option("--continue-on-error", "Keep going past a failed repo (default fail-fast)").option("--only <names>", "Restrict to comma-separated repo names").action((opts) => runWorkspace("setup", opts));
 workspace.command("doctor").description("Report workspace drift against the manifest").option("--json", "Output the manifest and drift array as JSON").action((opts) => runWorkspace("doctor", opts));
 program.parseAsync(process.argv).catch((err) => {
   const message = err instanceof Error ? err.message : String(err);

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

@@ -1,51 +1,100 @@
-Clone a project's repos **and** set each one up locally — node version, dependencies, env scaffold. This is `project:clone` followed by a per-repo setup pass.
+Clone a project's repos **and** set each one up for local development — node version, dependencies, databases, cross-repo links, and env. This is `project:clone` followed by a per-repo setup pass and a localdev orchestration pass.
 
-**Always ask before doing work — never assume.** Cloning and setup both run things that take time, hit the network, and need auth; confirm with the user before each phase, and respect repos they already have.
+**Always ask before doing work — never assume.** Cloning and setup hit the network, need auth, and can touch databases; confirm before each phase, and respect repos the user already has.
 
 ## Step 1 — Clone
 
-Run the full `project:clone` flow first by following `~/.claude/commands/haus-clone.md` end to end — whichever mode applies:
+Run the full `project:clone` flow by following `~/.claude/commands/haus-clone.md` end to end (name → one repo; no name → workspace repos from `repos.manifest.json`). Carry the resulting repo list into Step 2.
 
-- A **name** was given → it finds and clones that one repo from GitHub.
-- **No name** → it clones the workspace's repos from `repos.manifest.json` (asking clean-clone vs reuse-local first).
+## Step 2 — Confirm the setup pass
 
-When that finishes you have a set of repos on disk (freshly cloned and/or reused-local). Carry that list into Step 2.
+1. List the repos and what each will run (node, deps, localdev steps). Get a go-ahead. For **reused** local clones, ask whether to re-run setup.
+2. Check `NODE_AUTH_TOKEN` is exported if any repo needs private `@`-scoped packages; if missing, tell the user — those installs fail without it.
 
-## Step 2 — Confirm the setup pass
+## Step 3 — Per-repo dependency pass
 
-Before running any setup:
+For each repo, in its own directory, detect and install from the repo's own files (read its `docs/setup.md` / `CLAUDE.md` / `README.md` first — they win). Select node from `.nvmrc`/`engines.node` (`nvm install`), enable the pinned package manager (`corepack enable`), install JS deps (`yarn`/`pnpm`/`npm` by lockfile), composer deps if `composer.json` + `composer` present. Run each repo's steps in one login shell so the node version stays active. Per-repo failure is reported and skipped, not fatal.
 
-1. List the repos you're about to set up and what each will run (node version select, dependency install, etc.). Get a go-ahead. For repos that were **reused** from an existing local clone, ask whether to (re)run setup there too — they may already be set up.
-2. Check `NODE_AUTH_TOKEN` is exported if any repo depends on private `@`-scoped packages (e.g. `@haus-storefront-*`, `@haus-tech/*`). If it's missing, tell the user to set it first — those installs will fail without it. Let them decide whether to continue or stop.
+**Scaffold `.env`** so the env-wiring in Step 4 has a file to write to: if `.env.example` exists and `.env` does not, copy it; otherwise create an empty `.env`. Per decision D5, write `.env`; if the write is blocked, print the values for the user to add. Tell the user real secrets still need filling.
 
-## Step 3 — Set up each repo
+## Step 4 — Local-dev orchestration
 
-For each repo directory, run its setup **in that directory**, detecting what's needed from the repo's own files — don't assume a stack. Run a repo's steps in a single login shell so the selected node version stays active for the install. A robust pattern:
+This is the phase that takes the workspace from "installed" to "ready to run." It is driven by `localdev.yml` files; a repo with none is set up by Step 3 only.
 
-```
-bash -lc 'export NVM_DIR="$HOME/.nvm"; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; cd "<repo>" && nvm install && corepack enable && yarn install'
+### House conventions (the "how", so repos specify only the "what")
+
+Specify the least. Infer the rest from the repo's stack + these conventions, and work out the concrete commands at run time:
+
+- **IMPORTANT — never install anything without asking first; global/system tools especially** (Homebrew, Docker, Laravel Herd, global `npm`/`composer` packages). Detect what's already present; if something required is missing, name it, say why it's needed, and get an explicit **yes** before installing. Prefer the least-invasive option, and don't switch or override tools the dev already has.
+- **PHP / WordPress sites are served by the developer's own PHP environment.** If they already have one — detect `valet`, `herd`, `ddev`, or `php` on PATH — **use it**: just satisfy the env contract (docroot → the repo's `web/`, HTTPS) and report the URL; never override what they already run. **Only when no local PHP environment exists** (a completely fresh machine) suggest installing **[Laravel Herd](https://herd.laravel.com)** as the default (asking first) and point its docroot at `web/` + `herd secure`.
+- **Databases and other services (a repo's `needs:`) run in Docker.** **If Docker isn't installed**, it's a prerequisite for these — tell the user and **ask before installing it** (it's a global install). Once Docker is available, provision services the simplest way (a one-off `docker run`, or the repo's own compose if it ships one), then wire the matching env vars to point at them. Confirm before creating/overwriting data.
+- **Dependencies** install from the lockfile (Step 3).
+- A repo's `localdev.yml` carries **only what can't be inferred** — its `needs`, repo-specific `build`/`seed` commands, env keys, and URL. Detect the stack (e.g. Bedrock = `composer.json` + `web/` docroot + `wp-cli.yml`; Vendure/Node = `docker-compose.yml` + `@vendure/*`) and apply the matching convention.
+
+### The `localdev.yml` format
+
+**Per-repo — `<repo>/.haus-workflow/localdev.yml`** (how to set up THAT repo alone; sibling-agnostic):
+
+All fields optional. **Prefer intent (`needs`/`build`/`seed`/`serve`) over explicit `steps`** —
+the conventions above turn intent into commands.
+
+```yaml
+needs: [mysql] # services this repo requires; provisioned in Docker, env wired to them
+needsEnv: [WP_HOME, DB_NAME] # env keys that must be present to run/serve
+build: 'yarn build' # optional: the build command (run after deps)
+seed: 'dep db:pull staging-oderland' # optional: how to load data; remote/destructive → confirm first
+serve: # optional: how it runs (printed as a next-step, never auto-started)
+  via: herd # herd | valet | docker | command — for PHP envs, bring-your-own (don't install)
+  url: 'https://example.test'
+  start: 'yarn dev'
+steps: # optional escape hatch: explicit ordered shell steps when intent isn't enough
+  - run: 'composer install'
+    node: 10 # nvm version for THIS step
+    remote: true # SSH → confirm first
+    destructive: true # overwrites data → confirm first
+    optional: true # failure is non-fatal, continue
 ```
 
-**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.
+**Workspace — `<workspace>/.haus-workflow/localdev.yml`** (the glue BETWEEN repos):
+
+```yaml
+order: [repo-a, repo-b] # setup/startup order, by manifest id
+links:
+  - { type: symlink, from: <repo-folder>, to: <repo-folder>/path/to/link }
+  - { type: composer-path, in: <repo>, dep: <sibling-repo> }
+  - { type: yarn-link, in: [<repo>, ...], dep: <sibling-package-repo> }
+env:
+  - source: { repo: <repo>, provides: '<value>' }
+    sinks:
+      - { repo: <repo>, key: ENV_KEY }
+```
 
-Adjust per repo (gap-fill, or when no setup doc exists):
+### Run order
 
-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:
-   - `yarn.lock` or `packageManager: "yarn@…"` → `yarn install`
-   - `pnpm-lock.yaml` → `pnpm install`
-   - `package-lock.json` → `npm install`
-   - no JS manifest → skip
-3. **PHP dependencies.** If `composer.json` is present and `composer` is installed → `composer install`. If composer is missing, note it and skip.
-4. **Env scaffold.** If `.env.example` exists and `.env` does not → copy `.env.example` to `.env` (never overwrite an existing `.env`). Tell the user the real values still need filling.
+1. **Discover** `.haus-workflow/localdev.yml` in the workspace root and each repo.
+2. **Resolve order** from the workspace `order` (repos not listed run last, in manifest order). No workspace file → manifest order.
+3. **Per repo, in order**, apply intent via the conventions:
+   - **`needs`** → provision each service in Docker if not already running, and wire its env vars. Confirm before creating/overwriting data.
+   - **`build`** → run it (honor any node version the repo's docs note).
+   - **`serve`** → for `via: herd` / PHP envs, install nothing — verify the dev's environment serves `web/`, and report the URL.
+   - **`seed`** → run it; **confirm first** if it's remote (SSH) or destructive (overwrites data).
+   - **`steps`** (escape hatch) → run in order, selecting `node:` per step, `optional:` failures continue, **confirming before any `remote:`/`destructive:` step** — every run, even on re-run.
+4. **Links** (workspace-owned, performed generically — do NOT call a repo's own `setup-dev-mode.sh`, which is deprecated):
+   - `symlink` → `ln -s <from> <to>`; replace an existing symlink, but never clobber a real directory without confirmation.
+   - `composer-path` → in `in`'s `composer.json`, set the `dep`'s require to `{ "type": "path", "url": "../<dep-folder>", "options": { "symlink": true } }`, then `composer update <vendor/dep>`.
+   - `yarn-link` → `yarn link` in the `dep` repo, then `yarn link <pkg-name>` in each `in` repo (read `<pkg-name>` from the dep's `package.json`).
+5. **Env:** for each workspace `env` entry, confirm the `source` is satisfiable, then upsert the value into each sink repo's `.env` under its `key` — **creating `.env` if it does not exist** (Step 3 scaffolds it, but don't assume). **If the write is blocked or fails, print the exact `KEY=value` lines for the user to paste** (decision D5). Real secrets (DB passwords, tokens) remain the user's to fill.
+6. **Report, then offer to start.** Give the per-repo summary, then **ask the user whether to start everything now.**
+   - **Yes** → start each repo in the workspace `order` (its `serve.start`, e.g. `yarn dev`; bring up any remaining foreground services), run any follow-ups (e.g. `wp sync-products sync`), then **print the live URLs** (each repo's `serve.url`).
+   - **No** → just print the ordered start commands + follow-ups as next steps; start nothing.
 
-If a repo's setup fails, report the error and **continue to the next repo** — don't abort the whole run.
+**Default is "ready to run" (D2):** the preparation — datastores up (`docker compose up -d`), DBs pulled, links, builds, env wired — always happens. Starting the **foreground** dev servers and the initial product sync happens **only if the user says yes** to the start prompt above; otherwise they're printed, not run.
 
-## Step 4 — Report
+## Step 5 — Report
 
-Summarise per repo: node version used, dependency install result, composer (if any), env seeded. Then list what's still manual:
+Summarise per repo (node, deps, localdev steps, links, env). Then **ask whether to start everything now**:
 
-- Fill in each `.env` with real values (cross-repo values must match — see the workspace's environment docs).
-- Start Docker services and dev servers in dependency order — see the workspace's local-development docs.
+- **Yes** → start the dev servers in workspace `order`, run any follow-ups, and **print the live URLs** so the user can open the running app.
+- **No** → print the ordered start commands + follow-ups instead, and start nothing.
 
-**Do not** start servers or run `docker compose up` / `yarn dev` — this command only prepares the repos.
+Never start the app without that explicit yes.

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

@@ -11,19 +11,12 @@ Do this in order:
    honestly ("I couldn't fully recognise this stack, so I'll apply the general
    workflow and security guidance").
 
-2. **Ask the guided questions as chat.** Ask the project's guided questions one
-   or two at a time, in plain language. Collect the answers.
-
-3. **Record answers.** Write the answers to `.haus-workflow/setup-answers.json`
-   as a flat `{ "question": "answer" }` object (the exact question strings as
-   keys). This is what lets setup proceed without re-prompting.
-
-4. **Apply the basics.** Run `haus apply --write`. Read the result. This installs
+2. **Apply the basics.** Run `haus apply --write`. Read the result. This installs
    the core guardrails and helpers — including the documentation skill haus uses
    in the next step.
 
-5. **Write the project docs.** Open and follow the instructions in
-   `.claude/skills/writing-documentation/SKILL.md`, which step 4 just installed.
+3. **Write the project docs.** Open and follow the instructions in
+   `.claude/skills/writing-documentation/SKILL.md`, which step 2 just installed.
    Following it, do a deep read of the project and:
    - write the project documentation (the `CLAUDE.md` body and `docs/` files).
      NEVER alter the `<!-- HAUS:BEGIN haus-imports … -->` … `<!-- HAUS:END … -->`
@@ -31,17 +24,17 @@ Do this in order:
    - write `.haus-workflow/deep-context.json` describing what the deep read found
      (roles, stacks, patterns the quick scan in step 1 could not see).
      If this step can't be completed for any reason, say so plainly and skip to
-     step 8 — setup still finishes correctly with the basics from step 4.
+     step 6 — setup still finishes correctly with the basics from step 2.
 
-6. **Re-check recommendations with the new understanding.** Run `haus recommend`.
+4. **Re-check recommendations with the new understanding.** Run `haus recommend`.
    It re-reads `deep-context.json` and may surface extra helpers matching what the
    deep read discovered. You MUST run this before the next apply — `haus apply`
    does not re-calculate recommendations on its own.
 
-7. **Apply the rest.** Run `haus apply --write` again. It only writes what changed,
-   so this just adds the newly-matched helpers from step 6.
+5. **Apply the rest.** Run `haus apply --write` again. It only writes what changed,
+   so this just adds the newly-matched helpers from step 4.
 
-8. **Confirm.** End with one plain-language line, for example:
+6. **Confirm.** End with one plain-language line, for example:
    "✅ Your project is configured — I wrote your project docs, added N guardrails
    and M coding helpers (K matched after reading your code in depth). Run
    `/haus-doctor` any time to re-check." Fill the numbers from the apply output.

package/library/global/skills/haus-workflow/SKILL.md

@@ -17,21 +17,20 @@ All-in-one entry point for the Haus AI workflow.
 
 Task names use an asymmetric scope convention. The **project:** namespace marks tasks that
 act on **this repo** (`./.claude`, `./.haus-workflow`) — type `project:` to see them all.
-The unprefixed verbs (`update`, `catalog`, `install`, `uninstall`) act on **this machine's
+The unprefixed verbs (`update`, `install`, `uninstall`) act on **this machine's
 haus install** (`~/.claude`, npm) — they manage the haus tool itself, like `npm install -g`.
 The short legacy aliases still work but the names below are canonical.
 
-| Task name (legacy aliases)                                        | Command                         | Scope   | What it does                                                                                                                |
-| ----------------------------------------------------------------- | ------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `project:init` (`setup`, `init`)                                  | _Setup procedure below_         | project | First-time setup of an **existing** repo: adds AI skills, commands, workflow + project docs                                 |
-| `project:clone [name]` (`clone`)                                  | _Clone procedure below_         | project | No name: clone a **workspace**'s repos from `repos.manifest.json`. With a `name`: find & clone one repo by name from GitHub |
-| `project:cloneandsetup [name]` (`cloneandsetup`)                  | _Clone & setup procedure below_ | project | Run `project:clone`, then set up each repo locally (node version, deps, `.env`)                                             |
-| `project:refresh` (`apply`, `refresh`, `claude-md`, `regenerate`) | `haus apply --write`            | project | Re-run setup / refresh `.claude/` context + regenerate root `CLAUDE.md` import block                                        |
-| `project:doctor` (`doctor`, `check`)                              | `haus doctor`                   | project | Check for install drift                                                                                                     |
-| `update` (`upgrade`)                                              | `haus update`                   | global  | Update npm package + catalog + `~/.claude/` (also refreshes this project)                                                   |
-| `catalog`                                                         | `haus update`                   | global  | Fetch latest catalog (same command as update)                                                                               |
-| `install` (`global`)                                              | `haus install`                  | global  | Seed `~/.claude/` with haus-owned files                                                                                     |
-| `uninstall`                                                       | `haus uninstall`                | global  | Remove all haus global files from `~/.claude/`                                                                              |
+| Task name (legacy aliases)                                        | Command                         | Scope   | What it does                                                                                                                                                                              |
+| ----------------------------------------------------------------- | ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project:init` (`setup`, `init`)                                  | _Setup procedure below_         | project | First-time setup of an **existing** repo: adds AI skills, commands, workflow + project docs                                                                                               |
+| `project:clone [name]` (`clone`)                                  | _Clone procedure below_         | project | No name: clone a **workspace**'s repos from `repos.manifest.json`. With a `name`: find & clone one repo by name from GitHub                                                               |
+| `project:cloneandsetup [name]` (`cloneandsetup`)                  | _Clone & setup procedure below_ | project | Run `project:clone`, then set up each repo for local dev — deps, databases, cross-repo links, and env — via each repo's `.haus-workflow/localdev.yml` (+ the workspace's order/links/env) |
+| `project:refresh` (`apply`, `refresh`, `claude-md`, `regenerate`) | `haus apply --write`            | project | Re-run setup / refresh `.claude/` context + regenerate root `CLAUDE.md` import block                                                                                                      |
+| `project:doctor` (`doctor`, `check`)                              | `haus doctor`                   | project | Check for install drift                                                                                                                                                                   |
+| `update` (`upgrade`)                                              | `haus update`                   | global  | Update npm package + catalog + `~/.claude/` (also refreshes this project)                                                                                                                 |
+| `install` (`global`)                                              | `haus install`                  | global  | Seed `~/.claude/` with haus-owned files                                                                                                                                                   |
+| `uninstall`                                                       | `haus uninstall`                | global  | Remove all haus global files from `~/.claude/`                                                                                                                                            |
 
 ## Step 1 — Determine the task
 
@@ -48,12 +47,10 @@ Options:
      (haus apply --write — re-runs setup, regenerates CLAUDE.md imports)
   3. [global] update — update haus package + catalog + global files
      (haus update — checks npm for new version, fetches catalog, refreshes ~/.claude/)
-  4. [global] catalog — fetch catalog updates only
-     (haus update — same command; pulls latest workflow templates and lockfile)
-  5. [project] project:clone [name] — clone repos
+  4. [project] project:clone [name] — clone repos
      (no name: clone a workspace from repos.manifest.json; with a name: find & clone one repo by name from GitHub)
-  6. [project] project:cloneandsetup [name] — clone repos, then set them up
-     (project:clone, then per-repo node version + dependency install + .env scaffold)
+  5. [project] project:cloneandsetup [name] — clone repos, then set them up for local dev
+     (project:clone, then per-repo deps + databases + cross-repo links + env from localdev.yml)
 ```
 
 Map the user's selection to the command from the alias table, then continue to Step 2.
@@ -74,7 +71,7 @@ After the command completes, follow the relevant post-run steps below.
 
 ### Setup (`project:init`)
 
-1. Open and follow `~/.claude/commands/haus-setup.md` — the installed `haus-setup` command (in some projects also `.claude/commands/haus-setup.md`). Run every step in order. It detects the stack, asks the guided questions, runs `haus apply --write` (scaffolding, skills, commands, rules, docs skill), writes the **project docs** (`CLAUDE.md` body + `docs/`) and `.haus-workflow/deep-context.json`, runs `haus recommend`, applies the newly-matched helpers, and confirms.
+1. Open and follow `~/.claude/commands/haus-setup.md` — the installed `haus-setup` command (in some projects also `.claude/commands/haus-setup.md`). Run every step in order. It detects the stack, runs `haus apply --write` (scaffolding, skills, commands, rules, docs skill), writes the **project docs** (`CLAUDE.md` body + `docs/`) and `.haus-workflow/deep-context.json`, runs `haus recommend`, applies the newly-matched helpers, and confirms.
 2. Then fill `.haus-workflow/workflow-config.md` — replace every placeholder (`TODO`, `n/a`, empty): test/lint/typecheck/build commands (check `package.json`), docs paths, validation library, pre-commit tool, highest-stakes logic (ask if unclear). Leave none.
 
 ### Clone (`project:clone`)

package/package.json

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