@axiomatic-labs/claudeflow 2.32.22 → 2.33.0

package/lib/install.js

@@ -1,1406 +1,168 @@
 const fs = require('fs');
 const path = require('path');
-const { execSync, execFileSync } = require('child_process');
+const os = require('os');
+const { execSync } = require('child_process');
 const { requireAuth } = require('./auth.js');
 const { getLatestRelease, downloadReleaseAsset } = require('./download.js');
 const { writeLocalVersion, readLocalVersion } = require('./version.js');
-const { applyOverridesToFile: applyHookOverridesToFile } = require('./hook-overrides.js');
 const ui = require('./ui.js');
 
-// Template skills are shipped inside the ZIP. Copy every managed
-// claudeflow-* skill from the release while preserving any user-generated
-// skills that are not part of the shipped asset.
-const TEMPLATE_MANAGED_MANIFEST = path.join('.claudeflow', 'config', 'template-managed-manifest.json');
-const REQUIRED_TEMPLATE_RULES = [];
-const LEGACY_TEMPLATE_RULES = ['claudeflow-implementation.md', 'example-rules.md'];
-const SHARED_APPEND_PROMPT_TEMPLATE = path.join('.claudeflow', 'templates', 'claudeflow-core-system-prompt.md');
-const SHARED_APPEND_PROMPT_OUTPUT = 'append-system-prompt.md';
-const DEFAULT_CLAUDE_MD_TEMPLATE = path.join('.claudeflow', 'templates', 'claudeflow-default-claude-md.md');
-const DEFAULT_CLAUDE_MD_OUTPUT = 'CLAUDE.md';
-const TEMPLATE_MANAGED_SETTINGS_KEYS = ['$schema', 'enabledMcpjsonServers', 'env', 'permissions', 'hooks'];
-const SERENA_REPO = 'git+https://github.com/oraios/serena';
-const TEMPLATE_SEEDED_SETTINGS_KEYS = new Set(['statusLine']);
+// claudeflow installs a small, namespaced footprint. Most of it is self-contained files that are simply
+// PLACED (playbooks, scripts, skills) — those can't conflict with the user's project. The only things
+// that need a MERGE (never a clobber) are .claude/settings.json (register our hooks alongside theirs)
+// and CLAUDE.md (append our guidance block). That merge lives here, in Node, so install works on every
+// platform with no shell dependency. The GitHub auth gate (auth.js/download.js) is untouched.
 
-async function run() {
-  const current = readLocalVersion();
-  const isUpdate = !!current;
-  let copiedTemplateSkillCount = 0;
-  let staleRemovedCount = 0;
-  let managedPathCount = 0;
-
-  ui.banner(current || undefined);
-
-  ui.step('Authenticating with GitHub...');
-  const token = await requireAuth();
-
-  ui.step('Fetching latest release...');
-  const release = await getLatestRelease(token);
-  const version = release.tag_name;
-
-  // Find the ZIP asset
-  const asset = release.assets.find((a) => a.name.endsWith('.zip'));
-  if (!asset) {
-    ui.error('No ZIP asset found in the latest release.');
-    process.exit(1);
-  }
-
-  ui.step(`Downloading ${version}...`);
-  const zipBuffer = await downloadReleaseAsset(asset, token);
-
-  // Write ZIP to temp file and extract to a temp directory
-  const tmpZip = path.join(require('os').tmpdir(), `claudeflow-${Date.now()}.zip`);
-  const tmpExtract = path.join(require('os').tmpdir(), `claudeflow-extract-${Date.now()}`);
-  fs.writeFileSync(tmpZip, zipBuffer);
-  fs.mkdirSync(tmpExtract, { recursive: true });
-
-  const cwd = process.cwd();
-
-  try {
-    ui.step('Extracting template files...');
-    // -qq silences unzip's per-file `inflating:` output, which on a large
-    // ZIP exceeds execSync's default 1MB maxBuffer and triggers ENOBUFS.
-    // maxBuffer override is belt-and-suspenders for future growth.
-    execSync(`unzip -qq -o "${tmpZip}" -d "${tmpExtract}"`, {
-      stdio: 'pipe',
-      maxBuffer: 50 * 1024 * 1024,
-    });
-    const srcClaudeflow = path.join(tmpExtract, '.claudeflow');
-    // v2.13.148+: mode is per-build, not per-project. There are no more
-    // variants/{boost,normal} directories — the template ships a single
-    // .claude/ tree, and claudeflow-build asks "fast or normal?" at each
-    // invocation. So we source directly from the zip's .claude/ root.
-    const srcClaude = path.join(tmpExtract, '.claude');
-    const nextManagedPaths = collectManagedPathsFromRelease(tmpExtract);
-    const previousManifest = readTemplateManagedManifest(cwd);
-    const previousManagedPaths = previousManifest
-      ? previousManifest.managedPaths
-      : collectLegacyManagedPathsFromDisk(cwd);
-
-    if (isUpdate && !previousManifest) {
-      ui.info('No template-managed manifest found. Running aggressive legacy prune for managed paths.');
-    }
-
-    const staleManagedPaths = [...previousManagedPaths].filter((relPath) => !nextManagedPaths.has(relPath));
-    staleRemovedCount = pruneStaleManagedPaths(cwd, staleManagedPaths);
-
-    // Merge settings.json so template-managed keys refresh on update while
-    // preserving user customizations like custom statusLine commands.
-    const srcSettings = path.join(srcClaude, 'settings.json');
-    const dstSettings = path.join(cwd, '.claude', 'settings.json');
-    fs.mkdirSync(path.join(cwd, '.claude'), { recursive: true });
-    if (fs.existsSync(srcSettings)) {
-      syncClaudeSettings(srcSettings, dstSettings);
-      // Settings.json now ships with every hook command wrapped through
-      // run-with-override.js. The wrapper consults user-hook-overrides.json
-      // at invocation time, so toggles persist without any settings rewrite.
-    }
-
-    // Upsert playwright entry in .mcp.json with project-specific CDP port.
-    // IMPORTANT: read existing .mcp.json first and merge — never overwrite
-    // wholesale. Users may have custom MCP servers (claude-in-chrome, Linear,
-    // GitHub, etc) that must be preserved across install/update runs. Only
-    // the three template-managed entries (playwright, serena, context7) are
-    // allowed to be mutated by the installer.
-    const cdpHash = require('crypto').createHash('sha1').update(cwd).digest();
-    const cdpPort = 9200 + (cdpHash.readUInt16BE(2) % 100);
-    const mcpPath = path.join(cwd, '.mcp.json');
-    let mcpConfig = { mcpServers: {} };
-    try {
-      const existing = fs.readFileSync(mcpPath, 'utf8');
-      mcpConfig = JSON.parse(existing);
-      if (!mcpConfig.mcpServers || typeof mcpConfig.mcpServers !== 'object') {
-        mcpConfig.mcpServers = {};
-      }
-    } catch {
-      // File doesn't exist or is invalid JSON — start fresh with empty servers
-    }
-    // Spread first so user-added fields (env with API keys, cwd, etc.) survive.
-    // Only command/args are CLI-canonical and get overridden.
-    mcpConfig.mcpServers.playwright = {
-      ...mcpConfig.mcpServers.playwright,
-      command: "npx",
-      args: [
-        "@playwright/mcp@latest",
-        "--cdp-endpoint", `http://127.0.0.1:${cdpPort}`,
-        "--caps", "vision,devtools",
-      ],
-    };
-    fs.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + '\n');
-
-    // Copy all template-managed skills from the ZIP, including subskills.
-    const srcSkills = path.join(srcClaude, 'skills');
-    const dstSkills = path.join(cwd, '.claude', 'skills');
-    if (fs.existsSync(srcSkills)) {
-      fs.mkdirSync(dstSkills, { recursive: true });
-      const skillDirs = fs.readdirSync(srcSkills, { withFileTypes: true });
-      for (const entry of skillDirs) {
-        if (entry.isDirectory() && entry.name.startsWith('claudeflow-')) {
-          copyDirSync(path.join(srcSkills, entry.name), path.join(dstSkills, entry.name));
-          copiedTemplateSkillCount += 1;
-        }
-      }
-    }
-
-    // Copy all hooks
-    const srcHooks = path.join(srcClaude, 'hooks');
-    const dstHooks = path.join(cwd, '.claude', 'hooks');
-    if (fs.existsSync(srcHooks)) {
-      copyDirSync(srcHooks, dstHooks);
-    }
-
-    // Copy shared runtime scripts used by skills and hooks
-    const srcRuntime = path.join(srcClaudeflow, 'runtime');
-    const dstRuntime = path.join(cwd, '.claudeflow', 'runtime');
-    if (fs.existsSync(srcRuntime)) {
-      copyDirSync(srcRuntime, dstRuntime);
-    }
-
-    // Copy canonical template-managed assets used by init/update composition
-    const srcTemplates = path.join(srcClaudeflow, 'templates');
-    const dstTemplates = path.join(cwd, '.claudeflow', 'templates');
-    if (fs.existsSync(srcTemplates)) {
-      copyDirSync(srcTemplates, dstTemplates);
-    }
-
-    // Copy v2 orchestrator playbook layer (foundation/methodologies/domain/
-    // ui-ux/routing). Required for claudeflow-build / -test / -review skills
-    // to @-mention. Without this, those skills' @.claudeflow/playbooks/...
-    // refs point to non-existent files.
-    const srcPlaybooks = path.join(srcClaudeflow, 'playbooks');
-    const dstPlaybooks = path.join(cwd, '.claudeflow', 'playbooks');
-    if (fs.existsSync(srcPlaybooks)) {
-      copyDirSync(srcPlaybooks, dstPlaybooks);
-    }
-
-    materializeSharedAppendPrompt(cwd);
-    ensureDefaultClaudeMdRules(cwd);
-    propagateTemplateRules(cwd, srcTemplates);
-    // v2: scaffold the 8 system rules (3 always-loaded + 5 path-scoped)
-    // using scaffold-system-rule.js. When setup-context.json exists
-    // (brownfield), it derives framework-aware `paths` frontmatter. When
-    // setup-context.json is absent (greenfield), it falls back to the
-    // template's broad-default paths. No-clobber preserved — existing
-    // user customizations win.
-    propagateSystemRulesViaScaffold(cwd);
-    // After CLAUDE.md exists, append the claudeflow addendum (the load-bearing
-    // rule "all code changes flow through /claudeflow-build" + mode-aware
-    // mandates). Idempotent: runs every install/update; the block lives
-    // between <!-- claudeflow:boost-mode:BEGIN/END --> markers.
-    syncBoostAddendumOnInstall(cwd);
-
-    // Copy template agents (only template-managed, preserve user agents)
-    const srcAgents = path.join(srcClaude, 'agents');
-    const dstAgents = path.join(cwd, '.claude', 'agents');
-    if (fs.existsSync(srcAgents)) {
-      fs.mkdirSync(dstAgents, { recursive: true });
-      const agentFiles = fs.readdirSync(srcAgents);
-      for (const file of agentFiles) {
-        const name = file.replace(/\.md$/, '');
-        if (isTemplateManagedAgent(name)) {
-          fs.copyFileSync(path.join(srcAgents, file), path.join(dstAgents, file));
-        }
-      }
-    }
-
-    // Remove previously template-seeded base rules. Project memory now comes
-    // from setup-context, generated project rules, and root CLAUDE.md.
-    pruneLegacyTemplateRules(cwd);
-    // v2 cleanup: remove v1 build-orchestrator artifacts (phases/, references/,
-    // and v1-only enforcement hooks). These were template-managed in earlier
-    // versions but aren't in the v2 manifest, so install.js's stale-removal
-    // doesn't always identify them. Be explicit.
-    pruneLegacyV1BuildArtifacts(cwd);
-
-    // Copy commands
-    const srcCommands = path.join(srcClaude, 'commands');
-    const dstCommands = path.join(cwd, '.claude', 'commands');
-    if (fs.existsSync(srcCommands)) {
-      copyDirSync(srcCommands, dstCommands);
-    }
-
-    // Copy all docs
-    const srcDocs = path.join(srcClaudeflow, 'docs');
-    const dstDocs = path.join(cwd, '.claudeflow', 'docs');
-    if (fs.existsSync(srcDocs)) {
-      copyDirSync(srcDocs, dstDocs);
-    }
-
-    // Ensure .claudeflow/tmp exists and copy bundled scripts
-    fs.mkdirSync(path.join(cwd, '.claudeflow', 'tmp'), { recursive: true });
-    const srcTmp = path.join(srcClaudeflow, 'tmp');
-    if (fs.existsSync(srcTmp)) {
-      const tmpFiles = fs.readdirSync(srcTmp);
-      for (const file of tmpFiles) {
-        const srcFile = path.join(srcTmp, file);
-        const dstFile = path.join(cwd, '.claudeflow', 'tmp', file);
-        if (fs.statSync(srcFile).isFile()) {
-          fs.copyFileSync(srcFile, dstFile);
-        }
-      }
-    }
-
-    // v2.13.148+: variants/ and active-mode were removed. Mode (fast/normal)
-    // is now per-build, persisted in workflow-state.runs[run_id].top_level.mode.
-    // The user picks the mode via AskUserQuestion at every claudeflow-build
-    // invocation. No global project-level mode marker.
-
-    // Write version file
-    writeLocalVersion(version);
-    nextManagedPaths.add(normalizeRelativePath(path.join('.claudeflow', 'version')));
-
-    // Persist managed path manifest for deterministic stale-file pruning on update
-    writeTemplateManagedManifest(cwd, version, nextManagedPaths);
-    managedPathCount = nextManagedPaths.size;
-
-  } finally {
-    fs.unlinkSync(tmpZip);
-    fs.rmSync(tmpExtract, { recursive: true, force: true });
-  }
-
-  // install does NOT touch running processes — it only writes template files.
-  // The observer daemon / dev servers are never killed here; a fresh daemon
-  // with the updated runtime code is picked up on the next session, or via the
-  // /claudeflow-observer-reset skill. Killing the daemon on update used to cascade
-  // into tearing down the user's dev servers, so update stays purely a file copy.
-
-  // Install analysis tools (ast-grep + Serena MCP)
-  installAnalysisTools();
-
-  // Count installed items
-  const skillsDir = path.join(cwd, '.claude', 'skills');
-  let skillCount = 0;
-  try {
-    skillCount = fs.readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).length;
-  } catch {}
-
-  const hooksDir = path.join(cwd, '.claude', 'hooks');
-  let hookCount = 0;
-  try {
-    hookCount = fs.readdirSync(hooksDir, { withFileTypes: true }).filter((e) => e.isDirectory()).length;
-  } catch {}
-
-  const docsDir = path.join(cwd, '.claudeflow', 'docs');
-  let docCount = 0;
-  try {
-    docCount = fs.readdirSync(docsDir).filter((f) => !f.startsWith('.')).length;
-  } catch {}
-
-  console.log('');
-  if (isUpdate) {
-    ui.success(`${skillCount} skills (${copiedTemplateSkillCount} template skills updated, user skills preserved)`);
-    ui.success(`${hookCount} hooks updated`);
-    ui.success(`${docCount} docs updated`);
-    ui.success(`${staleRemovedCount} stale template-managed files removed`);
-    ui.success(`Template-managed manifest updated (${managedPathCount} paths)`);
-    ui.info('Default Claude Code status line is seeded when missing. Existing custom statusLine settings are preserved on update and can be overridden in .claude/settings.local.json.');
-
-    if (current === version) {
-      ui.done(`Claudeflow ${version} reinstalled.`);
-    } else {
-      ui.done(`Claudeflow updated: ${current} → ${version}`);
-    }
-
-    // Warn if setup-context.json is missing (legacy install or never-init).
-    // The orchestrator and skills assume this file exists; without it they
-    // fall back to inferring from CLAUDE.md + package.json, which works but
-    // is less precise. The user can regenerate it via /claudeflow-init or
-    // /claudeflow-update inside Claude Code.
-    const setupContextPath = path.join(cwd, '.claudeflow', 'config', 'setup-context.json');
-    if (!fs.existsSync(setupContextPath)) {
-      ui.info(`Note: .claudeflow/config/setup-context.json is missing. Builds will fall back to inferring stack from CLAUDE.md + package.json. To regenerate the canonical setup-context, run /claudeflow-init or /claudeflow-update inside Claude Code.`);
-    }
-
-  } else {
-    ui.success(`${skillCount} skills installed`);
-    ui.success(`${hookCount} hooks installed`);
-    ui.success(`${docCount} docs installed`);
-    ui.success(`Template-managed manifest written (${managedPathCount} paths)`);
-    ui.info('Default Claude Code status line installed. Override it in .claude/settings.json or .claude/settings.local.json.');
-
-    ui.done(`Claudeflow ${version} installed.`);
-  }
-
-  // v2.14.43 Gap #7: warn if enforcement is disabled. Lives outside the
-  // update/fresh-install branches so it fires in both flows (a user can
-  // start with enforcement on, then later toggle it off via panel, and
-  // a subsequent fresh install in the same dir would miss the warning if
-  // the check sat inside the update branch only).
-  try {
-    const overridesPath = path.join(cwd, '.claudeflow', 'config', 'user-hook-overrides.json');
-    if (fs.existsSync(overridesPath)) {
-      const overrides = JSON.parse(fs.readFileSync(overridesPath, 'utf8'));
-      if (overrides && overrides.enforcementDisabled === true) {
-        ui.info(`⚠️  ENFORCEMENT IS DISABLED — your .claudeflow/config/user-hook-overrides.json has "enforcementDisabled": true. All Claudeflow PreToolUse strict gates (phase tasks, plan agents, methodology, marker) are silenced. To re-enable: run \`claudeflow panel\` and toggle enforcement on, or edit user-hook-overrides.json to set "enforcementDisabled": false.`);
-      }
-    }
-  } catch {
-    // Best-effort: malformed JSON should not block install.
-  }
-
-  // Ensure the `claudeflow` shell command is available and matches the
-  // just-installed template version. Runs for both fresh installs and
-  // updates — the shell command is independent of the project template
-  // and needs to stay in sync either way.
-  const cliStatus = ensureGlobalCli(version);
-
-  // Getting started guide with project detection
-  showGettingStarted(cwd, cliStatus);
-}
-
-function ensureGlobalCli(version) {
-  // Returns { available: boolean, autoInstalled: boolean, upgraded: boolean, fromVersion?: string, error?: string }
-  // `commandExists('claudeflow')` yields a false positive when install.js runs
-  // under `npx @axiomatic-labs/claudeflow ...` — npx injects its own
-  // `node_modules/.bin` into PATH and the subprocess sees the self-referential
-  // binary even though nothing is installed globally. Cross-check against
-  // `npm ls -g` (which never reports the npx cache) so the auto-installer
-  // does not skip a missing global.
-  const installedVersion = readGlobalCliVersion();
-  const present = Boolean(installedVersion);
-  const needsUpgrade = present && installedVersion !== version;
-
-  if (present && !needsUpgrade) {
-    return { available: true, autoInstalled: false, upgraded: false };
-  }
-
-  if (process.env.CLAUDEFLOW_SKIP_GLOBAL_INSTALL === '1') {
-    return {
-      available: present,
-      autoInstalled: false,
-      upgraded: false,
-      fromVersion: installedVersion || undefined,
-      error: 'skipped',
-    };
-  }
-
-  console.log('');
-  if (needsUpgrade) {
-    console.log(
-      `  ${ui.DIM}Upgrading global claudeflow CLI from ${installedVersion} to ${version}...${ui.RESET}`
-    );
-  } else {
-    console.log(
-      `  ${ui.DIM}Installing claudeflow CLI globally so it is available as a shell command...${ui.RESET}`
-    );
-  }
-  try {
-    execSync(`npm install -g @axiomatic-labs/claudeflow@${version}`, {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      timeout: 120000,
-    });
-    // Verify with `npm ls -g` rather than `command -v`. Under npx, the
-    // subprocess PATH still contains the npx cache, so `command -v`
-    // would report true even if the global install wrote to a prefix
-    // that the user's shell cannot see.
-    const afterVersion = readGlobalCliVersion();
-    if (afterVersion) {
-      return {
-        available: true,
-        autoInstalled: !needsUpgrade,
-        upgraded: needsUpgrade,
-        fromVersion: installedVersion || undefined,
-        shellPath: verifyShellCanFindCli(),
-      };
-    }
-    return {
-      available: false,
-      autoInstalled: false,
-      upgraded: false,
-      error: 'installed but `npm ls -g` cannot see it — verify `npm config get prefix` is on $PATH',
-    };
-  } catch (err) {
-    const msg = err?.stderr?.toString?.() || err?.message || String(err);
-    return {
-      available: present,
-      autoInstalled: false,
-      upgraded: false,
-      fromVersion: installedVersion || undefined,
-      error: msg.split('\n')[0],
-    };
-  }
-}
-
-function readGlobalCliVersion() {
-  try {
-    const raw = execSync('npm ls -g --json --depth=0 @axiomatic-labs/claudeflow', {
-      stdio: ['ignore', 'pipe', 'ignore'],
-      timeout: 10000,
-    }).toString();
-    const parsed = JSON.parse(raw);
-    const v = parsed?.dependencies?.['@axiomatic-labs/claudeflow']?.version;
-    return typeof v === 'string' ? v : null;
-  } catch {
-    return null;
-  }
-}
-
-// Returns { ok: boolean | null, binPath?: string, shellRcFile?: string,
-//   nvmDetected?: boolean, suggestedFix?: string }
-//
-// Distinguishes "package installed globally" from "package findable from
-// the user's interactive shell". Catches the common nvm-lazy-load setup
-// where `npm install -g` writes a binary the shell can't see until nvm
-// is sourced — typically discovered only when the user opens a fresh
-// terminal and types `claudeflow` and gets "command not found".
-function verifyShellCanFindCli() {
-  // Skip on Windows; lazy-load + nvm-windows behave differently and the
-  // login-shell trick below is brittle there.
-  if (process.platform === 'win32') return { ok: null };
-
-  const shellPath = process.env.SHELL;
-  if (!shellPath || !fs.existsSync(shellPath)) return { ok: null };
-
-  // Run a non-inherited interactive login shell — that's the closest
-  // simulation of "user opens a new terminal" without polluting the
-  // current process.
-  let foundOnUserPath = null;
-  try {
-    const out = execSync(`${shellPath} -lic 'command -v claudeflow 2>/dev/null'`, {
-      encoding: 'utf8',
-      timeout: 6000,
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-    foundOnUserPath = out.length > 0;
-  } catch {
-    // Some shells exit non-zero when `command -v` finds nothing — treat
-    // that as "not found" rather than as an inconclusive check.
-    foundOnUserPath = false;
-  }
-
-  if (foundOnUserPath) return { ok: true };
-
-  // Resolve where the binary actually lives so the warning is concrete.
-  let binPath = null;
-  try {
-    const prefix = execSync('npm config get prefix', { encoding: 'utf8', timeout: 5000 }).trim();
-    binPath = path.join(prefix, 'bin', 'claudeflow');
-  } catch {}
-
-  const home = process.env.HOME || '';
-  const nvmDetected = !!process.env.NVM_DIR
-    || fs.existsSync(path.join(home, '.nvm', 'nvm.sh'));
-  const isZsh = shellPath.endsWith('/zsh');
-  const shellRcFile = isZsh ? '~/.zshrc' : (shellPath.endsWith('/bash') ? '~/.bashrc' : '~/.profile');
-
-  // Wrapper-function fix that mirrors the user's existing nvm lazy-load
-  // pattern (e.g., npx, node, npm). Single line, paste into rcFile, done.
-  const wrapperFix = `claudeflow() { unset -f claudeflow; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; claudeflow "$@"; }`;
-
-  return {
-    ok: false,
-    binPath,
-    shellRcFile,
-    nvmDetected,
-    suggestedFix: wrapperFix,
-  };
-}
-
-function showGettingStarted(cwd, cliStatus = { available: false, autoInstalled: false }) {
-  const MANIFESTS = ['package.json', 'pyproject.toml', 'Gemfile', 'go.mod', 'Cargo.toml', 'composer.json'];
-  const SKIP_DIRS = new Set(['node_modules', 'vendor', '__pycache__', 'dist', 'build', '.next', '.nuxt', '.output', '.claude']);
-
-  const rootHasManifest = MANIFESTS.some((f) => fs.existsSync(path.join(cwd, f)));
-
-  // Scan first-level subdirs for manifests (multi-stack detection)
-  const stackDirs = [];
-  try {
-    const entries = fs.readdirSync(cwd, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory() || entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue;
-      if (MANIFESTS.some((f) => fs.existsSync(path.join(cwd, entry.name, f)))) {
-        stackDirs.push(entry.name);
-      }
-    }
-  } catch {}
-
-  const isMultiStack = stackDirs.length > 1 || (rootHasManifest && stackDirs.length > 0);
-  const isGreenfield = !rootHasManifest && stackDirs.length === 0;
-
-  console.log(`  ${ui.BOLD}Getting started:${ui.RESET}`);
-  console.log('');
-
-  const startCommand = cliStatus.available ? 'claudeflow' : 'claude';
-  if (cliStatus.autoInstalled) {
-    console.log(`  ${ui.DIM}✓ Installed ${ui.CYAN}claudeflow${ui.RESET}${ui.DIM} globally — available as a shell command.${ui.RESET}`);
-    console.log('');
-  } else if (cliStatus.upgraded) {
-    console.log(
-      `  ${ui.DIM}✓ Upgraded global ${ui.CYAN}claudeflow${ui.RESET}${ui.DIM} CLI${cliStatus.fromVersion ? ` from ${cliStatus.fromVersion}` : ''}.${ui.RESET}`
-    );
-    console.log('');
-  }
-
-  // Shell PATH warning — if the global package was installed but the
-  // user's interactive shell can't find the binary (typical with
-  // nvm lazy-load), emit a concrete fix.
-  if (cliStatus.shellPath && cliStatus.shellPath.ok === false) {
-    const sp = cliStatus.shellPath;
-    console.log(`  ${ui.YELLOW}⚠ ${ui.BOLD}claudeflow${ui.RESET}${ui.YELLOW} CLI installed but NOT on your shell PATH.${ui.RESET}`);
-    if (sp.binPath) {
-      console.log(`    ${ui.DIM}Binary lives at: ${sp.binPath}${ui.RESET}`);
-    }
-    if (sp.nvmDetected) {
-      console.log(`    ${ui.DIM}Likely cause: nvm lazy-load. Add this to ${sp.shellRcFile}, then reopen terminal:${ui.RESET}`);
-      console.log(`    ${ui.CYAN}${sp.suggestedFix}${ui.RESET}`);
-    } else {
-      console.log(`    ${ui.DIM}Add the npm prefix bin directory to your PATH in ${sp.shellRcFile}.${ui.RESET}`);
-    }
-    console.log('');
-  }
-
-  if (!cliStatus.available) {
-    console.log(`  ${ui.DIM}To get the ${ui.CYAN}claudeflow${ui.RESET}${ui.DIM} shell command, run:${ui.RESET}`);
-    console.log(`    ${ui.CYAN}npm i -g @axiomatic-labs/claudeflow${ui.RESET}`);
-    if (cliStatus.error && cliStatus.error !== 'skipped') {
-      console.log(`    ${ui.DIM}(auto-install failed: ${cliStatus.error})${ui.RESET}`);
-    }
-    console.log('');
-  }
-  console.log(`  1. Run ${ui.CYAN}${startCommand}${ui.RESET} to start Claude Code`);
-
-  if (isGreenfield) {
-    console.log(`  2. Type ${ui.CYAN}/claudeflow-install${ui.RESET} to start setup`);
-    console.log('');
-    console.log(`     ${ui.DIM}Claudeflow will route you into the new-project setup flow,${ui.RESET}`);
-    console.log(`     ${ui.DIM}research the stack, and generate project-specific skills.${ui.RESET}`);
-  } else if (isMultiStack) {
-    console.log(`  2. Type ${ui.CYAN}/claudeflow-install${ui.RESET} to start setup`);
-    console.log('');
-    ui.info(`Multi-stack project detected: ${stackDirs.join(', ')}${rootHasManifest ? ' + root' : ''}`);
-    console.log('');
-    console.log(`     ${ui.DIM}Claudeflow will route you into the update flow and detect${ui.RESET}`);
-    console.log(`     ${ui.DIM}the relevant stacks before generating project skills.${ui.RESET}`);
-    console.log('');
-    console.log(`  ${ui.BOLD}After setup:${ui.RESET}`);
-    console.log(`  ${ui.DIM}Just describe what you want — Claudeflow handles the rest.${ui.RESET}`);
-  } else {
-    // Single-stack existing project
-    console.log(`  2. Type ${ui.CYAN}/claudeflow-install${ui.RESET} to start setup`);
-    console.log(`     ${ui.DIM}Claudeflow will route you into the existing-project update flow.${ui.RESET}`);
-    console.log(`  3. Tell Claude what you want — it handles the rest`);
-  }
-
-  console.log('');
-  console.log(`  ${ui.BOLD}Slash commands (inside Claude Code):${ui.RESET}`);
-  console.log(`  ${ui.CYAN}/claudeflow-install${ui.RESET}         ${ui.DIM}Smart router — scaffold a new project or update an existing one${ui.RESET}`);
-  console.log(`  ${ui.CYAN}/claudeflow-build${ui.RESET}           ${ui.DIM}Execute multi-file implementation requests with explicit verification${ui.RESET}`);
-  console.log(`  ${ui.CYAN}/claudeflow-review${ui.RESET}          ${ui.DIM}Senior review of a spec, request, or whole project${ui.RESET}`);
-  console.log(`  ${ui.CYAN}/claudeflow-test${ui.RESET}            ${ui.DIM}Run applicable test types with anti-falsification enforcement${ui.RESET}`);
-  console.log(`  ${ui.CYAN}/claudeflow-ship${ui.RESET}            ${ui.DIM}Release gate — classify blockers and deploy when ready${ui.RESET}`);
-  console.log(`  ${ui.CYAN}/claudeflow-prototype${ui.RESET}       ${ui.DIM}Navigable hi-fi prototypes via the Discovery design wave; set-master to write the design foundation${ui.RESET}`);
-  console.log(`  ${ui.CYAN}/claudeflow-regen-claudemd${ui.RESET}  ${ui.DIM}Regenerate CLAUDE.md from the latest template + setup-context${ui.RESET}`);
-  console.log('');
-  console.log(`  ${ui.BOLD}Shell commands (outside Claude Code):${ui.RESET}`);
-  console.log(`  ${ui.CYAN}claudeflow${ui.RESET}                 ${ui.DIM}Start Claude Code with this project's claudeflow context${ui.RESET}`);
-  console.log(`  ${ui.CYAN}claudeflow panel${ui.RESET}           ${ui.DIM}Open the local web dashboard — toggle hooks, reminders, enforcement${ui.RESET}`);
-  console.log(`  ${ui.CYAN}claudeflow doctor${ui.RESET}          ${ui.DIM}Diagnose CDP-port and lockfile issues; ${ui.CYAN}--fix${ui.RESET}${ui.DIM} to auto-repair${ui.RESET}`);
-  console.log(`  ${ui.CYAN}claudeflow install${ui.RESET}         ${ui.DIM}Refresh the template + global CLI in this project${ui.RESET}`);
-  console.log(`  ${ui.CYAN}claudeflow version${ui.RESET}         ${ui.DIM}Show installed framework + CLI versions${ui.RESET}`);
-  console.log('');
-  console.log(`  ${ui.DIM}Docs: https://claudeflow.dev${ui.RESET}`);
-  console.log('');
-}
-
-function syncClaudeSettings(srcSettingsPath, dstSettingsPath) {
-  const templateSettings = readJsonObject(srcSettingsPath, {
-    label: 'template .claude/settings.json',
-    throwOnInvalid: true,
-  });
-  const existingSettings = readJsonObject(dstSettingsPath, {
-    label: 'existing .claude/settings.json',
-    warnOnInvalid: true,
-  }) || {};
-  const mergedSettings = mergeClaudeSettings(templateSettings, existingSettings);
-  fs.writeFileSync(dstSettingsPath, `${JSON.stringify(mergedSettings, null, 2)}\n`);
-}
-
-function mergeClaudeSettings(templateSettings, existingSettings = {}) {
-  const template = isPlainObject(templateSettings) ? templateSettings : {};
-  const existing = isPlainObject(existingSettings) ? existingSettings : {};
-  const merged = {};
-
-  for (const [key, value] of Object.entries(template)) {
-    if (TEMPLATE_MANAGED_SETTINGS_KEYS.includes(key)) {
-      merged[key] = cloneJson(value);
-      continue;
-    }
-    if (TEMPLATE_SEEDED_SETTINGS_KEYS.has(key)) {
-      merged[key] = Object.prototype.hasOwnProperty.call(existing, key)
-        ? cloneJson(existing[key])
-        : cloneJson(value);
-    }
-  }
-
-  for (const [key, value] of Object.entries(existing)) {
-    if (Object.prototype.hasOwnProperty.call(merged, key)) continue;
-    if (TEMPLATE_MANAGED_SETTINGS_KEYS.includes(key)) continue;
-    merged[key] = cloneJson(value);
-  }
-
-  return merged;
-}
-
-function readJsonObject(filePath, options = {}) {
-  if (!fs.existsSync(filePath)) return null;
-  const { label = filePath, throwOnInvalid = false, warnOnInvalid = false } = options;
-
-  try {
-    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-    if (isPlainObject(parsed)) return parsed;
-
-    const message = `${label} must contain a top-level JSON object`;
-    if (throwOnInvalid) throw new Error(message);
-    if (warnOnInvalid) ui.warn(`${message}. Replacing it with template-managed defaults.`);
-    return null;
-  } catch (error) {
-    if (throwOnInvalid) throw error;
-    if (warnOnInvalid) ui.warn(`${label} is invalid JSON. Replacing it with template-managed defaults.`);
-    return null;
-  }
-}
-
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
-function cloneJson(value) {
-  if (value === undefined) return undefined;
-  return JSON.parse(JSON.stringify(value));
-}
-
-// Install ast-grep CLI, uv, and Serena MCP for runtime and analysis.
-// All steps are best-effort — failures warn but never block the install.
-function installAnalysisTools() {
-  console.log('');
-  ui.step('Setting up runtime & analysis tools...');
-
-  // 1. ast-grep CLI
-  const hasAstGrep = commandExists('sg');
-  if (hasAstGrep) {
-    ui.success('ast-grep CLI already installed');
-  } else {
-    ui.step('Installing ast-grep CLI...');
-    try {
-      execSync('npm install -g @ast-grep/cli', { stdio: 'pipe', timeout: 60000 });
-      ui.success('ast-grep CLI installed');
-    } catch {
-      ui.warn('ast-grep install failed — code exploration will use Grep fallback');
-    }
-  }
-
-  // 2. uv (required by Serena)
-  let hasUv = commandExists('uv');
-  if (hasUv) {
-    ui.success('uv already installed');
-  } else {
-    ui.step('Installing uv (Python package manager)...');
-    try {
-      if (process.platform === 'win32') {
-        execSync('powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"', {
-          stdio: 'pipe',
-          timeout: 60000,
-        });
-      } else {
-        execSync('curl -LsSf https://astral.sh/uv/install.sh | sh', {
-          stdio: 'pipe',
-          timeout: 60000,
-        });
-      }
-      // uv installs to ~/.local/bin or ~/.cargo/bin — check both
-      hasUv = commandExists('uv') || commandExists(path.join(homedir(), '.local', 'bin', 'uv'));
-      if (hasUv) {
-        ui.success('uv installed');
-      } else {
-        ui.warn('uv installed but not in PATH — restart your terminal before running init/update');
-      }
-    } catch {
-      ui.warn('uv install failed — Serena MCP will not be available');
-    }
-  }
-
-  // 3. Write MCP servers directly to .mcp.json (more reliable than claude mcp add)
-  configureMcpServers(hasUv);
-
-  // 4. Prime Serena for the current project when possible.
-  if (hasUv) {
-    indexSerenaProject(process.cwd());
-  }
-}
-
-// Write Serena and context7 MCP configs directly to .mcp.json.
-// This is more reliable than `claude mcp add` which can misparse flags.
-function configureMcpServers(hasUv) {
-  const cwd = process.cwd();
-  const mcpPath = path.join(cwd, '.mcp.json');
-
-  // Read existing .mcp.json or start fresh
-  let mcpConfig = { mcpServers: {} };
-  try {
-    const existing = fs.readFileSync(mcpPath, 'utf8');
-    mcpConfig = JSON.parse(existing);
-    if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
-  } catch {
-    // File doesn't exist or is invalid — start fresh
-  }
-
-  let changed = false;
-
-  // Serena MCP (requires uv)
-  if (hasUv) {
-    const serenaCommand = commandExists('uvx') ? 'uvx' : 'uv';
-    const serenaArgs = serenaCommand === 'uvx'
-      ? [
-        '--from', SERENA_REPO,
-        'serena', 'start-mcp-server',
-        '--context', 'claude-code',
-        '--project-from-cwd',
-      ]
-      : [
-        'run', '--with', SERENA_REPO,
-        'serena', 'start-mcp-server',
-        '--context', 'claude-code',
-        '--project-from-cwd',
-      ];
-    ui.step(mcpConfig.mcpServers.serena ? 'Refreshing Serena MCP configuration...' : 'Adding Serena MCP for semantic code analysis...');
-    // Spread first so user-added fields (env with API keys, cwd, etc.) survive.
-    mcpConfig.mcpServers.serena = {
-      ...mcpConfig.mcpServers.serena,
-      type: 'stdio',
-      command: serenaCommand,
-      args: serenaArgs,
-    };
-    changed = true;
-    ui.success('Serena MCP configured');
-  }
-
-  // context7 MCP
-  ui.step(mcpConfig.mcpServers.context7 ? 'Refreshing context7 MCP configuration...' : 'Adding context7 MCP for library documentation...');
-  // Spread first so user-added fields (env with API keys, cwd, etc.) survive.
-  mcpConfig.mcpServers.context7 = {
-    ...mcpConfig.mcpServers.context7,
-    type: 'stdio',
-    command: 'npx',
-    args: ['-y', '@upstash/context7-mcp@latest'],
-  };
-  changed = true;
-  ui.success('context7 MCP configured');
-
-  // codegraph MCP — AST-local code-graph for blast-radius / impact analysis.
-  // Runs via npx (no uv/Ollama/API key needed), so it is unconditional like context7.
-  // The build agents' investigation workflow uses it when available ("code-graph MCP
-  // if available, else grep") for transitive impact/callers; superior to grep for
-  // blast-radius. Index is built on first use; blind to .astro/.sql (agents fall back to grep).
-  ui.step(mcpConfig.mcpServers.codegraph ? 'Refreshing codegraph MCP configuration...' : 'Adding codegraph MCP for blast-radius analysis...');
-  // Spread first so user-added fields (cwd, env, etc.) survive.
-  mcpConfig.mcpServers.codegraph = {
-    ...mcpConfig.mcpServers.codegraph,
-    type: 'stdio',
-    command: 'npx',
-    args: ['--yes', '@colbymchenry/codegraph@latest', 'serve', '--mcp'],
-  };
-  changed = true;
-  ui.success('codegraph MCP configured');
-
-  // Write .mcp.json if anything changed
-  if (changed) {
-    try {
-      fs.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + '\n');
-    } catch (e) {
-      ui.warn(`Could not write .mcp.json: ${e.message}`);
-    }
-  }
-}
-
-// Check if a command exists in PATH
-function commandExists(cmd) {
-  try {
-    const check = process.platform === 'win32' ? `where "${cmd}"` : `command -v "${cmd}"`;
-    execSync(check, { stdio: 'pipe' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function indexSerenaProject(projectRoot) {
-  const statusPath = path.join(projectRoot, '.claudeflow', 'tmp', 'tooling', 'serena-status.json');
-
-  // Idempotent reinstall: skip indexing if a previous install already indexed
-  // the project successfully. To force a reindex, delete the marker file.
-  try {
-    const existing = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
-    if (existing && existing.indexed === true) {
-      ui.success('Serena project index already present (delete .claudeflow/tmp/tooling/serena-status.json to force reindex)');
-      return;
-    }
-  } catch {}
-
-  ui.step('Indexing project for Serena...');
-  const attempts = [
-    { command: 'uvx', args: ['--from', SERENA_REPO, 'serena', 'project', 'index', projectRoot] },
-    { command: 'uv', args: ['run', '--with', SERENA_REPO, 'serena', 'project', 'index', projectRoot] },
-  ];
-
-  let failureReason = 'uv/uvx not available';
-  let indexed = false;
-  for (const attempt of attempts) {
-    if (!commandExists(attempt.command)) continue;
-    try {
-      execFileSync(attempt.command, attempt.args, { cwd: projectRoot, stdio: 'pipe', timeout: 120000 });
-      indexed = true;
-      failureReason = null;
-      break;
-    } catch (error) {
-      failureReason = error.stderr ? String(error.stderr).trim() : error.message;
-    }
-  }
-
-  fs.mkdirSync(path.dirname(statusPath), { recursive: true });
-  fs.writeFileSync(statusPath, `${JSON.stringify({
-    configured: true,
-    indexed,
-    last_attempt_at: new Date().toISOString(),
-    failure_reason: failureReason,
-  }, null, 2)}\n`);
-
-  if (indexed) {
-    ui.success('Serena project index ready');
-  } else {
-    ui.warn('Serena indexing failed — semantic navigation may need a manual retry');
-  }
-}
-
-
-function normalizeRelativePath(value) {
-  return String(value || '').replace(/\\/g, '/').replace(/^\/+/, '');
-}
-
-function isPathInside(candidatePath, parentPath) {
-  const relative = path.relative(parentPath, candidatePath);
-  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
-}
-
-function collectFilesRecursive(rootDir) {
-  if (!fs.existsSync(rootDir)) return [];
-  const files = [];
-  const stack = [rootDir];
-  while (stack.length > 0) {
-    const current = stack.pop();
-    const entries = fs.readdirSync(current, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = path.join(current, entry.name);
-      if (entry.isDirectory()) {
-        stack.push(fullPath);
-      } else if (entry.isFile()) {
-        files.push(fullPath);
-      }
-    }
-  }
-  return files;
-}
-
-function addFilesFromDir(set, rootBase, targetDir, opts = {}) {
-  const { destPrefix } = opts;
-  for (const filePath of collectFilesRecursive(targetDir)) {
-    let relPath;
-    if (destPrefix !== undefined) {
-      const subRel = normalizeRelativePath(path.relative(targetDir, filePath));
-      relPath = normalizeRelativePath(subRel ? `${destPrefix}/${subRel}` : destPrefix);
-    } else {
-      relPath = normalizeRelativePath(path.relative(rootBase, filePath));
-    }
-    if (relPath.startsWith('.claude/')) {
-      set.add(relPath);
-    }
-  }
-}
-
-function collectManagedPathsFromRelease(extractRoot) {
-  const srcClaudeflow = path.join(extractRoot, '.claudeflow');
-  // v2.13.148+: single .claude/ tree at the zip root, no variants.
-  const srcClaude = path.join(extractRoot, '.claude');
-  const managed = new Set();
-
-  const settingsPath = path.join(srcClaude, 'settings.json');
-  if (fs.existsSync(settingsPath)) {
-    managed.add('.claude/settings.json');
-  }
-
-  addFilesFromDir(managed, extractRoot, path.join(srcClaude, 'hooks'), {
-    destPrefix: '.claude/hooks',
-  });
-
-  // Claudeflow dirs: runtime, templates, docs, playbooks in .claudeflow/.
-  // playbooks/ added in v2 — required for the claudeflow-build orchestrator
-  // and its always-loaded foundation/routing references.
-  ['runtime', 'templates', 'docs', 'playbooks'].forEach((folder) => {
-    addFilesFromDir(managed, extractRoot, path.join(srcClaudeflow, folder));
-  });
+const CLAUDE_MARK = '<!-- claudeflow:begin -->';
+const HOOK_TAG = 'scripts/claudeflow/hook_';            // identifies OUR hook entries in settings.json
+const PER_PROJECT_CONFIGS = ['brand.json', 'risk-signals.json'];  // create-if-absent, never clobber
+const SHARED_CONFIGS = ['playbook-map.json'];                     // always refreshed (shared system)
 
-  const skillsDir = path.join(srcClaude, 'skills');
-  if (fs.existsSync(skillsDir)) {
-    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isDirectory() && entry.name.startsWith('claudeflow-')) {
-        addFilesFromDir(managed, extractRoot, path.join(skillsDir, entry.name), {
-          destPrefix: `.claude/skills/${entry.name}`,
-        });
-      }
-    }
-  }
+function rmrf(p) { fs.rmSync(p, { recursive: true, force: true }); }
 
-  const agentsDir = path.join(srcClaude, 'agents');
-  if (fs.existsSync(agentsDir)) {
-    const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
-      const agentName = entry.name.replace(/\.md$/, '');
-      if (!isTemplateManagedAgent(agentName)) continue;
-      managed.add(normalizeRelativePath(path.join('.claude', 'agents', entry.name)));
-    }
-  }
-
-  const tmpDir = path.join(srcClaudeflow, 'tmp');
-  if (fs.existsSync(tmpDir)) {
-    const entries = fs.readdirSync(tmpDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isFile()) {
-        managed.add(normalizeRelativePath(path.join('.claudeflow', 'tmp', entry.name)));
-      }
-    }
-  }
-
-  const versionFile = path.join(srcClaudeflow, 'version');
-  if (fs.existsSync(versionFile)) {
-    managed.add('.claudeflow/version');
-  }
-
-  return managed;
-}
-
-function collectLegacyManagedPathsFromDisk(projectRoot) {
-  const claudeDir = path.join(projectRoot, '.claude');
-  const claudeflowDir = path.join(projectRoot, '.claudeflow');
-  const managed = new Set();
-
-  const settingsPath = path.join(claudeDir, 'settings.json');
-  if (fs.existsSync(settingsPath)) {
-    managed.add('.claude/settings.json');
-  }
-
-  // Claude Code native: hooks stay in .claude/
-  addFilesFromDir(managed, projectRoot, path.join(claudeDir, 'hooks'));
-
-  // Claudeflow dirs: runtime, templates, docs, playbooks in .claudeflow/.
-  // playbooks/ added in v2 — required for the claudeflow-build orchestrator.
-  // (variants/ removed in v2.13.148. .claudeflow/cli/ removed in v2.13.153.)
-  ['runtime', 'templates', 'docs', 'playbooks'].forEach((folder) => {
-    addFilesFromDir(managed, projectRoot, path.join(claudeflowDir, folder));
-  });
-
-  const skillsDir = path.join(claudeDir, 'skills');
-  if (fs.existsSync(skillsDir)) {
-    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isDirectory() && entry.name.startsWith('claudeflow-')) {
-        addFilesFromDir(managed, projectRoot, path.join(skillsDir, entry.name));
-      }
-    }
-  }
-
-  const agentsDir = path.join(claudeDir, 'agents');
-  if (fs.existsSync(agentsDir)) {
-    const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
-      const agentName = entry.name.replace(/\.md$/, '');
-      if (!isTemplateManagedAgent(agentName)) continue;
-      managed.add(normalizeRelativePath(path.join('.claude', 'agents', entry.name)));
-    }
-  }
-
-  const tmpDir = path.join(claudeflowDir, 'tmp');
-  if (fs.existsSync(tmpDir)) {
-    const entries = fs.readdirSync(tmpDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isFile() && entry.name.endsWith('.py')) {
-        managed.add(normalizeRelativePath(path.join('.claudeflow', 'tmp', entry.name)));
-      }
-    }
-  }
-
-  const versionFile = path.join(claudeflowDir, 'version');
-  if (fs.existsSync(versionFile)) {
-    managed.add('.claudeflow/version');
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, e.name), d = path.join(dst, e.name);
+    if (e.isDirectory()) copyDir(s, d);
+    else if (e.isFile()) fs.copyFileSync(s, d);
   }
-
-  return managed;
 }
 
-function readTemplateManagedManifest(projectRoot) {
-  const manifestPath = path.join(projectRoot, TEMPLATE_MANAGED_MANIFEST);
-  if (!fs.existsSync(manifestPath)) return null;
-
-  try {
-    const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    if (!Array.isArray(parsed.managed_paths)) return null;
-    const managedPaths = new Set(
-      parsed.managed_paths
-        .filter((entry) => typeof entry === 'string')
-        .map((entry) => normalizeRelativePath(entry))
-        .filter((entry) => entry.startsWith('.claude/')),
-    );
-    return {
-      version: typeof parsed.version === 'string' ? parsed.version : null,
-      managedPaths,
-    };
-  } catch {
-    return null;
+function countFiles(dir) {
+  let n = 0;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) n += countFiles(path.join(dir, e.name));
+    else n++;
   }
+  return n;
 }
 
-function writeTemplateManagedManifest(projectRoot, version, managedPaths) {
-  const manifestPath = path.join(projectRoot, TEMPLATE_MANAGED_MANIFEST);
-  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-  const payload = {
-    schema_version: 1,
-    version,
-    updated_at: new Date().toISOString(),
-    managed_paths: [...managedPaths].sort(),
-  };
-  fs.writeFileSync(manifestPath, `${JSON.stringify(payload, null, 2)}\n`);
-}
-
-function pruneStaleManagedPaths(projectRoot, staleRelativePaths) {
-  if (!Array.isArray(staleRelativePaths) || staleRelativePaths.length === 0) {
-    return 0;
+function mergeSettings(cwd, payloadSettings) {
+  const sp = path.join(cwd, '.claude', 'settings.json');
+  let data = {};
+  if (fs.existsSync(sp)) { try { data = JSON.parse(fs.readFileSync(sp, 'utf8')); } catch { data = {}; } }
+  const hooks = data.hooks || (data.hooks = {});
+  // Drop any existing claudeflow hook entries (identified by our script path) so a re-install replaces
+  // stale matchers/timeouts; the user's OWN hooks (not referencing scripts/claudeflow/hook_) are kept.
+  for (const evt of Object.keys(hooks)) {
+    hooks[evt] = (hooks[evt] || []).filter(e => !(e.hooks || []).some(h => (h.command || '').includes(HOOK_TAG)));
+    if (!hooks[evt].length) delete hooks[evt];
   }
-
-  const claudeflowRoot = path.resolve(projectRoot, '.claude');
-  let removedCount = 0;
-  const uniquePaths = [...new Set(staleRelativePaths.map((entry) => normalizeRelativePath(entry)))]
-    .filter((entry) => entry.startsWith('.claude/'))
-    .sort((a, b) => b.length - a.length);
-
-  for (const relPath of uniquePaths) {
-    const absolutePath = path.resolve(projectRoot, relPath);
-    if (!isPathInside(absolutePath, claudeflowRoot)) continue;
-    if (!fs.existsSync(absolutePath)) continue;
-
-    fs.rmSync(absolutePath, { recursive: true, force: true });
-    removedCount += 1;
-    pruneEmptyAncestors(path.dirname(absolutePath), claudeflowRoot);
+  // Add the shipped claudeflow hook entries.
+  const ph = (payloadSettings && payloadSettings.hooks) || {};
+  for (const evt of Object.keys(ph)) {
+    const arr = hooks[evt] || (hooks[evt] = []);
+    for (const entry of ph[evt]) arr.push(entry);
   }
-
-  return removedCount;
+  if (payloadSettings && payloadSettings['$schema'] && !data['$schema']) data['$schema'] = payloadSettings['$schema'];
+  fs.mkdirSync(path.dirname(sp), { recursive: true });
+  fs.writeFileSync(sp, JSON.stringify(data, null, 2) + '\n');
 }
 
-function pruneEmptyAncestors(startDir, stopDir) {
-  let current = startDir;
-  while (isPathInside(current, stopDir) && current !== stopDir) {
-    if (!fs.existsSync(current)) {
-      current = path.dirname(current);
-      continue;
-    }
-    const entries = fs.readdirSync(current);
-    if (entries.length > 0) break;
-    fs.rmdirSync(current);
-    current = path.dirname(current);
-  }
+function appendClaudeMd(cwd, snippetPath) {
+  if (!fs.existsSync(snippetPath)) return false;
+  const target = path.join(cwd, 'CLAUDE.md');
+  if (fs.existsSync(target) && fs.readFileSync(target, 'utf8').includes(CLAUDE_MARK)) return false;
+  const snippet = fs.readFileSync(snippetPath, 'utf8');
+  const prefix = fs.existsSync(target) ? '\n' : '';
+  fs.appendFileSync(target, prefix + snippet);
+  return true;
 }
 
-function assertRequiredTemplateRules(rulesDir) {
-  for (const filename of REQUIRED_TEMPLATE_RULES) {
-    const rulePath = path.join(rulesDir, filename);
-    if (!fs.existsSync(rulePath)) {
-      throw new Error(
-        `Release asset is missing required template rule .claude/rules/${filename}. Rebuild the release before installing.`,
-      );
-    }
-  }
-}
+// Place + merge the framework from an extracted payload dir into a project. Pure filesystem, no network —
+// so it is testable on a throwaway dir.
+function installFromPayload(src, cwd) {
+  const out = { playbooks: 0, scripts: 0, skills: 0, claudeMd: false };
 
-// v1 build-orchestrator artifacts that v2 replaces. When upgrading from a
-// pre-v2 install, these stay on disk because install.js's stale cleanup
-// can't match files that exist on disk but aren't in the v2 ZIP manifest.
-// Listing them explicitly here makes the v1 → v2 upgrade leave a clean
-// .claude/.
-const LEGACY_V1_BUILD_ARTIFACTS = [
-  // v1 had phases/references inside build/test/review skills; v2 doesn't.
-  '.claude/skills/claudeflow-build/phases',
-  '.claude/skills/claudeflow-build/references',
-  '.claude/skills/claudeflow-test/phases',
-  '.claude/skills/claudeflow-test/references',
-  '.claude/skills/claudeflow-review/phases',
-  '.claude/skills/claudeflow-review/references',
-  // v1 enforcement hooks; v2 uses guard-sensitive-files + validate-closure +
-  // session-env + filter-command-output instead.
-  '.claude/hooks/PreToolUse/enforce-task-creation.js',
-  '.claude/hooks/PreToolUse/enforce-ecosystem-artifacts.js',
-  '.claude/hooks/PreToolUse/freeze-step-contract.js',
-  '.claude/hooks/PreToolUse/freeze-workflow-state.js',
-  '.claude/hooks/PreToolUse/route-exit-plan-mode.js',
-  '.claude/hooks/PreToolUse/stack-debt-guard.js',
-];
-
-function pruneLegacyV1BuildArtifacts(projectRoot) {
-  for (const relPath of LEGACY_V1_BUILD_ARTIFACTS) {
-    const absPath = path.join(projectRoot, relPath);
-    if (!fs.existsSync(absPath)) continue;
-    try {
-      fs.rmSync(absPath, { recursive: true, force: true });
-    } catch {
-      // Best-effort. If the file is locked or permissions issue, skip;
-      // the user can clean up manually. Don't abort the install.
-    }
+  // 1) Playbooks — always refreshed (shared system).
+  const srcPlaybooks = path.join(src, '.claudeflow', 'playbooks');
+  if (fs.existsSync(srcPlaybooks)) {
+    const dst = path.join(cwd, '.claudeflow', 'playbooks');
+    rmrf(dst); copyDir(srcPlaybooks, dst);
+    out.playbooks = countFiles(dst);
   }
-}
 
-function pruneLegacyTemplateRules(projectRoot) {
-  const rulesDir = path.join(projectRoot, '.claude', 'rules');
-  for (const filename of LEGACY_TEMPLATE_RULES) {
-    fs.rmSync(path.join(rulesDir, filename), { force: true });
+  // 2) Configs — per-project ones create-if-absent (never clobber a customized brand); shared refresh.
+  fs.mkdirSync(path.join(cwd, '.claudeflow'), { recursive: true });
+  for (const c of PER_PROJECT_CONFIGS) {
+    const s = path.join(src, '.claudeflow', c), d = path.join(cwd, '.claudeflow', c);
+    if (fs.existsSync(s) && !fs.existsSync(d)) fs.copyFileSync(s, d);
   }
-  if (fs.existsSync(rulesDir) && fs.readdirSync(rulesDir).length === 0) {
-    fs.rmdirSync(rulesDir);
+  for (const c of SHARED_CONFIGS) {
+    const s = path.join(src, '.claudeflow', c);
+    if (fs.existsSync(s)) fs.copyFileSync(s, path.join(cwd, '.claudeflow', c));
   }
-}
 
-function propagateTemplateRules(projectRoot, srcTemplates) {
-  const srcRulesDir = path.join(srcTemplates, 'rules');
-  if (!fs.existsSync(srcRulesDir)) return;
-  const dstRulesDir = path.join(projectRoot, '.claude', 'rules');
-  fs.mkdirSync(dstRulesDir, { recursive: true });
-  for (const filename of fs.readdirSync(srcRulesDir)) {
-    if (!filename.endsWith('.md')) continue;
-    // Skip the 8 v2 system rules — they're handled by
-    // propagateSystemRulesViaScaffold, which derives framework-aware
-    // `paths` from setup-context.json when available.
-    if (V2_SYSTEM_RULES.has(filename)) continue;
-    const dstPath = path.join(dstRulesDir, filename);
-    if (fs.existsSync(dstPath)) continue; // no-clobber: preserve project-specific or user rules
-    fs.copyFileSync(path.join(srcRulesDir, filename), dstPath);
+  // 3) Scripts (hooks + scans + servers) — always refreshed.
+  const srcScripts = path.join(src, 'scripts', 'claudeflow');
+  if (fs.existsSync(srcScripts)) {
+    const dst = path.join(cwd, 'scripts', 'claudeflow');
+    fs.mkdirSync(dst, { recursive: true });
+    for (const e of fs.readdirSync(srcScripts)) { fs.copyFileSync(path.join(srcScripts, e), path.join(dst, e)); out.scripts++; }
   }
-}
-
-// The 8 v2 system rules that ship with claudeflow. propagateTemplateRules
-// skips these because they need scaffold-system-rule.js to derive
-// framework-aware `paths` frontmatter (e.g., a Next.js+Prisma project
-// gets `**/*.prisma` and `**/app/api/**` instead of broad defaults).
-const V2_SYSTEM_RULES = new Set([
-  'claudeflow-context-engineering.md',
-  'claudeflow-engineering-quality.md',
-  'claudeflow-testing.md',
-  'claudeflow-security.md',
-  'claudeflow-api.md',
-  'claudeflow-database.md',
-  'claudeflow-ui-ux.md',
-  'claudeflow-evidence.md',
-]);
-
-// Map of v2 rule filenames → rule slug used by scaffold-system-rule.js
-function ruleSlugFromFilename(filename) {
-  // Strip "claudeflow-" prefix and ".md" suffix. e.g.,
-  // "claudeflow-ui-ux.md" → "ui-ux".
-  return filename.replace(/^claudeflow-/, '').replace(/\.md$/, '');
-}
 
-function propagateSystemRulesViaScaffold(projectRoot) {
-  const scaffoldScript = path.join(
-    projectRoot, '.claudeflow', 'runtime', 'scaffold-system-rule.js',
-  );
-  if (!fs.existsSync(scaffoldScript)) {
-    // scaffold-system-rule.js is part of v2 — if missing, the project
-    // was bootstrapped with a pre-v2 ZIP. Skip silently; user can run
-    // /claudeflow-update later to refresh.
-    return;
-  }
-
-  for (const filename of V2_SYSTEM_RULES) {
-    const slug = ruleSlugFromFilename(filename);
-    try {
-      execFileSync('node', [
-        scaffoldScript,
-        '--rule', slug,
-        '--project-root', projectRoot,
-        '--mode', 'init',
-        // No --force: respect no-clobber. User edits win.
-      ], { stdio: ['ignore', 'ignore', 'pipe'] });
-    } catch (err) {
-      // scaffold-system-rule.js exits 1 when target exists (no-clobber).
-      // That's expected on re-install; don't warn. Other exit codes are
-      // real errors; log to stderr but don't abort the install.
-      const exitCode = err && err.status;
-      if (exitCode !== 1) {
-        process.stderr.write(
-          `Warning: failed to scaffold system rule "${slug}" (exit ${exitCode}). ` +
-            `You can re-run with /claudeflow-update later.\n`,
-        );
-      }
+  // 4) Skills — replace each shipped claudeflow-* skill; preserve the user's own skills.
+  const srcSkills = path.join(src, '.claude', 'skills');
+  if (fs.existsSync(srcSkills)) {
+    const dst = path.join(cwd, '.claude', 'skills');
+    fs.mkdirSync(dst, { recursive: true });
+    for (const e of fs.readdirSync(srcSkills, { withFileTypes: true })) {
+      if (!e.isDirectory() || !e.name.startsWith('claudeflow-')) continue;
+      const d = path.join(dst, e.name);
+      rmrf(d); copyDir(path.join(srcSkills, e.name), d); out.skills++;
     }
   }
-}
 
-function materializeSharedAppendPrompt(projectRoot) {
-  const templatePath = path.join(projectRoot, SHARED_APPEND_PROMPT_TEMPLATE);
-  if (!fs.existsSync(templatePath)) {
-    throw new Error(
-      `Shared append prompt template is missing: ${SHARED_APPEND_PROMPT_TEMPLATE}. Rebuild the release before installing.`,
-    );
+  // 5) settings.json hooks — MERGE (never clobber the user's settings).
+  const srcSettings = path.join(src, '.claude', 'settings.json');
+  if (fs.existsSync(srcSettings)) {
+    try { mergeSettings(cwd, JSON.parse(fs.readFileSync(srcSettings, 'utf8'))); } catch {}
   }
 
-  const outputPath = path.join(projectRoot, SHARED_APPEND_PROMPT_OUTPUT);
-  fs.copyFileSync(templatePath, outputPath);
-}
-
-// Inject the canonical claudeflow rules block into the project's CLAUDE.md.
-//
-// Three cases:
-//   1. CLAUDE.md absent → create with the block plus user-content section
-//   2. CLAUDE.md present, no sentinel, no opt-out → prepend the block,
-//      preserving every byte of the existing file
-//   3. CLAUDE.md present with sentinel → replace the block in place
-//      (keeps future template revisions propagating idempotently)
-//
-// User opt-out: drop the literal string `claudeflow:default-rules:opt-out`
-// anywhere in CLAUDE.md (e.g. in a comment) to skip injection forever.
-//
-// The block is wrapped in HTML comments — markdown renders them invisibly
-// but they survive editor round-trips and remain machine-detectable.
-const CLAUDE_MD_INJECT_BEGIN = '<!-- claudeflow:default-rules:start (do not edit between markers) -->';
-const CLAUDE_MD_INJECT_END = '<!-- claudeflow:default-rules:end -->';
-const CLAUDE_MD_OPT_OUT = 'claudeflow:default-rules:opt-out';
+  // 6) CLAUDE.md — append the guidance block (idempotent).
+  out.claudeMd = appendClaudeMd(cwd, path.join(src, 'assets', 'CLAUDE.snippet.md'));
 
-function buildDefaultRulesBlock(projectRoot) {
-  const templatePath = path.join(projectRoot, DEFAULT_CLAUDE_MD_TEMPLATE);
-  if (!fs.existsSync(templatePath)) return null;
-  let body = fs.readFileSync(templatePath, 'utf8');
-  // Strip the leading `# CLAUDE.md` heading — when injected into an existing
-  // file the heading would conflict with the user's own H1.
-  body = body.replace(/^\s*#\s*CLAUDE\.md\s*\r?\n+/, '').trimEnd();
-  return `${CLAUDE_MD_INJECT_BEGIN}\n${body}\n${CLAUDE_MD_INJECT_END}`;
+  return out;
 }
 
-function ensureDefaultClaudeMdRules(projectRoot) {
-  const block = buildDefaultRulesBlock(projectRoot);
-  if (!block) return { action: 'no-template' };
-
-  const outputPath = path.join(projectRoot, DEFAULT_CLAUDE_MD_OUTPUT);
-
-  if (!fs.existsSync(outputPath)) {
-    fs.writeFileSync(outputPath, `${block}\n`);
-    return { action: 'created' };
-  }
-
-  const existing = fs.readFileSync(outputPath, 'utf8');
-
-  if (existing.includes(CLAUDE_MD_OPT_OUT)) {
-    return { action: 'opt-out' };
-  }
-
-  // The block always lives at the bottom. Two paths get us there:
-  //   - sentinels found at the bottom and content current → unchanged
-  //   - sentinels found anywhere else (top, middle, stale content) →
-  //     remove the old block and append a fresh one at the tail.
-  //   - sentinels absent → append for the first time.
-  const beginIdx = existing.indexOf(CLAUDE_MD_INJECT_BEGIN);
-  const endIdx = existing.indexOf(CLAUDE_MD_INJECT_END);
-  let userContent;
-  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
-    const before = existing.slice(0, beginIdx);
-    const after = existing.slice(endIdx + CLAUDE_MD_INJECT_END.length);
-    userContent = `${before.replace(/\s+$/, '')}${after.startsWith('\n') ? '' : '\n'}${after}`.replace(/^\s+/, '').replace(/\s+$/, '');
-  } else {
-    userContent = existing.replace(/\s+$/, '');
-  }
-
-  const next = userContent.length === 0
-    ? `${block}\n`
-    : `${userContent}\n\n${block}\n`;
-
-  if (next === existing) return { action: 'unchanged' };
-  fs.writeFileSync(outputPath, next);
-  return { action: beginIdx !== -1 ? 'updated' : 'injected' };
-}
+async function run() {
+  const current = readLocalVersion();
+  ui.banner(current || undefined);
+  const cwd = process.cwd();
 
-function isTemplateManagedAgent(agentName) {
-  return agentName.startsWith('claudeflow-');
-}
+  ui.step('Authenticating with GitHub...');
+  const token = await requireAuth();
 
-function listTemplateManagedAgents(agentsDir) {
-  if (!fs.existsSync(agentsDir)) return [];
-  return fs.readdirSync(agentsDir)
-    .filter((entry) => entry.endsWith('.md'))
-    .map((entry) => entry.replace(/\.md$/, ''))
-    .filter((name) => isTemplateManagedAgent(name))
-    .sort();
-}
+  ui.step('Fetching latest release...');
+  const release = await getLatestRelease(token);
+  const asset = (release.assets || []).find(a => /\.zip$/.test(a.name));
+  if (!asset) throw new Error('No .zip asset found in the latest release.');
+  const version = (release.tag_name || '').replace(/^v/, '')
+    || asset.name.replace(/^claudeflow-?v?/, '').replace(/\.zip$/, '');
 
-// Recursively copy a directory, creating parents as needed
-function copyDirSync(src, dst, skipNames) {
-  fs.mkdirSync(dst, { recursive: true });
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-  for (const entry of entries) {
-    if (skipNames && skipNames.has(entry.name)) continue;
-    const srcPath = path.join(src, entry.name);
-    const dstPath = path.join(dst, entry.name);
-    if (entry.isDirectory()) {
-      copyDirSync(srcPath, dstPath);
-    } else {
-      fs.copyFileSync(srcPath, dstPath);
-    }
-  }
-}
+  ui.step(`Downloading ${asset.name}...`);
+  const zipBuffer = await downloadReleaseAsset(asset, token);
 
-// Append the claudeflow addendum to CLAUDE.md (idempotent).
-// The block between <!-- claudeflow:boost-mode:BEGIN/END --> markers carries
-// the load-bearing rule ("all code changes flow through /claudeflow-build")
-// plus mode-aware mandates. Re-runs on every install/update; refreshes a
-// stale block if present. Marker name preserved for backwards compatibility
-// with projects upgraded across the v2.13.148 variants-removal boundary.
-function syncBoostAddendumOnInstall(cwd) {
-  // v2.13.152: in unified mode (mode is per-build, picked at /claudeflow-build
-  // invocation), the addendum is always injected when CLAUDE.md exists. The
-  // load-bearing rule "all code changes flow through /claudeflow-build" applies
-  // regardless of which mode is picked per build, so we no longer gate on
-  // .claudeflow/active-mode (which was removed in v2.13.148). Mode-specific
-  // mandates inside the addendum body explicitly say "fast-only" or
-  // "normal-only" so the LLM applies them conditionally.
-  const claudeMdPath = path.join(cwd, 'CLAUDE.md');
-  const addendumPath = path.join(cwd, '.claudeflow', 'templates', 'claudeflow-append-claude-md.md');
-  if (!fs.existsSync(claudeMdPath) || !fs.existsSync(addendumPath)) return;
+  const tmpZip = path.join(os.tmpdir(), `claudeflow-${Date.now()}.zip`);
+  const tmp = path.join(os.tmpdir(), `claudeflow-extract-${Date.now()}`);
+  fs.writeFileSync(tmpZip, zipBuffer);
+  fs.mkdirSync(tmp, { recursive: true });
+  // -qq silences unzip's per-file output (large ZIPs otherwise blow execSync's 1MB buffer).
+  execSync(`unzip -qq -o "${tmpZip}" -d "${tmp}"`, { stdio: 'ignore' });
 
-  const ADDENDUM_BEGIN = '<!-- claudeflow:boost-mode:BEGIN -->';
-  const ADDENDUM_END = '<!-- claudeflow:boost-mode:END -->';
-  const original = fs.readFileSync(claudeMdPath, 'utf8');
-  const beginIdx = original.indexOf(ADDENDUM_BEGIN);
-  const endIdx = original.indexOf(ADDENDUM_END);
-  const hasBlock = beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx;
+  ui.step('Installing framework...');
+  const summary = installFromPayload(tmp, cwd);
+  writeLocalVersion(`v${version}`);
 
-  let base = original;
-  if (hasBlock) {
-    const blockEnd = endIdx + ADDENDUM_END.length;
-    base = original.slice(0, beginIdx).replace(/\s*$/, '') + original.slice(blockEnd).replace(/^\s*/, '\n');
-  }
+  try { rmrf(tmp); fs.rmSync(tmpZip, { force: true }); } catch {}
 
-  const addendumBody = fs.readFileSync(addendumPath, 'utf8').trimEnd();
-  const block = `\n\n${ADDENDUM_BEGIN}\n${addendumBody}\n${ADDENDUM_END}\n`;
-  fs.writeFileSync(claudeMdPath, base.replace(/\s*$/, '') + block);
+  ui.success(`claudeflow v${version} installed`);
+  ui.info(`  ${summary.playbooks} playbooks · ${summary.scripts} scripts · ${summary.skills} skills`
+    + (summary.claudeMd ? ' · CLAUDE.md guidance added' : ''));
+  ui.done(`Describe a change and the ${ui.BOLD}claudeflow-implement${ui.RESET} skill will drive it.`);
 }
 
-module.exports = Object.assign(run, {
-  assertRequiredTemplateRules,
-  materializeSharedAppendPrompt,
-  ensureDefaultClaudeMdRules,
-  buildDefaultRulesBlock,
-  CLAUDE_MD_INJECT_BEGIN,
-  CLAUDE_MD_INJECT_END,
-  CLAUDE_MD_OPT_OUT,
-  isTemplateManagedAgent,
-  listTemplateManagedAgents,
-  mergeClaudeSettings,
-  commandExists,
-  readGlobalCliVersion,
-  verifyShellCanFindCli,
-  showGettingStarted,
-});
+module.exports = run;
+module.exports.installFromPayload = installFromPayload;
+module.exports.mergeSettings = mergeSettings;