@hustle-together/api-dev-tools 3.11.1 → 3.12.1

package/bin/cli.js

@@ -1,19 +1,17 @@
 #!/usr/bin/env node
 
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const readline = require("readline");
 
 /**
- * API Development Tools Installer
+ * API Development Tools Installer v1.0.0
  *
- * Installs slash commands AND enforcement hooks for interview-driven API development.
- *
- * Features:
- *   - Slash commands in .claude/commands/
- *   - Python hooks for programmatic enforcement
- *   - Settings configuration for hook registration
- *   - State file template for progress tracking
+ * Interactive CLI installer with:
+ * - ASCII art branding
+ * - Progress indicators
+ * - Comprehensive file installation
  *
  * Usage: npx @hustle-together/api-dev-tools --scope=project
  *
@@ -21,916 +19,549 @@ const { execSync } = require('child_process');
  *   --with-storybook   Auto-initialize Storybook for component development
  *   --with-playwright  Auto-initialize Playwright for E2E testing
  *   --with-sandpack    Auto-install Sandpack for live UI previews
+ *   --silent           Skip banner and reduce output
  */
 
-// Parse command-line arguments
-const args = process.argv.slice(2);
-const scope = args.find(arg => arg.startsWith('--scope='))?.split('=')[1] || 'project';
-const withStorybook = args.includes('--with-storybook');
-const withPlaywright = args.includes('--with-playwright');
-const withSandpack = args.includes('--with-sandpack');
-
-// Colors for terminal output
-const colors = {
-  reset: '\x1b[0m',
-  bright: '\x1b[1m',
-  green: '\x1b[32m',
-  blue: '\x1b[34m',
-  yellow: '\x1b[33m',
-  red: '\x1b[31m',
-  cyan: '\x1b[36m',
+// ═══════════════════════════════════════════════════════════════════════════
+// ANSI Colors (red/black/white branding)
+// ═══════════════════════════════════════════════════════════════════════════
+
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
 };
 
-function log(message, color = 'reset') {
-  console.log(`${colors[color]}${message}${colors.reset}`);
+// ═══════════════════════════════════════════════════════════════════════════
+// ASCII Art Banner
+// ═══════════════════════════════════════════════════════════════════════════
+
+const BANNER = `
+${c.red}    ╔═══════════════════════════════════════════════════════════════╗
+    ║                                                               ║
+    ║     ██╗  ██╗██╗   ██╗███████╗████████╗██╗     ███████╗       ║
+    ║     ██║  ██║██║   ██║██╔════╝╚══██╔══╝██║     ██╔════╝       ║
+    ║     ███████║██║   ██║███████╗   ██║   ██║     █████╗         ║
+    ║     ██╔══██║██║   ██║╚════██║   ██║   ██║     ██╔══╝         ║
+    ║     ██║  ██║╚██████╔╝███████║   ██║   ███████╗███████╗       ║
+    ║     ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝   ╚══════╝╚══════╝       ║
+    ║                                                               ║
+    ╚═══════════════════════════════════════════════════════════════╝${c.reset}
+
+${c.bold}              API Development Tools for Claude Code${c.reset}
+${c.dim}        Interview-driven, research-first API development${c.reset}
+                        ${c.gray}v1.0.0${c.reset}
+`;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Spinner Animation
+// ═══════════════════════════════════════════════════════════════════════════
+
+const spinnerFrames = ["◐", "◓", "◑", "◒"];
+let spinnerIndex = 0;
+let spinnerInterval = null;
+
+function startSpinner(message) {
+  process.stdout.write(`\r${c.gray}${spinnerFrames[0]}${c.reset} ${message}`);
+  spinnerInterval = setInterval(() => {
+    spinnerIndex = (spinnerIndex + 1) % spinnerFrames.length;
+    process.stdout.write(
+      `\r${c.gray}${spinnerFrames[spinnerIndex]}${c.reset} ${message}`,
+    );
+  }, 100);
 }
 
-/**
- * Check if Python 3 is available
- */
-function checkPython() {
-  const pythonCommands = ['python3', 'python'];
-
-  for (const cmd of pythonCommands) {
-    try {
-      const version = execSync(`${cmd} --version 2>&1`, { encoding: 'utf8' }).trim();
-      if (version.includes('Python 3')) {
-        return { available: true, command: cmd, version };
-      }
-    } catch (e) {
-      // Command not found, try next
-    }
+function stopSpinner(success, message) {
+  if (spinnerInterval) {
+    clearInterval(spinnerInterval);
+    spinnerInterval = null;
   }
+  const icon = success ? `${c.white}●${c.reset}` : `${c.red}○${c.reset}`;
+  process.stdout.write(`\r${icon} ${message}\n`);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Logging Utilities
+// ═══════════════════════════════════════════════════════════════════════════
 
-  return { available: false, command: null, version: null };
+function log(message) {
+  console.log(message);
 }
 
-/**
- * Verify installation was successful
- */
-function verifyInstallation(claudeDir, hooksDir) {
-  const checks = [
-    { path: path.join(claudeDir, 'commands'), name: 'Commands directory' },
-    { path: path.join(claudeDir, 'settings.json'), name: 'Settings file' },
-    { path: path.join(claudeDir, 'api-dev-state.json'), name: 'State file' },
-    { path: path.join(claudeDir, 'registry.json'), name: 'Registry file' },
-    { path: path.join(claudeDir, 'performance-budgets.json'), name: 'Performance budgets' },
-    { path: path.join(claudeDir, 'research'), name: 'Research cache directory' },
-    { path: path.join(claudeDir, 'research', 'index.json'), name: 'Research index' },
-  ];
+function logStep(step, total, message) {
+  const progress = `${c.dim}[${step}/${total}]${c.reset}`;
+  console.log(`\n${progress} ${c.bold}${message}${c.reset}`);
+}
 
-  // Add hook checks if hooks directory exists (v3.0 has 18 hooks for 100% phase enforcement with user checkpoints)
-  if (fs.existsSync(hooksDir)) {
-    checks.push(
-      // Core utility hooks (5)
-      { path: path.join(hooksDir, 'session-startup.py'), name: 'session-startup.py' },
-      { path: path.join(hooksDir, 'enforce-external-research.py'), name: 'enforce-external-research.py' },
-      { path: path.join(hooksDir, 'track-tool-use.py'), name: 'track-tool-use.py' },
-      { path: path.join(hooksDir, 'periodic-reground.py'), name: 'periodic-reground.py' },
-      { path: path.join(hooksDir, 'api-workflow-check.py'), name: 'api-workflow-check.py' },
-      // Phase enforcement hooks with user checkpoints (12 - one per phase)
-      { path: path.join(hooksDir, 'enforce-disambiguation.py'), name: 'enforce-disambiguation.py' },
-      { path: path.join(hooksDir, 'enforce-scope.py'), name: 'enforce-scope.py' },
-      { path: path.join(hooksDir, 'enforce-research.py'), name: 'enforce-research.py' },
-      { path: path.join(hooksDir, 'enforce-interview.py'), name: 'enforce-interview.py' },
-      { path: path.join(hooksDir, 'enforce-deep-research.py'), name: 'enforce-deep-research.py' },
-      { path: path.join(hooksDir, 'enforce-schema.py'), name: 'enforce-schema.py' },
-      { path: path.join(hooksDir, 'enforce-environment.py'), name: 'enforce-environment.py' },
-      { path: path.join(hooksDir, 'enforce-tdd-red.py'), name: 'enforce-tdd-red.py' },
-      { path: path.join(hooksDir, 'verify-implementation.py'), name: 'verify-implementation.py' },
-      { path: path.join(hooksDir, 'verify-after-green.py'), name: 'verify-after-green.py' },
-      { path: path.join(hooksDir, 'enforce-verify.py'), name: 'enforce-verify.py' },
-      { path: path.join(hooksDir, 'enforce-refactor.py'), name: 'enforce-refactor.py' },
-      { path: path.join(hooksDir, 'enforce-documentation.py'), name: 'enforce-documentation.py' },
-      { path: path.join(hooksDir, 'update-registry.py'), name: 'update-registry.py' }
-    );
-  }
+function logSuccess(message) {
+  console.log(`  ${c.white}●${c.reset} ${message}`);
+}
 
-  const failures = [];
-  for (const check of checks) {
-    if (!fs.existsSync(check.path)) {
-      failures.push(check.name);
-    }
-  }
+function logInfo(message) {
+  console.log(`  ${c.gray}○${c.reset} ${message}`);
+}
+
+function logWarn(message) {
+  console.log(`  ${c.red}◆${c.reset} ${message}`);
+}
 
-  return { success: failures.length === 0, failures };
+function logError(message) {
+  console.log(`  ${c.red}✗${c.reset} ${message}`);
 }
 
-function main() {
-  log('\n🚀 Installing API Development Tools for Claude Code...\n', 'bright');
+// ═══════════════════════════════════════════════════════════════════════════
+// File Copy Utilities
+// ═══════════════════════════════════════════════════════════════════════════
 
-  // Check Python availability first
-  const python = checkPython();
-  if (!python.available) {
-    log('⚠️  Warning: Python 3 not found', 'yellow');
-    log('   Enforcement hooks require Python 3 to run.', 'yellow');
-    log('   Hooks will be installed but may not work until Python 3 is available.', 'yellow');
-    log('   Install Python 3: https://www.python.org/downloads/\n', 'yellow');
-  } else {
-    log(`✅ Found ${python.version}`, 'green');
-  }
+function copyDir(src, dest, options = {}) {
+  const { filter = () => true, overwrite = false } = options;
+  let copied = 0;
 
-  // Get target directory (where user ran the command)
-  const targetDir = process.cwd();
-  const claudeDir = path.join(targetDir, '.claude');
-  const commandsDir = path.join(claudeDir, 'commands');
-  const hooksDir = path.join(claudeDir, 'hooks');
+  if (!fs.existsSync(src)) return copied;
 
-  // Get source directories from this package
-  const packageDir = path.dirname(__dirname);
-  const sourceCommandsDir = path.join(packageDir, 'commands');
-  const sourceHooksDir = path.join(packageDir, 'hooks');
-  const sourceTemplatesDir = path.join(packageDir, 'templates');
-
-  // Verify source commands exist
-  if (!fs.existsSync(sourceCommandsDir)) {
-    log('❌ Error: Commands directory not found in package', 'red');
-    log(`   Looking for: ${sourceCommandsDir}`, 'red');
-    process.exit(1);
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
   }
 
-  // ========================================
-  // 1. Install Commands
-  // ========================================
-  if (!fs.existsSync(commandsDir)) {
-    log(`📁 Creating directory: ${commandsDir}`, 'blue');
-    fs.mkdirSync(commandsDir, { recursive: true });
-  }
+  const entries = fs.readdirSync(src, { withFileTypes: true });
 
-  const commandFiles = fs.readdirSync(sourceCommandsDir).filter(file =>
-    file.endsWith('.md')
-  );
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
 
-  if (commandFiles.length === 0) {
-    log('⚠️  Warning: No command files found to install', 'yellow');
-  } else {
-    log('📦 Installing commands:', 'blue');
-    commandFiles.forEach(file => {
-      const source = path.join(sourceCommandsDir, file);
-      const dest = path.join(commandsDir, file);
+    if (!filter(entry.name, srcPath)) continue;
 
-      try {
-        fs.copyFileSync(source, dest);
-        log(`   ✅ ${file}`, 'green');
-      } catch (error) {
-        log(`   ❌ Failed to copy ${file}: ${error.message}`, 'red');
+    if (entry.isDirectory()) {
+      copied += copyDir(srcPath, destPath, options);
+    } else {
+      if (!fs.existsSync(destPath) || overwrite) {
+        fs.copyFileSync(srcPath, destPath);
+        copied++;
       }
-    });
+    }
   }
 
-  // ========================================
-  // 2. Install Hooks (Programmatic Enforcement)
-  // ========================================
-  if (fs.existsSync(sourceHooksDir)) {
-    if (!fs.existsSync(hooksDir)) {
-      log(`\n📁 Creating directory: ${hooksDir}`, 'blue');
-      fs.mkdirSync(hooksDir, { recursive: true });
-    }
+  return copied;
+}
 
-    const hookFiles = fs.readdirSync(sourceHooksDir).filter(file =>
-      file.endsWith('.py')
-    );
+function copyFile(src, dest, options = {}) {
+  const { overwrite = false, executable = false } = options;
 
-    if (hookFiles.length > 0) {
-      log('\n🔒 Installing enforcement hooks:', 'cyan');
-      hookFiles.forEach(file => {
-        const source = path.join(sourceHooksDir, file);
-        const dest = path.join(hooksDir, file);
-
-        try {
-          fs.copyFileSync(source, dest);
-          // Make executable
-          fs.chmodSync(dest, '755');
-          log(`   ✅ ${file}`, 'green');
-        } catch (error) {
-          log(`   ❌ Failed to copy ${file}: ${error.message}`, 'red');
-        }
-      });
+  if (!fs.existsSync(src)) return false;
 
-      log('\n   Hook purposes:', 'blue');
-      log('   • enforce-research.py  - Blocks code writing without research', 'blue');
-      log('   • track-tool-use.py    - Logs all research activity', 'blue');
-      log('   • api-workflow-check.py - Prevents stopping until complete', 'blue');
-    }
+  const destDir = path.dirname(dest);
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
   }
 
-  // ========================================
-  // 3. Install/Merge Settings (Hook Registration)
-  // ========================================
-  const settingsSource = path.join(sourceTemplatesDir, 'settings.json');
-  const settingsDest = path.join(claudeDir, 'settings.json');
-
-  if (fs.existsSync(settingsSource)) {
-    log('\n⚙️  Configuring hook settings:', 'cyan');
-
-    try {
-      const newSettings = JSON.parse(fs.readFileSync(settingsSource, 'utf8'));
-
-      if (fs.existsSync(settingsDest)) {
-        // Merge with existing settings
-        const existingSettings = JSON.parse(fs.readFileSync(settingsDest, 'utf8'));
-        const mergedSettings = mergeSettings(existingSettings, newSettings);
-        fs.writeFileSync(settingsDest, JSON.stringify(mergedSettings, null, 2));
-        log('   ✅ Merged with existing settings.json', 'green');
-      } else {
-        // Create new settings file
-        fs.writeFileSync(settingsDest, JSON.stringify(newSettings, null, 2));
-        log('   ✅ Created settings.json with hook configuration', 'green');
-      }
-    } catch (error) {
-      log(`   ❌ Failed to configure settings: ${error.message}`, 'red');
+  if (!fs.existsSync(dest) || overwrite) {
+    fs.copyFileSync(src, dest);
+    if (executable) {
+      fs.chmodSync(dest, "755");
     }
+    return true;
   }
+  return false;
+}
 
-  // ========================================
-  // 4. Install State File Template
-  // ========================================
-  const stateSource = path.join(sourceTemplatesDir, 'api-dev-state.json');
-  const stateDest = path.join(claudeDir, 'api-dev-state.json');
-
-  if (fs.existsSync(stateSource)) {
-    log('\n📊 Setting up state tracking:', 'cyan');
+// ═══════════════════════════════════════════════════════════════════════════
+// Check Prerequisites
+// ═══════════════════════════════════════════════════════════════════════════
 
-    if (!fs.existsSync(stateDest)) {
-      try {
-        fs.copyFileSync(stateSource, stateDest);
-        log('   ✅ Created api-dev-state.json template', 'green');
-      } catch (error) {
-        log(`   ❌ Failed to create state file: ${error.message}`, 'red');
+function checkPython() {
+  const commands = ["python3", "python"];
+  for (const cmd of commands) {
+    try {
+      const version = execSync(`${cmd} --version 2>&1`, {
+        encoding: "utf8",
+      }).trim();
+      if (version.includes("Python 3")) {
+        return { ok: true, cmd, version };
       }
-    } else {
-      log('   ℹ️  State file already exists (preserved)', 'blue');
+    } catch (e) {
+      // Continue to next command
     }
   }
+  return { ok: false };
+}
 
-  // ========================================
-  // 4b. Install Registry (v3.8.0)
-  // ========================================
-  const registrySource = path.join(sourceTemplatesDir, 'registry.json');
-  const registryDest = path.join(claudeDir, 'registry.json');
-
-  if (fs.existsSync(registrySource)) {
-    log('\n📋 Setting up central registry:', 'cyan');
+function checkNode() {
+  try {
+    const version = process.version;
+    const major = parseInt(version.slice(1).split(".")[0], 10);
+    return { ok: major >= 18, version };
+  } catch (e) {
+    return { ok: false };
+  }
+}
 
-    if (!fs.existsSync(registryDest)) {
-      try {
-        fs.copyFileSync(registrySource, registryDest);
-        log('   ✅ Created registry.json (tracks APIs, components, pages)', 'green');
-      } catch (error) {
-        log(`   ❌ Failed to create registry: ${error.message}`, 'red');
-      }
-    } else {
-      log('   ℹ️  Registry already exists (preserved)', 'blue');
-    }
+// ═══════════════════════════════════════════════════════════════════════════
+// Main Installation
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function main() {
+  // Parse arguments
+  const args = process.argv.slice(2);
+  const withStorybook = args.includes("--with-storybook");
+  const withPlaywright = args.includes("--with-playwright");
+  const withSandpack = args.includes("--with-sandpack");
+  const silent = args.includes("--silent") || args.includes("-s");
+
+  // Show banner
+  if (!silent) {
+    console.clear();
+    log(BANNER);
   }
 
-  // ========================================
-  // 4c. Install Brand Guide Template (v3.9.0)
-  // ========================================
-  const brandGuideSource = path.join(sourceTemplatesDir, 'BRAND_GUIDE.md');
-  const brandGuideDest = path.join(claudeDir, 'BRAND_GUIDE.md');
+  // Directory setup
+  const targetDir = process.cwd();
+  const packageDir = path.dirname(__dirname);
+  const claudeDir = path.join(targetDir, ".claude");
+  const hooksDir = path.join(targetDir, "hooks");
 
-  if (fs.existsSync(brandGuideSource)) {
-    log('\n🎨 Setting up brand guide:', 'cyan');
+  const totalSteps = 8;
+  let currentStep = 0;
 
-    if (!fs.existsSync(brandGuideDest)) {
-      try {
-        fs.copyFileSync(brandGuideSource, brandGuideDest);
-        log('   ✅ Created BRAND_GUIDE.md (customize for your project branding)', 'green');
-      } catch (error) {
-        log(`   ❌ Failed to create brand guide: ${error.message}`, 'red');
-      }
-    } else {
-      log('   ℹ️  Brand guide already exists (preserved)', 'blue');
-    }
-  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 1: Check Prerequisites
+  // ─────────────────────────────────────────────────────────────────────────
 
-  // ========================================
-  // 4d. Install Performance Budgets (v3.9.0)
-  // ========================================
-  const perfBudgetsSource = path.join(sourceTemplatesDir, 'performance-budgets.json');
-  const perfBudgetsDest = path.join(claudeDir, 'performance-budgets.json');
+  logStep(++currentStep, totalSteps, "Checking prerequisites");
 
-  if (fs.existsSync(perfBudgetsSource)) {
-    log('\n📊 Setting up performance budgets:', 'cyan');
+  const node = checkNode();
+  if (node.ok) {
+    logSuccess(`Node.js ${node.version}`);
+  } else {
+    logError(`Node.js 18+ required (found ${node.version || "none"})`);
+    process.exit(1);
+  }
 
-    if (!fs.existsSync(perfBudgetsDest)) {
-      try {
-        fs.copyFileSync(perfBudgetsSource, perfBudgetsDest);
-        log('   ✅ Created performance-budgets.json (thresholds for TDD gates)', 'green');
-      } catch (error) {
-        log(`   ❌ Failed to create performance budgets: ${error.message}`, 'red');
-      }
-    } else {
-      log('   ℹ️  Performance budgets already exist (preserved)', 'blue');
-    }
+  const python = checkPython();
+  if (python.ok) {
+    logSuccess(`${python.version}`);
+  } else {
+    logWarn("Python 3 not found - hooks may not work");
+    logInfo("Install: https://www.python.org/downloads/");
   }
 
-  // ========================================
-  // 4e. Install Research Cache Structure (v3.0)
-  // ========================================
-  const researchDir = path.join(claudeDir, 'research');
-  const researchIndexSource = path.join(sourceTemplatesDir, 'research-index.json');
-  const researchIndexDest = path.join(researchDir, 'index.json');
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 2: Install Commands
+  // ─────────────────────────────────────────────────────────────────────────
 
-  log('\n📚 Setting up research cache:', 'cyan');
+  logStep(++currentStep, totalSteps, "Installing slash commands");
 
-  if (!fs.existsSync(researchDir)) {
-    try {
-      fs.mkdirSync(researchDir, { recursive: true });
-      log('   ✅ Created .claude/research/ directory', 'green');
-    } catch (error) {
-      log(`   ❌ Failed to create research directory: ${error.message}`, 'red');
-    }
-  }
+  const commandsDir = path.join(claudeDir, "commands");
+  const sourceCommandsDir = path.join(packageDir, "commands");
 
-  if (fs.existsSync(researchIndexSource) && !fs.existsSync(researchIndexDest)) {
-    try {
-      fs.copyFileSync(researchIndexSource, researchIndexDest);
-      log('   ✅ Created research/index.json for freshness tracking', 'green');
-    } catch (error) {
-      log(`   ❌ Failed to create research index: ${error.message}`, 'red');
-    }
-  } else if (fs.existsSync(researchIndexDest)) {
-    log('   ℹ️  Research index already exists (preserved)', 'blue');
+  if (!fs.existsSync(commandsDir)) {
+    fs.mkdirSync(commandsDir, { recursive: true });
   }
 
-  // ========================================
-  // 4c. Install Test UI (Parser API + Page)
-  // ========================================
-  log('\n🧪 Setting up Test UI:', 'cyan');
-
-  const testUiSourceDir = path.join(sourceTemplatesDir, 'api-test');
-  const hasNextJs = fs.existsSync(path.join(targetDir, 'next.config.js')) ||
-                    fs.existsSync(path.join(targetDir, 'next.config.mjs')) ||
-                    fs.existsSync(path.join(targetDir, 'next.config.ts'));
-
-  // Detect App Router structure (used by Test UI and Showcase Pages)
-  const appDir = fs.existsSync(path.join(targetDir, 'src', 'app'))
-    ? path.join(targetDir, 'src', 'app')
-    : fs.existsSync(path.join(targetDir, 'app'))
-      ? path.join(targetDir, 'app')
-      : null;
-
-  if (!hasNextJs) {
-    log('   ⚠️  Next.js not detected - skipping Test UI installation', 'yellow');
-    log('   💡 Test UI requires Next.js App Router', 'yellow');
-  } else if (fs.existsSync(testUiSourceDir)) {
-
-    if (!appDir) {
-      log('   ⚠️  App Router not detected - skipping Test UI installation', 'yellow');
-      log('   💡 Test UI requires Next.js App Router (app/ or src/app/)', 'yellow');
-    } else {
-      // Install test-structure API route
-      const apiTestStructureDir = path.join(appDir, 'api', 'test-structure');
-      const apiTestStructureSource = path.join(testUiSourceDir, 'test-structure', 'route.ts');
-      const apiTestStructureDest = path.join(apiTestStructureDir, 'route.ts');
+  const commandsCopied = copyDir(sourceCommandsDir, commandsDir, {
+    filter: (name) => name.endsWith(".md"),
+  });
 
-      if (!fs.existsSync(apiTestStructureDir)) {
-        fs.mkdirSync(apiTestStructureDir, { recursive: true });
-      }
+  logSuccess(`${commandsCopied} commands installed to .claude/commands/`);
 
-      if (!fs.existsSync(apiTestStructureDest)) {
-        try {
-          fs.copyFileSync(apiTestStructureSource, apiTestStructureDest);
-          log('   ✅ Created /api/test-structure route (parses Vitest files)', 'green');
-        } catch (error) {
-          log(`   ❌ Failed to create test-structure API: ${error.message}`, 'red');
-        }
-      } else {
-        log('   ℹ️  /api/test-structure already exists (preserved)', 'blue');
-      }
-
-      // Install test UI page
-      const apiTestPageDir = path.join(appDir, 'api-test');
-      const apiTestPageSource = path.join(testUiSourceDir, 'page.tsx');
-      const apiTestPageDest = path.join(apiTestPageDir, 'page.tsx');
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 3: Install Hooks
+  // ─────────────────────────────────────────────────────────────────────────
 
-      if (!fs.existsSync(apiTestPageDir)) {
-        fs.mkdirSync(apiTestPageDir, { recursive: true });
-      }
+  logStep(++currentStep, totalSteps, "Installing enforcement hooks");
 
-      if (!fs.existsSync(apiTestPageDest)) {
-        try {
-          fs.copyFileSync(apiTestPageSource, apiTestPageDest);
-          log('   ✅ Created /api-test page (displays test structure)', 'green');
-        } catch (error) {
-          log(`   ❌ Failed to create test UI page: ${error.message}`, 'red');
-        }
-      } else {
-        log('   ℹ️  /api-test page already exists (preserved)', 'blue');
-      }
+  const sourceHooksDir = path.join(packageDir, "hooks");
 
-      log('   💡 Test UI available at http://localhost:3000/api-test', 'yellow');
-    }
-  } else {
-    log('   ⚠️  Test UI templates not found in package', 'yellow');
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
   }
 
-  // ========================================
-  // 4f. Install Showcase Pages (v3.9.2)
-  // ========================================
-  log('\n🎨 Setting up showcase pages:', 'cyan');
-
-  if (hasNextJs && appDir) {
-    const showcaseTemplates = [
-      // Shared components first (required by other pages)
-      {
-        source: 'shared',
-        dest: path.join(appDir, 'shared'),
-        files: ['HeroHeader.tsx', 'index.ts'],
-        name: 'Shared components (HeroHeader)'
-      },
-      // API Showcase
-      {
-        source: 'api-showcase',
-        dest: path.join(appDir, 'api-showcase'),
-        files: ['page.tsx'],
-        componentsDir: '_components',
-        componentFiles: ['APIShowcase.tsx', 'APICard.tsx', 'APIModal.tsx', 'APITester.tsx'],
-        name: 'API Showcase'
-      },
-      // UI Showcase
-      {
-        source: 'ui-showcase',
-        dest: path.join(appDir, 'ui-showcase'),
-        files: ['page.tsx'],
-        componentsDir: '_components',
-        componentFiles: ['UIShowcase.tsx', 'PreviewCard.tsx', 'PreviewModal.tsx'],
-        name: 'UI Showcase'
-      },
-      // Dev Tools Landing
-      {
-        source: 'dev-tools',
-        dest: path.join(appDir, 'dev-tools'),
-        files: ['page.tsx'],
-        componentsDir: '_components',
-        componentFiles: ['DevToolsLanding.tsx'],
-        name: 'Dev Tools Landing'
-      }
-    ];
-
-    for (const template of showcaseTemplates) {
-      const sourceDir = path.join(sourceTemplatesDir, template.source);
+  // Copy hooks lib directory first
+  const sourceHooksLibDir = path.join(sourceHooksDir, "lib");
+  const destHooksLibDir = path.join(hooksDir, "lib");
 
-      if (!fs.existsSync(sourceDir)) {
-        log(`   ⚠️  ${template.name} template not found`, 'yellow');
-        continue;
-      }
+  if (fs.existsSync(sourceHooksLibDir)) {
+    if (!fs.existsSync(destHooksLibDir)) {
+      fs.mkdirSync(destHooksLibDir, { recursive: true });
+    }
+    copyDir(sourceHooksLibDir, destHooksLibDir);
+  }
 
-      // Create destination directory
-      if (!fs.existsSync(template.dest)) {
-        fs.mkdirSync(template.dest, { recursive: true });
+  // Copy Python hook files
+  let hooksCopied = 0;
+  if (fs.existsSync(sourceHooksDir)) {
+    const hookFiles = fs
+      .readdirSync(sourceHooksDir)
+      .filter((f) => f.endsWith(".py"));
+
+    for (const file of hookFiles) {
+      const src = path.join(sourceHooksDir, file);
+      const dest = path.join(hooksDir, file);
+
+      if (!fs.existsSync(dest)) {
+        fs.copyFileSync(src, dest);
+        fs.chmodSync(dest, "755");
+        hooksCopied++;
       }
+    }
+  }
 
-      let installedFiles = [];
+  logSuccess(`${hooksCopied} hooks installed to hooks/`);
+  logInfo("Includes: enforce-*, notify-*, track-token-usage.py");
 
-      // Copy main files (page.tsx, etc.)
-      for (const file of template.files) {
-        const srcFile = path.join(sourceDir, file);
-        const destFile = path.join(template.dest, file);
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 4: Install Subagents
+  // ─────────────────────────────────────────────────────────────────────────
 
-        if (fs.existsSync(srcFile) && !fs.existsSync(destFile)) {
-          try {
-            fs.copyFileSync(srcFile, destFile);
-            installedFiles.push(file);
-          } catch (error) {
-            log(`   ❌ Failed to copy ${file}: ${error.message}`, 'red');
-          }
-        }
-      }
+  logStep(++currentStep, totalSteps, "Installing subagents");
 
-      // Copy _components directory if exists
-      if (template.componentsDir && template.componentFiles) {
-        const srcComponentsDir = path.join(sourceDir, template.componentsDir);
-        const destComponentsDir = path.join(template.dest, template.componentsDir);
-
-        if (fs.existsSync(srcComponentsDir)) {
-          if (!fs.existsSync(destComponentsDir)) {
-            fs.mkdirSync(destComponentsDir, { recursive: true });
-          }
-
-          for (const file of template.componentFiles) {
-            const srcFile = path.join(srcComponentsDir, file);
-            const destFile = path.join(destComponentsDir, file);
-
-            if (fs.existsSync(srcFile) && !fs.existsSync(destFile)) {
-              try {
-                fs.copyFileSync(srcFile, destFile);
-                installedFiles.push(`_components/${file}`);
-              } catch (error) {
-                log(`   ❌ Failed to copy ${file}: ${error.message}`, 'red');
-              }
-            }
-          }
-        }
-      }
+  const agentsDir = path.join(claudeDir, "agents");
+  const sourceAgentsDir = path.join(packageDir, ".claude", "agents");
 
-      if (installedFiles.length > 0) {
-        log(`   ✅ ${template.name} (${installedFiles.length} files)`, 'green');
-      } else {
-        log(`   ℹ️  ${template.name} already exists (preserved)`, 'blue');
-      }
-    }
-
-    log('\n   💡 Showcase pages available at:', 'yellow');
-    log('      /dev-tools     - Landing page with all dev tools', 'yellow');
-    log('      /api-showcase  - Interactive API testing', 'yellow');
-    log('      /ui-showcase   - Live component previews', 'yellow');
-  } else {
-    log('   ⚠️  Next.js App Router not detected - skipping showcase pages', 'yellow');
+  if (!fs.existsSync(agentsDir)) {
+    fs.mkdirSync(agentsDir, { recursive: true });
   }
 
-  // ========================================
-  // 4g. Install Component/Page Templates (v3.9.0)
-  // ========================================
-  log('\n📦 Setting up component/page templates:', 'cyan');
+  const agentsCopied = copyDir(sourceAgentsDir, agentsDir, {
+    filter: (name) => name.endsWith(".md"),
+  });
 
-  const componentPageTemplates = [
-    {
-      source: 'component',
-      dest: path.join(claudeDir, 'templates', 'component'),
-      name: 'Component templates'
-    },
-    {
-      source: 'page',
-      dest: path.join(claudeDir, 'templates', 'page'),
-      name: 'Page templates'
-    }
-  ];
+  logSuccess(`${agentsCopied} subagents installed to .claude/agents/`);
+  logInfo("Haiku: parallel-researcher, research-validator, docs-generator");
+  logInfo(
+    "Sonnet: schema-generator, test-writer, implementation-reviewer, code-reviewer",
+  );
 
-  for (const template of componentPageTemplates) {
-    const sourceDir = path.join(sourceTemplatesDir, template.source);
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 5: Install Configuration Files
+  // ─────────────────────────────────────────────────────────────────────────
 
-    if (!fs.existsSync(sourceDir)) {
-      log(`   ⚠️  ${template.name} not found`, 'yellow');
-      continue;
-    }
-
-    if (!fs.existsSync(template.dest)) {
-      fs.mkdirSync(template.dest, { recursive: true });
-    }
+  logStep(++currentStep, totalSteps, "Setting up configuration");
 
-    const files = fs.readdirSync(sourceDir);
-    let copiedCount = 0;
+  const sourceTemplatesDir = path.join(packageDir, "templates");
 
-    for (const file of files) {
-      const srcFile = path.join(sourceDir, file);
-      const destFile = path.join(template.dest, file);
+  // Settings
+  const settingsSource = path.join(sourceTemplatesDir, "settings.json");
+  const settingsDest = path.join(claudeDir, "settings.json");
 
-      if (fs.statSync(srcFile).isFile() && !fs.existsSync(destFile)) {
-        try {
-          fs.copyFileSync(srcFile, destFile);
-          copiedCount++;
-        } catch (error) {
-          log(`   ❌ Failed to copy ${file}: ${error.message}`, 'red');
-        }
+  if (fs.existsSync(settingsSource)) {
+    if (fs.existsSync(settingsDest)) {
+      // Merge settings
+      try {
+        const existing = JSON.parse(fs.readFileSync(settingsDest, "utf8"));
+        const newSettings = JSON.parse(fs.readFileSync(settingsSource, "utf8"));
+        const merged = mergeSettings(existing, newSettings);
+        fs.writeFileSync(settingsDest, JSON.stringify(merged, null, 2));
+        logSuccess("Merged settings.json");
+      } catch (e) {
+        logWarn("Could not merge settings.json");
       }
-    }
-
-    if (copiedCount > 0) {
-      log(`   ✅ ${template.name} (${copiedCount} files)`, 'green');
     } else {
-      log(`   ℹ️  ${template.name} already exists (preserved)`, 'blue');
+      copyFile(settingsSource, settingsDest);
+      logSuccess("Created settings.json");
     }
   }
 
-  // ========================================
-  // 4h. Install Manifest Generation Scripts
-  // ========================================
-  log('\n📊 Setting up manifest generation scripts:', 'cyan');
+  // State file
+  const stateSource = path.join(sourceTemplatesDir, "api-dev-state.json");
+  const stateDest = path.join(claudeDir, "api-dev-state.json");
 
-  const sourceScriptsDir = path.join(packageDir, 'scripts');
-  const targetScriptsDir = path.join(targetDir, 'scripts', 'api-dev-tools');
+  if (!fs.existsSync(stateDest) && fs.existsSync(stateSource)) {
+    copyFile(stateSource, stateDest);
+    logSuccess("Created api-dev-state.json");
+  } else if (fs.existsSync(stateDest)) {
+    logInfo("State file preserved");
+  }
 
-  if (fs.existsSync(sourceScriptsDir)) {
-    if (!fs.existsSync(targetScriptsDir)) {
-      fs.mkdirSync(targetScriptsDir, { recursive: true });
+  // Registry
+  const registrySource = path.join(sourceTemplatesDir, "registry.json");
+  const registryDest = path.join(claudeDir, "registry.json");
+
+  if (!fs.existsSync(registryDest) && fs.existsSync(registrySource)) {
+    copyFile(registrySource, registryDest);
+    logSuccess("Created registry.json");
+  }
+
+  // Research cache
+  const researchDir = path.join(claudeDir, "research");
+  if (!fs.existsSync(researchDir)) {
+    fs.mkdirSync(researchDir, { recursive: true });
+    const indexSource = path.join(sourceTemplatesDir, "research-index.json");
+    if (fs.existsSync(indexSource)) {
+      copyFile(indexSource, path.join(researchDir, "index.json"));
     }
+    logSuccess("Created research cache");
+  }
 
-    const scriptFiles = fs.readdirSync(sourceScriptsDir).filter(file =>
-      file.endsWith('.ts')
-    );
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 6: Install Environment Template
+  // ─────────────────────────────────────────────────────────────────────────
 
-    if (scriptFiles.length > 0) {
-      scriptFiles.forEach(file => {
-        const source = path.join(sourceScriptsDir, file);
-        const dest = path.join(targetScriptsDir, file);
+  logStep(++currentStep, totalSteps, "Setting up environment");
 
-        try {
-          fs.copyFileSync(source, dest);
-          log(`   ✅ ${file}`, 'green');
-        } catch (error) {
-          log(`   ❌ Failed to copy ${file}: ${error.message}`, 'red');
-        }
-      });
+  const templatesDestDir = path.join(targetDir, "templates");
+  if (!fs.existsSync(templatesDestDir)) {
+    fs.mkdirSync(templatesDestDir, { recursive: true });
+  }
 
-      log('\n   Script purposes:', 'blue');
-      log('   • generate-test-manifest.ts - Parses tests → manifest (NO LLM)', 'blue');
-      log('   • extract-parameters.ts     - Extracts Zod params → matrix', 'blue');
-      log('   • collect-test-results.ts   - Runs Vitest → results JSON', 'blue');
-      log('\n   💡 Scripts run automatically after tests pass (Phase 8 → 9)', 'yellow');
-      log('   💡 Manual: npx tsx scripts/api-dev-tools/generate-test-manifest.ts', 'yellow');
-    }
-  } else {
-    log('   ⚠️  Scripts directory not found in package', 'yellow');
+  const envSource = path.join(sourceTemplatesDir, ".env.example");
+  const envDest = path.join(templatesDestDir, ".env.example");
+
+  if (fs.existsSync(envSource)) {
+    copyFile(envSource, envDest, { overwrite: true });
+    logSuccess("Created templates/.env.example");
+    logInfo("Copy to .env and configure your API keys");
   }
 
-  // ========================================
-  // 5. Install MCP Servers via CLI (Context7, GitHub)
-  // ========================================
-  // NOTE: We use `claude mcp add` directly because .mcp.json requires manual approval
-  // and doesn't auto-load. Using the CLI ensures servers are immediately available.
-  log('\n🔌 Configuring MCP servers:', 'cyan');
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 7: Configure MCP Servers
+  // ─────────────────────────────────────────────────────────────────────────
 
-  const { execSync } = require('child_process');
+  logStep(++currentStep, totalSteps, "Configuring MCP servers");
 
   const mcpServers = [
-    { name: 'context7', command: 'npx -y @upstash/context7-mcp', description: 'Live documentation from library source code' },
-    { name: 'github', command: 'npx -y @modelcontextprotocol/server-github', description: 'GitHub issues, PRs, and repository access' }
+    { name: "context7", cmd: "npx -y @upstash/context7-mcp" },
+    { name: "github", cmd: "npx -y @modelcontextprotocol/server-github" },
+    {
+      name: "greptile",
+      cmd: "npx -y @anthropics/mcp-greptile",
+      optional: true,
+    },
   ];
 
   for (const server of mcpServers) {
     try {
-      // Check if server already exists
-      const checkResult = execSync(`claude mcp get ${server.name} 2>&1`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
-      if (checkResult.includes('Connected') || checkResult.includes('Scope:')) {
-        log(`   ✓ ${server.name} - already configured`, 'blue');
-      }
-    } catch (checkError) {
-      // Server doesn't exist, add it
+      execSync(`claude mcp get ${server.name} 2>&1`, {
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      logInfo(`${server.name} already configured`);
+    } catch (e) {
       try {
-        execSync(`claude mcp add ${server.name} -- ${server.command}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
-        log(`   ✅ ${server.name} - ${server.description}`, 'green');
-      } catch (addError) {
-        log(`   ⚠️  ${server.name} - Could not add (run manually: claude mcp add ${server.name} -- ${server.command})`, 'yellow');
+        execSync(`claude mcp add ${server.name} -- ${server.cmd}`, {
+          encoding: "utf8",
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+        logSuccess(`Added ${server.name}`);
+      } catch (addErr) {
+        if (server.optional) {
+          logInfo(
+            `${server.name} (optional) - configure with GREPTILE_API_KEY`,
+          );
+        } else {
+          logWarn(`Could not add ${server.name} - add manually`);
+        }
       }
     }
   }
 
-  log('\n   ⚠️  GitHub MCP requires GITHUB_PERSONAL_ACCESS_TOKEN in env', 'yellow');
-  log('   💡 Restart Claude Code for MCP tools to be available', 'yellow');
-
-  // ========================================
-  // 6. Update CLAUDE.md with workflow documentation
-  // ========================================
-  const claudeMdSection = path.join(sourceTemplatesDir, 'CLAUDE-SECTION.md');
-  const projectClaudeMd = path.join(targetDir, 'CLAUDE.md');
-
-  if (fs.existsSync(claudeMdSection)) {
-    log('\n📝 CLAUDE.md workflow documentation:', 'cyan');
-
-    const sectionContent = fs.readFileSync(claudeMdSection, 'utf8');
-    const sectionMarker = '## API Development Workflow (v3.0)';
-
-    if (fs.existsSync(projectClaudeMd)) {
-      const existingContent = fs.readFileSync(projectClaudeMd, 'utf8');
-
-      if (existingContent.includes(sectionMarker)) {
-        // Update existing section
-        const beforeSection = existingContent.split(sectionMarker)[0];
-        // Find the next ## heading or end of file
-        const afterMatch = existingContent.match(/## API Development Workflow[\s\S]*?((?=\n## )|$)/);
-        const afterSection = afterMatch ? existingContent.substring(existingContent.indexOf(afterMatch[0]) + afterMatch[0].length) : '';
-
-        fs.writeFileSync(projectClaudeMd, beforeSection + sectionContent + afterSection);
-        log('   ✅ Updated API Development Workflow section in CLAUDE.md', 'green');
-      } else {
-        // Append section
-        fs.appendFileSync(projectClaudeMd, '\n\n' + sectionContent);
-        log('   ✅ Added API Development Workflow section to CLAUDE.md', 'green');
-      }
-    } else {
-      // Create new CLAUDE.md with section
-      fs.writeFileSync(projectClaudeMd, '# Project Instructions\n\n' + sectionContent);
-      log('   ✅ Created CLAUDE.md with API Development Workflow section', 'green');
-    }
-  }
+  logInfo("Greptile requires GREPTILE_API_KEY + GITHUB_TOKEN for Phase 14");
 
-  // ========================================
-  // 7. Install Optional Development Tools
-  // ========================================
-  if (withStorybook || withPlaywright || withSandpack) {
-    log('\n🔧 Installing optional development tools:', 'cyan');
+  // ─────────────────────────────────────────────────────────────────────────
+  // Step 8: Optional Tools
+  // ─────────────────────────────────────────────────────────────────────────
+
+  logStep(++currentStep, totalSteps, "Optional tools");
 
+  if (withStorybook || withPlaywright || withSandpack) {
     if (withSandpack) {
+      startSpinner("Installing Sandpack...");
       try {
-        log('   📦 Installing Sandpack for live component previews...', 'blue');
-        execSync('pnpm add @codesandbox/sandpack-react 2>&1', { cwd: targetDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
-        log('   ✅ Sandpack installed successfully', 'green');
-      } catch (error) {
-        // Try npm if pnpm fails
-        try {
-          execSync('npm install @codesandbox/sandpack-react 2>&1', { cwd: targetDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
-          log('   ✅ Sandpack installed successfully (via npm)', 'green');
-        } catch (npmError) {
-          log('   ⚠️  Could not install Sandpack automatically. Run manually:', 'yellow');
-          log('      pnpm add @codesandbox/sandpack-react', 'yellow');
-        }
+        execSync("npm install @codesandbox/sandpack-react 2>&1", {
+          cwd: targetDir,
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+        stopSpinner(true, "Sandpack installed");
+      } catch (e) {
+        stopSpinner(
+          false,
+          "Sandpack install failed - run: npm install @codesandbox/sandpack-react",
+        );
       }
     }
 
     if (withStorybook) {
+      startSpinner("Initializing Storybook (this takes a moment)...");
       try {
-        log('   📖 Initializing Storybook (this may take a moment)...', 'blue');
-        execSync('npx storybook@latest init --yes 2>&1', { cwd: targetDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 300000 });
-        log('   ✅ Storybook initialized successfully', 'green');
-        log('   💡 Run with: pnpm storybook', 'yellow');
-      } catch (error) {
-        log('   ⚠️  Storybook init failed. Run manually:', 'yellow');
-        log('      npx storybook@latest init', 'yellow');
+        execSync("npx storybook@latest init --yes 2>&1", {
+          cwd: targetDir,
+          stdio: ["pipe", "pipe", "pipe"],
+          timeout: 300000,
+        });
+        stopSpinner(true, "Storybook initialized");
+      } catch (e) {
+        stopSpinner(
+          false,
+          "Storybook init failed - run: npx storybook@latest init",
+        );
       }
     }
 
     if (withPlaywright) {
+      startSpinner("Initializing Playwright (this takes a moment)...");
       try {
-        log('   🎭 Initializing Playwright (this may take a moment)...', 'blue');
-        execSync('npm init playwright@latest -- --yes 2>&1', { cwd: targetDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 300000 });
-        log('   ✅ Playwright initialized successfully', 'green');
-        log('   💡 Run tests with: npx playwright test', 'yellow');
-      } catch (error) {
-        log('   ⚠️  Playwright init failed. Run manually:', 'yellow');
-        log('      npm init playwright@latest', 'yellow');
+        execSync("npm init playwright@latest -- --yes 2>&1", {
+          cwd: targetDir,
+          stdio: ["pipe", "pipe", "pipe"],
+          timeout: 300000,
+        });
+        stopSpinner(true, "Playwright initialized");
+      } catch (e) {
+        stopSpinner(
+          false,
+          "Playwright init failed - run: npm init playwright@latest",
+        );
       }
     }
+  } else {
+    logInfo("None selected");
+    logInfo(
+      "Add later with: --with-storybook --with-playwright --with-sandpack",
+    );
   }
 
-  // ========================================
-  // Success Summary
-  // ========================================
-  log('\n' + '═'.repeat(60), 'green');
-  log('🎉 API Development Tools v3.10.0 installed successfully!', 'green');
-  log('═'.repeat(60) + '\n', 'green');
-
-  log('📋 What was installed:', 'bright');
-  log('   Commands:  .claude/commands/*.md', 'blue');
-  log('   Hooks:     .claude/hooks/*.py (enforcement + user checkpoints)', 'blue');
-  log('   Settings:  .claude/settings.json', 'blue');
-  log('   State:     .claude/api-dev-state.json', 'blue');
-  log('   Registry:  .claude/registry.json (tracks APIs, components, pages)', 'blue');
-  log('   Brand:     .claude/BRAND_GUIDE.md (customize for your branding)', 'blue');
-  log('   Budgets:   .claude/performance-budgets.json (TDD gate thresholds)', 'blue');
-  log('   Research:  .claude/research/ (with freshness tracking)', 'blue');
-  log('   Scripts:   scripts/api-dev-tools/*.ts (manifest generation)', 'blue');
-  log('   MCP:       context7, github (via claude mcp add)', 'blue');
-  log('   Test UI:   /api-test page + /api/test-structure API (if Next.js)', 'blue');
-
-  log('\n🆕 New in v3.10.0:', 'bright');
-  log('   • Enhanced installer with detailed optional tools info', 'cyan');
-  log('   • UI workflow auto-prompts for Storybook/Playwright installation', 'cyan');
-  log('   • Demo JSONs updated for 13-phase workflow accuracy', 'cyan');
-  log('   • Animated 3D grid hero header on showcase pages', 'cyan');
-  log('   • Dev Tools landing page at /dev-tools', 'cyan');
-  log('   • Multi-endpoint API selector (e.g., /tts, /voices, /models)', 'cyan');
-  log('   • Audio playback for TTS/voice API responses', 'cyan');
-  log('   • Enhanced Hustle branding (#BA0C2F)', 'cyan');
-  log('   • Dark mode support throughout', 'cyan');
-
-  log('\n📦 v3.9.0 Features (included):', 'bright');
-  log('   • /hustle-ui-create command for components and pages', 'cyan');
-  log('   • UI Showcase page (grid + modal preview at /ui-showcase)', 'cyan');
-  log('   • API Showcase page (interactive testing at /api-showcase)', 'cyan');
-  log('   • Brand guide integration (.claude/BRAND_GUIDE.md)', 'cyan');
-  log('   • Performance budgets as TDD gates (memory, re-renders, timing)', 'cyan');
-  log('   • ShadCN component detection in src/components/ui/', 'cyan');
-  log('   • 4-step verification (responsive + brand + tests + memory)', 'cyan');
-  log('   • Storybook + Playwright testing templates with thresholds', 'cyan');
-
-  log('\n📦 v3.8.0 Features (included):', 'bright');
-  log('   • /hustle-combine command for API orchestration', 'cyan');
-  log('   • Central registry (registry.json) tracks all created elements', 'cyan');
-
-  log('\n🔒 User Checkpoint Enforcement:', 'bright');
-  log('   • Phase 1: "Which interpretation?" (disambiguation)', 'cyan');
-  log('   • Phase 2: "Scope correct?" (scope confirmation)', 'cyan');
-  log('   • Phase 3: "Proceed to interview?" (research summary)', 'cyan');
-  log('   • Phase 4: "Interview complete?" (all questions answered)', 'cyan');
-  log('   • Phase 5: "Approve searches?" (deep research proposal)', 'cyan');
-  log('   • Phase 6: "Schema matches interview?" (schema review)', 'cyan');
-  log('   • Phase 7: "Ready for testing?" (environment check)', 'cyan');
-  log('   • Phase 8: "Test plan looks good?" (test matrix)', 'cyan');
-  log('   • Phase 10: "Fix gaps?" (verification decision)', 'cyan');
-  log('   • Phase 12: "Documentation complete?" (final checklist)', 'cyan');
-
-  log('\n📚 Available Commands:', 'bright');
-  log('  API Development:', 'bright');
-  log('  /hustle-api-create [endpoint] - Complete 13-phase API workflow', 'blue');
-  log('  /hustle-combine [api|ui]      - Combine existing APIs into orchestration', 'blue');
-  log('  /hustle-api-interview [endpoint] - Questions FROM research', 'blue');
-  log('  /hustle-api-research [library]   - Adaptive propose-approve research', 'blue');
-  log('  /hustle-api-verify [endpoint]    - Manual Phase 10 verification', 'blue');
-  log('  /hustle-api-env [endpoint]       - Check API keys and environment', 'blue');
-  log('  /hustle-api-status [endpoint]    - Track 13-phase progress', 'blue');
-  log('', 'blue');
-  log('  UI Development:', 'bright');
-  log('  /hustle-ui-create [name]      - Create component or page (13-phase)', 'blue');
-  log('                                  • Brand guide integration', 'blue');
-  log('                                  • ShadCN component detection', 'blue');
-  log('                                  • 4-step verification', 'blue');
-  log('                                  • UI Showcase auto-update', 'blue');
-
-  log('\n🚀 Quick Start:', 'bright');
-  log('   API: /hustle-api-create my-endpoint', 'blue');
-  log('   UI:  /hustle-ui-create Button', 'blue');
-
-  log('\n💡 Check progress anytime:', 'yellow');
-  log('   cat .claude/api-dev-state.json | jq \'.phases\'', 'yellow');
-
-  log('\n📖 Documentation:', 'bright');
-  log(`   ${path.join(commandsDir, 'README.md')}\n`, 'blue');
-
-  log('\n🎨 Showcase Pages:', 'bright');
-  log('   /dev-tools     - Landing page with all dev tools', 'blue');
-  log('   /api-showcase  - Interactive API testing', 'blue');
-  log('   /ui-showcase   - Live component previews', 'blue');
-
-  // Enhanced Optional Development Tools Section
-  log('\n' + '─'.repeat(60), 'yellow');
-  log('📦 OPTIONAL DEVELOPMENT TOOLS', 'yellow');
-  log('─'.repeat(60), 'yellow');
-  log('   The following tools are OPTIONAL but enhance UI development.', 'bright');
-  log('   Install now with flags, or later when prompted during /hustle-ui-create.\n', 'bright');
-
-  log('   ┌──────────────────────────────────────────────────────────┐', 'cyan');
-  log('   │  STORYBOOK (Component Development)                       │', 'cyan');
-  log('   ├──────────────────────────────────────────────────────────┤', 'cyan');
-  log('   │  Size:      ~50MB                                        │', 'cyan');
-  log('   │  Purpose:   Visual component testing, interactive docs   │', 'cyan');
-  log('   │  Required:  /hustle-ui-create (component mode)           │', 'cyan');
-  log('   │  Without:   Cannot write .stories.tsx files              │', 'cyan');
-  log('   │  Install:   --with-storybook flag OR during UI workflow  │', 'cyan');
-  log('   │  Command:   npx storybook@latest init                    │', 'cyan');
-  log('   └──────────────────────────────────────────────────────────┘', 'cyan');
-
-  log('   ┌──────────────────────────────────────────────────────────┐', 'magenta');
-  log('   │  PLAYWRIGHT (E2E Testing)                                │', 'magenta');
-  log('   ├──────────────────────────────────────────────────────────┤', 'magenta');
-  log('   │  Size:      ~200MB (includes browser binaries)           │', 'magenta');
-  log('   │  Purpose:   End-to-end page testing, cross-browser       │', 'magenta');
-  log('   │  Required:  /hustle-ui-create-page (page mode)           │', 'magenta');
-  log('   │  Without:   Cannot write .e2e.test.ts files              │', 'magenta');
-  log('   │  Install:   --with-playwright flag OR during UI workflow │', 'magenta');
-  log('   │  Command:   npm init playwright@latest                   │', 'magenta');
-  log('   └──────────────────────────────────────────────────────────┘', 'magenta');
-
-  log('   ┌──────────────────────────────────────────────────────────┐', 'blue');
-  log('   │  SANDPACK (Live Editing)                                 │', 'blue');
-  log('   ├──────────────────────────────────────────────────────────┤', 'blue');
-  log('   │  Size:      ~5MB                                         │', 'blue');
-  log('   │  Purpose:   Live code editing in UI Showcase             │', 'blue');
-  log('   │  Required:  Interactive component playground             │', 'blue');
-  log('   │  Without:   Static previews only (still functional)      │', 'blue');
-  log('   │  Install:   --with-sandpack flag                         │', 'blue');
-  log('   │  Command:   npm install @codesandbox/sandpack-react      │', 'blue');
-  log('   └──────────────────────────────────────────────────────────┘', 'blue');
-
-  log('\n   💡 UI Workflow Behavior:', 'bright');
-  log('   When you run /hustle-ui-create without Storybook or Playwright:', 'bright');
-  log('   1. The hook will BLOCK writing test/story files', 'bright');
-  log('   2. You\'ll see the install command and be prompted to install', 'bright');
-  log('   3. After installing, the workflow continues automatically', 'bright');
-  log('   4. You can skip and install later, but Phase 8-10 will be blocked', 'bright');
-
-  log('\n   Example with all optional tools:', 'yellow');
-  log('   npx @hustle-together/api-dev-tools --with-storybook --with-playwright --with-sandpack\n', 'yellow');
-
-  // ========================================
-  // 5. Verify Installation
-  // ========================================
-  const verification = verifyInstallation(claudeDir, hooksDir);
-  if (!verification.success) {
-    log('⚠️  Installation verification found issues:', 'yellow');
-    verification.failures.forEach(f => log(`   • Missing: ${f}`, 'yellow'));
-    log('   Some features may not work correctly.\n', 'yellow');
-  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Summary
+  // ─────────────────────────────────────────────────────────────────────────
+
+  log(`
+${c.red}═══════════════════════════════════════════════════════════════${c.reset}
+${c.bold}                    Installation Complete${c.reset}
+${c.red}═══════════════════════════════════════════════════════════════${c.reset}
+
+${c.bold}Installed:${c.reset}
+  ● Commands      .claude/commands/     (slash commands)
+  ● Hooks         hooks/                (enforcement)
+  ● Subagents     .claude/agents/       (parallel processing)
+  ● Config        .claude/              (settings, state, registry)
+  ● Templates     templates/            (.env.example)
+
+${c.bold}Quick Start:${c.reset}
+  ${c.gray}$${c.reset} /api-create my-endpoint      ${c.dim}# Build API endpoint${c.reset}
+  ${c.gray}$${c.reset} /hustle-ui-create Button     ${c.dim}# Build component${c.reset}
+  ${c.gray}$${c.reset} /hustle-ui-create-page Home  ${c.dim}# Build page${c.reset}
+  ${c.gray}$${c.reset} /hustle-combine api          ${c.dim}# Orchestrate APIs${c.reset}
+
+${c.bold}Next Steps:${c.reset}
+  1. ${c.white}cp templates/.env.example .env${c.reset}
+  2. ${c.white}Configure your API keys in .env${c.reset}
+  3. ${c.white}Add GREPTILE_API_KEY + GITHUB_TOKEN${c.reset} for Phase 14 code review
+  4. ${c.white}/ntfy-setup${c.reset} for push notifications (optional)
+  5. ${c.white}Restart Claude Code${c.reset} for MCP tools
+
+${c.dim}Documentation: https://github.com/hustle-together/api-dev-tools${c.reset}
+`);
 }
 
-/**
- * Merge MCP server configurations
- */
-function mergeMcpServers(existing, newMcp) {
-  const merged = { ...existing };
-  merged.mcpServers = merged.mcpServers || {};
-
-  // Add new MCP servers that don't already exist
-  if (newMcp.mcpServers) {
-    for (const [name, config] of Object.entries(newMcp.mcpServers)) {
-      if (!merged.mcpServers[name]) {
-        merged.mcpServers[name] = config;
-      }
-    }
-  }
-
-  return merged;
-}
+// ═══════════════════════════════════════════════════════════════════════════
+// Settings Merge
+// ═══════════════════════════════════════════════════════════════════════════
 
-/**
- * Merge two settings objects, combining hooks arrays
- */
 function mergeSettings(existing, newSettings) {
   const merged = { ...existing };
 
-  // Merge hooks
   if (newSettings.hooks) {
     merged.hooks = merged.hooks || {};
 
@@ -939,11 +570,10 @@ function mergeSettings(existing, newSettings) {
         merged.hooks[hookType] = [];
       }
 
-      // Add new hooks that don't already exist (check by command path)
       for (const newHook of newSettings.hooks[hookType]) {
-        const hookCommand = newHook.hooks?.[0]?.command || '';
-        const exists = merged.hooks[hookType].some(existing => {
-          const existingCommand = existing.hooks?.[0]?.command || '';
+        const hookCommand = newHook.hooks?.[0]?.command || "";
+        const exists = merged.hooks[hookType].some((existing) => {
+          const existingCommand = existing.hooks?.[0]?.command || "";
           return existingCommand === hookCommand;
         });
 
@@ -954,14 +584,27 @@ function mergeSettings(existing, newSettings) {
     }
   }
 
+  if (newSettings.permissions) {
+    merged.permissions = merged.permissions || {};
+    merged.permissions.allow = [
+      ...new Set([
+        ...(merged.permissions.allow || []),
+        ...(newSettings.permissions.allow || []),
+      ]),
+    ];
+    merged.permissions.deny = [
+      ...new Set([
+        ...(merged.permissions.deny || []),
+        ...(newSettings.permissions.deny || []),
+      ]),
+    ];
+  }
+
   return merged;
 }
 
-// Run installer
-try {
-  main();
-} catch (error) {
-  log(`\n❌ Installation failed: ${error.message}`, 'red');
-  log(`   ${error.stack}\n`, 'red');
+// Run
+main().catch((error) => {
+  console.error(`\n${c.red}Installation failed:${c.reset} ${error.message}`);
   process.exit(1);
-}
+});