@massu/core 1.2.1 → 1.4.0-soak.0

package/dist/hooks/user-prompt.js

@@ -252,6 +252,7 @@ var FrameworkConfigSchema = z.object({
   ui: z.string().default("none"),
   languages: z.record(z.string(), LanguageFrameworkEntrySchema).optional()
 }).passthrough();
+var DetectedConfigSchema = z.object({}).passthrough().optional();
 var VerificationEntrySchema = z.object({
   type: z.string().optional(),
   test: z.string().optional(),
@@ -276,6 +277,31 @@ var DetectionConfigSchema = z.object({
   signal_weights: z.record(z.string(), z.number()).optional(),
   disable_builtin: z.boolean().optional()
 }).passthrough().optional();
+var WatchConfigSchema = z.object({
+  debounce_ms: z.number().int().positive().default(3e3),
+  storm_threshold: z.number().int().positive().default(50),
+  deep_storm_threshold: z.number().int().positive().default(500),
+  hard_timeout_ms: z.number().int().positive().default(3e5),
+  scope: z.enum(["paths", "full"]).default("paths"),
+  // Plan 3a hotfix 2026-05-02: refuse to start if the watch surface
+  // exceeds this many files. Prevents the misconfig pattern where
+  // `paths.source_dirs` includes `.` or otherwise expands to a 60K+
+  // file tree, producing 30-100% steady CPU. Override via
+  // `paths_full_root_opt_in: true` for users on small repos who genuinely
+  // need root-level watching.
+  max_watched_files: z.number().int().positive().default(1e4),
+  paths_full_root_opt_in: z.boolean().default(false)
+}).passthrough().optional();
+var LSPConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  servers: z.array(z.object({
+    language: z.string(),
+    command: z.string()
+  })).default([]),
+  autoDetect: z.object({
+    viaPortScan: z.boolean().default(false)
+  }).optional()
+}).passthrough();
 var RawConfigSchema = z.object({
   schema_version: z.union([z.literal(1), z.literal(2)]).default(1),
   project: z.object({
@@ -308,7 +334,13 @@ var RawConfigSchema = z.object({
   verification: VerificationConfigSchema,
   canonical_paths: CanonicalPathsSchema,
   verification_types: VerificationTypesSchema,
-  detection: DetectionConfigSchema
+  detection: DetectionConfigSchema,
+  // Plan #2: detector-owned per-language conventions (free-form passthrough)
+  detected: DetectedConfigSchema,
+  // Plan 3a: file-watcher daemon tunables
+  watch: WatchConfigSchema,
+  // Plan 3b Phase 4: optional LSP enrichment of AST adapter results.
+  lsp: LSPConfigSchema.optional()
 }).passthrough();
 var _config = null;
 var _projectRoot = null;
@@ -385,13 +417,16 @@ Hint: run \`massu config refresh\` to regenerate a valid config or fix the liste
       name: parsed.project.name,
       root: projectRoot
     },
+    // Spread `fw` first so zod-`.passthrough()` extras (e.g., `framework.swift`,
+    // `framework.python`) survive into the consumer-visible Config. Then override
+    // the v2-backcompat-mirrored router/orm/ui values. Without the spread, the
+    // variant-resolution `pickVariant` (install-commands.ts) cannot see the
+    // top-level passthrough language blocks.
     framework: {
-      type: fw.type,
+      ...fw,
       router,
       orm,
-      ui,
-      primary: fw.primary,
-      languages: fw.languages
+      ui
     },
     paths: parsed.paths,
     toolPrefix: parsed.toolPrefix,
@@ -412,7 +447,10 @@ Hint: run \`massu config refresh\` to regenerate a valid config or fix the liste
     verification: parsed.verification,
     canonical_paths: parsed.canonical_paths,
     verification_types: parsed.verification_types,
-    detection: parsed.detection
+    detection: parsed.detection,
+    detected: parsed.detected,
+    watch: parsed.watch,
+    lsp: parsed.lsp
   };
   if (!_config.cloud?.apiKey && process.env.MASSU_API_KEY) {
     _config.cloud = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massu/core",
-  "version": "1.2.1",
+  "version": "1.4.0-soak.0",
   "type": "module",
   "description": "AI Engineering Governance MCP Server - Session memory, knowledge system, feature registry, code intelligence, rule enforcement, tiered tooling (12 free / 72 total), 55+ workflow commands, 11 agents, 20+ patterns",
   "main": "src/server.ts",
@@ -11,20 +11,26 @@
     "start": "npx tsx src/server.ts",
     "test": "vitest run",
     "build": "tsc --noEmit && npm run build:cli && npm run build:hooks",
-    "build:cli": "esbuild --bundle --platform=node --format=esm --outfile=dist/cli.js src/cli.ts --external:better-sqlite3 --external:yaml --external:zod --banner:js='#!/usr/bin/env node\nimport{createRequire as __cr}from\"module\";const require=__cr(import.meta.url);'",
-    "build:hooks": "esbuild --bundle --platform=node --format=esm --outdir=dist/hooks src/hooks/*.ts --external:better-sqlite3 --external:yaml --external:zod --banner:js='import{createRequire as __cr}from\"module\";const require=__cr(import.meta.url);'",
-    "prepublishOnly": "bash ../../scripts/prepublish-check.sh && npm run build"
+    "build:cli": "esbuild --bundle --platform=node --format=esm --outfile=dist/cli.js src/cli.ts --external:better-sqlite3 --external:yaml --external:zod --external:chokidar --external:proper-lockfile --external:fsevents --banner:js='#!/usr/bin/env node\nimport{createRequire as __cr}from\"module\";const require=__cr(import.meta.url);'",
+    "build:hooks": "esbuild --bundle --platform=node --format=esm --outdir=dist/hooks src/hooks/*.ts --external:better-sqlite3 --external:yaml --external:zod --external:chokidar --external:proper-lockfile --external:fsevents --banner:js='import{createRequire as __cr}from\"module\";const require=__cr(import.meta.url);'",
+    "prepublishOnly": "bash ../../scripts/prepublish-check.sh && npm run build",
+    "bench:watch": "tsx test/perf/watch-benchmark.ts"
   },
   "dependencies": {
     "@clack/prompts": "^0.9.1",
     "better-sqlite3": "^12.6.2",
+    "chokidar": "^3.6.0",
     "fast-glob": "^3.3.0",
+    "proper-lockfile": "^4.1.2",
     "smol-toml": "^1.3.0",
+    "vscode-languageserver-protocol": "^3.17.5",
+    "web-tree-sitter": "^0.26.8",
     "yaml": "^2.4.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
+    "@types/proper-lockfile": "^4.1.4",
     "esbuild": "^0.27.3",
     "tsx": "^4.0.0",
     "typescript": "^5.4.0",

package/src/cli.ts

@@ -47,6 +47,23 @@ async function main(): Promise<void> {
       await runInstallCommands();
       break;
     }
+    case 'show-template': {
+      const { runShowTemplate } = await import('./commands/show-template.ts');
+      await runShowTemplate(args.slice(1));
+      break;
+    }
+    case 'watch': {
+      const { runWatch } = await import('./commands/watch.ts');
+      const result = await runWatch(args.slice(1));
+      process.exit(result.exitCode);
+      return;
+    }
+    case 'refresh-log': {
+      const { runRefreshLog } = await import('./commands/refresh-log.ts');
+      const result = await runRefreshLog(args.slice(1));
+      process.exit(result.exitCode);
+      return;
+    }
     case 'validate-config': {
       const { runValidateConfig } = await import('./commands/doctor.ts');
       await runValidateConfig();
@@ -80,7 +97,11 @@ async function handleConfigSubcommand(configArgs: string[]): Promise<void> {
   switch (sub) {
     case 'refresh': {
       const { runConfigRefresh } = await import('./commands/config-refresh.ts');
-      const result = await runConfigRefresh({ dryRun: flags.has('--dry-run') });
+      const result = await runConfigRefresh({
+        dryRun: flags.has('--dry-run'),
+        skipCommands: flags.has('--skip-commands'),
+        autoYes: flags.has('--yes') || flags.has('-y'),
+      });
       process.exit(result.exitCode);
       return;
     }
@@ -136,6 +157,9 @@ Commands:
   doctor            Check installation health
   install-hooks     Install/update Claude Code hooks
   install-commands  Install/update slash commands
+  show-template     Print the resolved variant of a bundled template (e.g. for diffs)
+  watch             Run the file-watcher daemon (auto-refresh on stack changes)
+  refresh-log [N]   Show the last N watcher auto-refresh events
   validate-config   Validate massu.config.yaml (alias: config validate)
   config <sub>      Config lifecycle: refresh | validate | upgrade | doctor | check-drift
 
@@ -158,7 +182,9 @@ massu config <subcommand>
 
 Subcommands:
   refresh       Re-run detection and apply changes to massu.config.yaml.
-                  --dry-run    Print diff and exit without writing.
+                  --dry-run        Print diff and exit without writing.
+                  --skip-commands  Don't re-template .claude/commands/.
+                  --yes, -y        Auto-apply without prompting (CI / scripts).
   validate      Validate massu.config.yaml (alias of \`massu validate-config\`).
   upgrade       Migrate a v1 config to schema_version=2.
                   --rollback   Restore from .bak file.

package/src/commands/config-refresh.ts

@@ -23,7 +23,7 @@
  *   2  unparseable massu.config.yaml
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, rmSync } from 'fs';
 import { resolve } from 'path';
 import { parse as parseYaml } from 'yaml';
 import { runDetection } from '../detect/index.ts';
@@ -31,6 +31,9 @@ import { computeFingerprint } from '../detect/drift.ts';
 import type { AnyConfig } from '../detect/migrate.ts';
 import { copyUnknownKeys, preserveNestedSubkeys } from '../detect/passthrough.ts';
 import { buildConfigFromDetection, renderConfigYaml, writeConfigAtomic } from './init.ts';
+import { installAll } from './install-commands.ts';
+import { resetConfig } from '../config.ts';
+import { withInstallLock } from '../lib/installLock.ts';
 
 const PRESERVED_FIELDS = [
   'rules',
@@ -56,6 +59,20 @@ export interface ConfigRefreshOptions {
   dryRun?: boolean;
   cwd?: string;
   silent?: boolean;
+  /**
+   * Plan #2 P4-001: when true, skip the post-refresh `installAll` call so
+   * `.claude/commands/` is NOT re-templated. Used by tests to keep file I/O
+   * hermetic, and by users who want config-only refresh behavior.
+   */
+  skipCommands?: boolean;
+  /**
+   * Plan 3a Phase 6: when true, bypass BOTH the non-TTY bail and the
+   * `@clack/prompts` confirm gate. The watcher daemon and `--yes` CLI flag
+   * use this to auto-apply detected changes. Combined with
+   * `skipCommands: true`, it lets the watcher delegate `installAll` to its
+   * own outer call (single install, single lock acquire — see iter-3 G3-A9).
+   */
+  autoYes?: boolean;
 }
 
 export interface ConfigRefreshResult {
@@ -293,26 +310,34 @@ export async function runConfigRefresh(opts: ConfigRefreshOptions = {}): Promise
     return { exitCode: 0, applied: false, dryRun: false, diff };
   }
 
-  // Interactive prompt; fall back to dry-run semantics when not a TTY.
-  if (!process.stdin.isTTY) {
-    log('Config diff (non-interactive; pass --dry-run to suppress this note or run interactively to apply):\n');
-    log(renderDiff(diff));
-    return {
-      exitCode: 0,
-      applied: false,
-      dryRun: false,
-      diff,
-      message: 'non-interactive shell; no changes written',
-    };
-  }
+  // Plan 3a Phase 6: when autoYes=true, skip BOTH the non-TTY bail and the
+  // confirm gate so the watcher (daemon stdin is detached) and the
+  // `--yes`/-y CLI flag actually apply changes.
+  if (!opts.autoYes) {
+    // Interactive prompt; fall back to dry-run semantics when not a TTY.
+    if (!process.stdin.isTTY) {
+      log('Config diff (non-interactive; pass --dry-run to suppress this note or run interactively to apply):\n');
+      log(renderDiff(diff));
+      return {
+        exitCode: 0,
+        applied: false,
+        dryRun: false,
+        diff,
+        message: 'non-interactive shell; no changes written',
+      };
+    }
 
-  log('Config diff:\n');
-  log(renderDiff(diff));
-  const { confirm } = await import('@clack/prompts');
-  const apply = await confirm({ message: 'Apply these changes to massu.config.yaml?' });
-  if (apply !== true) {
-    log('Aborted; no changes written.\n');
-    return { exitCode: 0, applied: false, dryRun: false, diff, message: 'aborted by user' };
+    log('Config diff:\n');
+    log(renderDiff(diff));
+    const { confirm } = await import('@clack/prompts');
+    const apply = await confirm({ message: 'Apply these changes to massu.config.yaml?' });
+    if (apply !== true) {
+      log('Aborted; no changes written.\n');
+      return { exitCode: 0, applied: false, dryRun: false, diff, message: 'aborted by user' };
+    }
+  } else {
+    log('Config diff (auto-applying via --yes / watcher):\n');
+    log(renderDiff(diff));
   }
 
   const yamlContent = renderConfigYaml(merged);
@@ -323,5 +348,48 @@ export async function runConfigRefresh(opts: ConfigRefreshOptions = {}): Promise
     return { exitCode: 2, applied: false, dryRun: false, diff, message };
   }
   log('Config refreshed.\n');
+
+  // Plan #2 P4-001: re-template `.claude/commands/` against the freshly
+  // written config so newly-detected stack changes get the right scaffolds.
+  // P4-003 (auto-delete half): if a stack is now declared and the empty-init
+  // placeholder still exists, remove it.
+  if (!opts.skipCommands) {
+    log('Will also re-template command files; pass --skip-commands to opt out.\n');
+    // Reset cached config so installAll reads the freshly-written YAML.
+    resetConfig();
+    try {
+      const installResult = withInstallLock(cwd, () => installAll(cwd));
+      const total =
+        installResult.totalInstalled +
+        installResult.totalUpdated +
+        installResult.totalSkipped +
+        installResult.totalKept;
+      log(`Re-templated ${total} command files (${installResult.totalInstalled} new, ${installResult.totalUpdated} updated).\n`);
+
+      // Auto-delete the empty-init placeholder if at least one stack-specific
+      // command was resolved this run (i.e., a non-zero install/update count).
+      const stackResolved =
+        installResult.totalInstalled > 0 || installResult.totalUpdated > 0;
+      if (stackResolved) {
+        const placeholderPath = resolve(installResult.claudeDir, 'commands', '_massu-needs-stack.md');
+        if (existsSync(placeholderPath)) {
+          try {
+            rmSync(placeholderPath, { force: true });
+            log('Removed _massu-needs-stack.md (stack now declared).\n');
+          } catch {
+            // Best-effort: never block refresh on placeholder cleanup.
+          }
+        }
+      }
+    } catch (err) {
+      // Don't fail the whole refresh if re-template breaks; the YAML was already written.
+      // InstallLockBusyError.message already follows plan §243 format —
+      // `installAll already running (PID=X) — try again in <N>s` — so we
+      // surface it verbatim rather than re-wrapping.
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!opts.silent) process.stderr.write(`Warning: re-template failed: ${msg}\n`);
+    }
+  }
+
   return { exitCode: 0, applied: true, dryRun: false, diff };
 }

package/src/commands/init.ts

@@ -26,14 +26,14 @@
  *   installHooks, buildHooksConfig, resolveHooksDir, initMemoryDir, runInit.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, chmodSync } from 'fs';
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, writeFileSync, writeSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, chmodSync } from 'fs';
 import { resolve, basename, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { homedir } from 'os';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 import { backfillMemoryFiles } from '../memory-file-ingest.ts';
 import { getConfig, resetConfig } from '../config.ts';
-import { installCommands } from './install-commands.ts';
+import { installAll } from './install-commands.ts';
 import {
   runDetection,
   type DetectionResult,
@@ -75,6 +75,11 @@ export interface InitOptions {
   template?: string;
   /** Skip hook/command/memory install side-effects. Used in tests. */
   skipSideEffects?: boolean;
+  /**
+   * Plan #2 P4-002: when true, skip the asset-install (commands / agents /
+   * patterns / etc). MCP register, hooks, and memory init still run.
+   */
+  skipCommands?: boolean;
   /** Override cwd (tests). */
   cwd?: string;
   /** Suppress console output. */
@@ -508,6 +513,14 @@ export function buildConfigFromDetection(
   // P5-002: stamp a stack fingerprint so session-start can detect drift later.
   config.detection = { fingerprint: computeFingerprint(detection) };
 
+  // Plan #2 P3-003: emit detector-owned `detected:` block (per-language
+  // conventions sampled from the codebase). Only present when the introspector
+  // ran (i.e., not skipped by the session-start hook). Detector-owned →
+  // refreshed on every `init`/`config refresh`, NOT in PRESERVED_FIELDS.
+  if (detection.detected && Object.keys(detection.detected).length > 0) {
+    config.detected = detection.detected;
+  }
+
   // Preserve legacy `python` block for v1 consumers (domain-enforcer, etc.).
   // Per Phase 0 P1-009 (b): python legacy config coexists with languages.python.
   if (languages.includes('python')) {
@@ -576,7 +589,31 @@ export function writeConfigAtomic(
   }
 
   try {
-    writeFileSync(tmpPath, content, { encoding: 'utf-8', mode: 0o644 });
+    // Iter-8 fix: ensure the parent directory exists. POSIX `rename(2)`
+    // requires the target's parent to exist; otherwise the rename fails
+    // with ENOENT and we leak the tmp. The watcher's auto-refresh path
+    // never hits this (the configPath is always inside an existing repo
+    // with massu.config.yaml already there), but `runInit` on a fresh
+    // path under a non-existent parent would fall over before this line.
+    mkdirSync(dirname(configPath), { recursive: true });
+
+    // Iter-7 fix: write tmp via openSync + writeSync + fsyncSync + closeSync
+    // so the data hits the platter BEFORE renameSync. This matches
+    // `writeStateAtomic` (watch/state.ts) and the spec doc claim that the
+    // 3a watcher's atomic-rename guarantees universally cover all writes
+    // touched during a refresh cycle. Without fsync, on certain filesystems
+    // (xfs, ext4 `data=writeback`) the rename can land before data, leaving
+    // a zero-byte config on power-loss / SIGKILL between writeFileSync and
+    // renameSync — a gap the watcher daemon makes more reachable since
+    // refresh writes happen unattended every quiescence window.
+    const fd = openSync(tmpPath, 'w', 0o644);
+    try {
+      const buf = Buffer.from(content, 'utf-8');
+      writeSync(fd, buf, 0, buf.length, 0);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
 
     // Validate YAML parses.
     const parsed = yamlParse(content);
@@ -998,6 +1035,7 @@ export function parseInitArgs(argv: string[]): ParseInitArgsResult {
     const a = argv[i];
     if (a === '--ci') opts.ci = true;
     else if (a === '--force') opts.force = true;
+    else if (a === '--skip-commands') opts.skipCommands = true;
     else if (a === '--help' || a === '-h') opts.help = true;
     else if (a === '--template') {
       const next = argv[i + 1];
@@ -1025,6 +1063,8 @@ Options:
   --force             Overwrite existing massu.config.yaml without prompting.
   --template <name>   Skip detection and scaffold from a greenfield template.
                       Templates: ${TEMPLATE_NAMES.join(', ')}
+  --skip-commands     Skip the asset install (.claude/commands etc).
+                      MCP register, hooks, and memory init still run.
   --help, -h          Show this help message
 
 Examples:
@@ -1131,7 +1171,7 @@ export async function runInit(argv?: string[], overrides?: InitOptions): Promise
     }
     log(`  Installed template '${opts.template}' → massu.config.yaml`);
     if (!opts.skipSideEffects) {
-      installSideEffects(projectRoot, log);
+      installSideEffects(projectRoot, log, opts.skipCommands);
     }
     return;
   }
@@ -1139,11 +1179,20 @@ export async function runInit(argv?: string[], overrides?: InitOptions): Promise
   // Branch 2: detection-driven path (P3-001, P3-002)
   const detection = await runDetection(projectRoot);
   const languageCount = new Set(detection.manifests.map((m) => m.language)).size;
-  if (detection.manifests.length === 0 && languageCount === 0) {
-    errLog('error: no languages detected in this directory');
-    errLog('       (no package.json, pyproject.toml, Cargo.toml, etc.)');
-    errLog('       pass --template <name> to scaffold a new project, or cd into a repo with a manifest');
-    throw new Error('No languages detected');
+  const emptyStack = detection.manifests.length === 0 && languageCount === 0;
+  if (emptyStack) {
+    if (opts.ci && !opts.force) {
+      // Plan #2 §"Answer to install-before-stack": interactive `massu init` in
+      // an empty repo is supported. CI mode keeps the strict guard (no
+      // accidental empty-stack configs in pipelines) — pass --force in CI to
+      // explicitly opt into empty-stack init.
+      errLog('error: no languages detected in this directory');
+      errLog('       (no package.json, pyproject.toml, Cargo.toml, etc.)');
+      errLog('       pass --template <name>, --force, or run interactively for empty-stack init');
+      throw new Error('No languages detected');
+    }
+    log('  No languages detected — proceeding with empty-stack init.');
+    log('  After adding a manifest (package.json, pyproject.toml, ...) run: npx massu config refresh');
   }
 
   // Emit warnings to stderr for ambiguous / malformed detection.
@@ -1186,8 +1235,10 @@ export async function runInit(argv?: string[], overrides?: InitOptions): Promise
     throw new Error(writeRes.error ?? 'atomic write failed');
   }
 
-  // Post-write validation; rollback on failure.
-  const validation = validateWrittenConfig(configPath, projectRoot);
+  // Post-write validation; rollback on failure. Skip filesystem-existence
+  // checks for empty-stack init (no manifests = `paths.source` defaults to
+  // 'src' which legitimately doesn't exist in an empty dir).
+  const validation = validateWrittenConfig(configPath, projectRoot, !emptyStack);
   if (validation !== null) {
     try { rmSync(configPath, { force: true }); } catch { /* ignore */ }
     errLog(`error: generated config failed validation: ${validation}`);
@@ -1198,12 +1249,17 @@ export async function runInit(argv?: string[], overrides?: InitOptions): Promise
   log('  Created massu.config.yaml (schema_version: 2)');
 
   if (!opts.skipSideEffects) {
-    installSideEffects(projectRoot, log);
+    installSideEffects(projectRoot, log, opts.skipCommands, emptyStack);
   }
 }
 
 /** Shared side-effect steps (MCP register + hooks + commands + memory + backfill). */
-function installSideEffects(projectRoot: string, log: (s: string) => void): void {
+function installSideEffects(
+  projectRoot: string,
+  log: (s: string) => void,
+  skipCommands: boolean = false,
+  emptyStack: boolean = false,
+): void {
   // MCP register
   const mcpRegistered = registerMcpServer(projectRoot);
   if (mcpRegistered) {
@@ -1216,17 +1272,68 @@ function installSideEffects(projectRoot: string, log: (s: string) => void): void
   const { count: hooksCount } = installHooks(projectRoot);
   log(`  Installed ${hooksCount} hooks in .claude/settings.local.json`);
 
-  // Commands
-  try {
-    const cmdResult = installCommands(projectRoot);
-    const cmdTotal = cmdResult.installed + cmdResult.updated + cmdResult.skipped;
-    if (cmdResult.installed > 0 || cmdResult.updated > 0) {
-      log(`  Installed ${cmdTotal} slash commands (${cmdResult.installed} new, ${cmdResult.updated} updated)`);
-    } else if (cmdTotal > 0) {
-      log(`  ${cmdTotal} slash commands already up to date`);
+  // Plan #2 P4-002: install all asset types (commands, agents, patterns,
+  // protocols, reference) via installAll — replaces the legacy
+  // installCommands() that only handled commands. Skipped when --skip-commands.
+  // Plan #2 P4-003: when no stack-specific commands resolved (empty-stack init),
+  // write a single `_massu-needs-stack.md` placeholder so consumers know to
+  // run `config refresh` after adding their first manifest.
+  if (!skipCommands) {
+    try {
+      const cmdResult = installAll(projectRoot);
+      const cmdTotal =
+        cmdResult.totalInstalled +
+        cmdResult.totalUpdated +
+        cmdResult.totalSkipped +
+        cmdResult.totalKept;
+      if (cmdResult.totalInstalled > 0 || cmdResult.totalUpdated > 0) {
+        log(`  Installed ${cmdTotal} project assets (${cmdResult.totalInstalled} new, ${cmdResult.totalUpdated} updated)`);
+      } else if (cmdTotal > 0) {
+        log(`  ${cmdTotal} project assets already up to date`);
+      }
+
+      // Empty-stack init detection: when caller signals an empty stack OR
+      // when NO commands resolved at all, drop the placeholder so the user
+      // understands the next step. The explicit `emptyStack` signal handles
+      // the t=0 case (zero manifests detected) where generic-default commands
+      // still install but no stack-specific scaffolds match the consumer.
+      const commandStats = cmdResult.assets.commands;
+      const stackResolved = !emptyStack && commandStats &&
+        (commandStats.installed > 0 || commandStats.updated > 0 || commandStats.kept > 0);
+      if (!stackResolved) {
+        const placeholderPath = resolve(cmdResult.claudeDir, 'commands', '_massu-needs-stack.md');
+        if (!existsSync(placeholderPath)) {
+          const placeholderBody = [
+            '# Massu — stack not yet detected',
+            '',
+            'Your stack hasn\'t been detected yet. Most slash commands ship as language-specific',
+            'variants (e.g., `massu-scaffold-router.python-fastapi.md` for FastAPI projects).',
+            'When detection finds a manifest, the right variants get installed automatically.',
+            '',
+            'After you add your first manifest (`package.json`, `pyproject.toml`, `Cargo.toml`,',
+            'etc.) run:',
+            '',
+            '```bash',
+            'npx massu config refresh',
+            '```',
+            '',
+            'This file will be auto-removed on the first refresh that resolves at least one',
+            'stack-specific command.',
+            '',
+            '— Massu',
+          ].join('\n');
+          try {
+            mkdirSync(resolve(cmdResult.claudeDir, 'commands'), { recursive: true });
+            writeFileSync(placeholderPath, placeholderBody, 'utf-8');
+            log('  Wrote _massu-needs-stack.md placeholder (no stack detected yet)');
+          } catch {
+            // Best-effort.
+          }
+        }
+      }
+    } catch {
+      // Best-effort — don't fail init if assets can't be resolved.
     }
-  } catch {
-    // Best-effort — don't fail init if assets can't be resolved.
   }
 
   // Memory dir