grimoire-framework 1.0.2 → 1.0.4

package/bin/grimoire.js

@@ -1,1118 +1,1118 @@
-#!/usr/bin/env node
-
-/**
- * grimoire-FullStack CLI
- * Main entry point - Standalone (no external dependencies for npx compatibility)
- * Version: 4.0.0
- */
-
-const path = require('path');
-const fs = require('fs');
-const { execSync } = require('child_process');
-
-// Read package.json for version
-const packageJsonPath = path.join(__dirname, '..', 'package.json');
-const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-
-// Parse arguments
-const args = process.argv.slice(2);
-const command = args[0];
-
-// Helper: Run initialization wizard
-async function runWizard(options = {}) {
-  // Use the v4 wizard from packages/installer/src/wizard/index.js
-  const wizardPath = path.join(__dirname, '..', 'packages', 'installer', 'src', 'wizard', 'index.js');
-
-  if (!fs.existsSync(wizardPath)) {
-    // Fallback to legacy wizard if new wizard not found
-    const legacyScript = path.join(__dirname, 'grimoire-init.js');
-    if (fs.existsSync(legacyScript)) {
-      if (!options.quiet) {
-        console.log('⚠️  Using legacy wizard (src/wizard not found)');
-      }
-      // Legacy wizard doesn't support options, pass via env vars
-      process.env.grimoire_INSTALL_FORCE = options.force ? '1' : '';
-      process.env.grimoire_INSTALL_QUIET = options.quiet ? '1' : '';
-      process.env.grimoire_INSTALL_DRY_RUN = options.dryRun ? '1' : '';
-      require(legacyScript);
-      return;
-    }
-    console.error('❌ Initialization wizard not found');
-    console.error('Please ensure grimoire-FullStack is installed correctly.');
-    process.exit(1);
-  }
-
-  try {
-    // Run the v4 wizard with options
-    const { runWizard: executeWizard } = require(wizardPath);
-    await executeWizard(options);
-  } catch (error) {
-    console.error('❌ Wizard error:', error.message);
-    process.exit(1);
-  }
-}
-
-// Helper: Show help
-function showHelp() {
-  console.log(`
-grimoire-FullStack v${packageJson.version}
-AI-Orchestrated System for Full Stack Development
-
-USAGE:
-  npx grimoire-framework              # Run installation wizard
-  npx grimoire-framework install      # Install in current project
-  npx grimoire-framework init <name>  # Create new project
-  npx grimoire-framework update       # Update to latest version
-  npx grimoire-framework validate     # Validate installation integrity
-  npx grimoire-framework info         # Show system info
-  npx grimoire-framework doctor       # Run diagnostics
-  npx grimoire-framework --version    # Show version
-  npx grimoire-framework --version -d # Show detailed version info
-  npx grimoire-framework --help       # Show this help
-
-UPDATE:
-  grimoire-framework update                    # Update to latest version
-  grimoire-framework update --check            # Check for updates without applying
-  grimoire-framework update --dry-run          # Preview what would be updated
-  grimoire-framework update --force            # Force update even if up-to-date
-  grimoire-framework update --verbose          # Show detailed output
-
-VALIDATION:
-  grimoire-framework validate                    # Validate installation integrity
-  grimoire-framework validate --repair           # Repair missing/corrupted files
-  grimoire-framework validate --repair --dry-run # Preview repairs
-  grimoire-framework validate --detailed         # Show detailed file list
-
-CONFIGURATION:
-  grimoire-framework config show                       # Show resolved configuration
-  grimoire-framework config show --debug               # Show with source annotations
-  grimoire-framework config diff --levels L1,L2        # Compare config levels
-  grimoire-framework config migrate                    # Migrate monolithic to layered
-  grimoire-framework config validate                   # Validate config files
-  grimoire-framework config init-local                 # Create local-config.yaml
-
-SERVICE DISCOVERY:
-  grimoire-framework workers search <query>            # Search for workers
-  grimoire-framework workers search "json" --category=data
-  grimoire-framework workers search "transform" --tags=etl,data
-  grimoire-framework workers search "api" --format=json
-
-EXAMPLES:
-  # Install in current directory
-  npx grimoire-framework
-
-  # Install with minimal mode (only expansion-creator)
-  npx grimoire-minimal
-
-  # Create new project
-  npx grimoire-framework init my-project
-
-  # Search for workers
-  grimoire-framework workers search "json csv"
-
-For more information, visit: https://github.com/grimoireAI/grimoire
-`);
-}
-
-// Helper: Show version
-async function showVersion() {
-  const isDetailed = args.includes('--detailed') || args.includes('-d');
-
-  if (!isDetailed) {
-    // Simple version output (backwards compatible)
-    console.log(packageJson.version);
-    return;
-  }
-
-  // Detailed version output (Story 7.2: Version Tracking)
-  console.log(`grimoire-FullStack v${packageJson.version}`);
-  console.log('Package: grimoire');
-
-  // Check for local installation
-  const localVersionPath = path.join(process.cwd(), '.grimoire', 'version.json');
-
-  if (fs.existsSync(localVersionPath)) {
-    try {
-      const versionInfo = JSON.parse(fs.readFileSync(localVersionPath, 'utf8'));
-      console.log('\n📦 Local Installation:');
-      console.log(`  Version:    ${versionInfo.version}`);
-      console.log(`  Mode:       ${versionInfo.mode || 'unknown'}`);
-
-      if (versionInfo.installedAt) {
-        const installedDate = new Date(versionInfo.installedAt);
-        console.log(`  Installed:  ${installedDate.toLocaleDateString()}`);
-      }
-
-      if (versionInfo.updatedAt) {
-        const updatedDate = new Date(versionInfo.updatedAt);
-        console.log(`  Updated:    ${updatedDate.toLocaleDateString()}`);
-      }
-
-      if (versionInfo.fileHashes) {
-        const fileCount = Object.keys(versionInfo.fileHashes).length;
-        console.log(`  Files:      ${fileCount} tracked`);
-      }
-
-      if (versionInfo.customized && versionInfo.customized.length > 0) {
-        console.log(`  Customized: ${versionInfo.customized.length} files`);
-      }
-
-      // Version comparison
-      if (versionInfo.version !== packageJson.version) {
-        console.log('\n⚠️  Version mismatch!');
-        console.log(`  Local:  ${versionInfo.version}`);
-        console.log(`  Latest: ${packageJson.version}`);
-        console.log('  Run \'npx grimoire-framework update\' to update.');
-      } else {
-        console.log('\n✅ Up to date');
-      }
-    } catch (error) {
-      console.log(`\n⚠️  Could not read version.json: ${error.message}`);
-    }
-  } else {
-    console.log('\n📭 No local installation found');
-    console.log('  Run \'npx grimoire-framework install\' to install grimoire in this project.');
-  }
-}
-
-// Helper: Show system info
-function showInfo() {
-  console.log('📊 grimoire-FullStack System Information\n');
-  console.log(`Version: ${packageJson.version}`);
-  console.log(`Platform: ${process.platform}`);
-  console.log(`Node.js: ${process.version}`);
-  console.log(`Architecture: ${process.arch}`);
-  console.log(`Working Directory: ${process.cwd()}`);
-  console.log(`Install Location: ${path.join(__dirname, '..')}`);
-
-  // Check if .grimoire exists
-  const grimoireCoreDir = path.join(__dirname, '..', '.grimoire');
-  if (fs.existsSync(grimoireCoreDir)) {
-    console.log('\n✓ grimoire Core installed');
-
-    // Count components
-    const countFiles = (dir) => {
-      try {
-        return fs.readdirSync(dir).length;
-      } catch {
-        return 0;
-      }
-    };
-
-    console.log(`  - Agents: ${countFiles(path.join(grimoireCoreDir, 'development', 'agents'))}`);
-    console.log(`  - Tasks: ${countFiles(path.join(grimoireCoreDir, 'development', 'tasks'))}`);
-    console.log(`  - Templates: ${countFiles(path.join(grimoireCoreDir, 'development', 'templates'))}`);
-    console.log(`  - Workflows: ${countFiles(path.join(grimoireCoreDir, 'development', 'workflows'))}`);
-  } else {
-    console.log('\n⚠️  grimoire Core not found');
-  }
-
-  // Check grimoire Pro status (Task 5.1)
-  const proDir = path.join(__dirname, '..', 'pro');
-  if (fs.existsSync(proDir)) {
-    console.log('\n✓ grimoire Pro installed');
-
-    try {
-      const { featureGate } = require(path.join(proDir, 'license', 'feature-gate'));
-      const state = featureGate.getLicenseState();
-      const info = featureGate.getLicenseInfo();
-
-      const stateEmoji = {
-        'Active': '✅',
-        'Grace': '⚠️',
-        'Expired': '❌',
-        'Not Activated': '➖',
-      };
-
-      console.log(`  - License: ${stateEmoji[state] || ''} ${state}`);
-
-      if (info && info.features) {
-        const availableCount = featureGate.listAvailable().length;
-        console.log(`  - Features: ${availableCount} available`);
-      }
-    } catch {
-      console.log('  - License: Unable to check status');
-    }
-  }
-}
-
-// Helper: Run installation validation
-async function runValidate() {
-  const validateArgs = args.slice(1); // Remove 'validate' from args
-
-  try {
-    // Load the validate command module
-    const { createValidateCommand } = require('../.grimoire/cli/commands/validate/index.js');
-    const validateCmd = createValidateCommand();
-
-    // Parse and execute (Note: don't include 'validate' as it's the command name, not an argument)
-    await validateCmd.parseAsync(['node', 'grimoire', ...validateArgs]);
-  } catch (_error) {
-    // Fallback: Run quick validation inline
-    console.log('Running installation validation...\n');
-
-    try {
-      const validatorPath = path.join(
-        __dirname,
-        '..',
-        'packages',
-        'installer',
-        'src',
-        'installer',
-        'post-install-validator.js',
-      );
-      const { PostInstallValidator, formatReport } = require(validatorPath);
-
-      const projectRoot = process.cwd();
-      const validator = new PostInstallValidator(projectRoot, path.join(__dirname, '..'));
-      const report = await validator.validate();
-
-      console.log(formatReport(report, { colors: true }));
-
-      if (
-        report.status === 'failed' ||
-        report.stats.missingFiles > 0 ||
-        report.stats.corruptedFiles > 0
-      ) {
-        process.exit(1);
-      }
-    } catch (validatorError) {
-      console.error(`❌ Validation error: ${validatorError.message}`);
-      if (args.includes('--verbose') || args.includes('-v')) {
-        console.error(validatorError.stack);
-      }
-      process.exit(2);
-    }
-  }
-}
-
-// Helper: Run update command
-async function runUpdate() {
-  const updateArgs = args.slice(1);
-  const isCheck = updateArgs.includes('--check');
-  const isDryRun = updateArgs.includes('--dry-run');
-  const isForce = updateArgs.includes('--force');
-  const isVerbose = updateArgs.includes('--verbose') || updateArgs.includes('-v');
-
-  try {
-    const updaterPath = path.join(__dirname, '..', 'packages', 'installer', 'src', 'updater', 'index.js');
-
-    if (!fs.existsSync(updaterPath)) {
-      console.error('❌ Updater module not found');
-      console.error('Please ensure grimoire-FullStack is installed correctly.');
-      process.exit(1);
-    }
-
-    const { grimoireUpdater, formatCheckResult, formatUpdateResult } = require(updaterPath);
-
-    const updater = new grimoireUpdater(process.cwd(), {
-      verbose: isVerbose,
-      force: isForce,
-    });
-
-    if (isCheck) {
-      // Check only mode
-      console.log('🔍 Checking for updates...\n');
-      const result = await updater.checkForUpdates();
-      console.log(formatCheckResult(result, { colors: true }));
-
-      if (result.status === 'check_failed') {
-        process.exit(1);
-      }
-    } else {
-      // Update mode
-      console.log('🔄 grimoire Update\n');
-
-      const result = await updater.update({
-        dryRun: isDryRun,
-        onProgress: (phase, message) => {
-          if (isVerbose) {
-            console.log(`[${phase}] ${message}`);
-          }
-        },
-      });
-
-      console.log(formatUpdateResult(result, { colors: true }));
-
-      if (!result.success && result.error !== 'Already up to date') {
-        process.exit(1);
-      }
-    }
-  } catch (error) {
-    console.error(`❌ Update error: ${error.message}`);
-    if (args.includes('--verbose') || args.includes('-v')) {
-      console.error(error.stack);
-    }
-    process.exit(1);
-  }
-}
-
-// Helper: Run doctor diagnostics
-async function runDoctor() {
-  const doctorArgs = args.slice(1);
-  const shouldFix = doctorArgs.includes('--fix');
-  const isDryRun = doctorArgs.includes('--dry-run');
-  const showHelp = doctorArgs.includes('--help') || doctorArgs.includes('-h');
-
-  if (showHelp) {
-    console.log(`
-Usage: grimoire doctor [options]
-
-Run system diagnostics and optionally fix issues.
-
-Options:
-  --fix          Attempt to automatically fix detected issues
-  --dry-run      Show what would be fixed without making changes
-  -h, --help     Show this help message
-
-Examples:
-  $ npx grimoire-framework doctor              # Run diagnostics
-  $ npx grimoire-framework doctor --fix        # Fix detected issues
-  $ npx grimoire-framework doctor --dry-run    # Preview fixes
-`);
-    return;
-  }
-
-  console.log('🏥 grimoire System Diagnostics\n');
-
-  const issues = [];
-  let hasErrors = false;
-
-  // Helper: Compare semver versions
-  const compareVersions = (a, b) => {
-    const pa = a.split('.').map((n) => parseInt(n, 10));
-    const pb = b.split('.').map((n) => parseInt(n, 10));
-    for (let i = 0; i < 3; i++) {
-      const na = pa[i] || 0;
-      const nb = pb[i] || 0;
-      if (na > nb) return 1;
-      if (na < nb) return -1;
-    }
-    return 0;
-  };
-
-  // Check 1: Node.js version
-  const nodeVersion = process.version.replace('v', '');
-  const requiredNodeVersion = '18.0.0';
-  const nodeOk = compareVersions(nodeVersion, requiredNodeVersion) >= 0;
-
-  if (!nodeOk) {
-    issues.push({
-      type: 'node_version',
-      autoFix: false,
-      message: `Node.js version: ${process.version} (requires >=18.0.0)`,
-      suggestion: 'nvm install 20 && nvm use 20',
-    });
-    hasErrors = true;
-  }
-  console.log(
-    `${nodeOk ? '✔' : '✗'} Node.js version: ${process.version} ${nodeOk ? '(meets requirement: >=18.0.0)' : '(requires >=18.0.0)'}`,
-  );
-
-  // Check 2: npm
-  try {
-    const npmVersion = execSync('npm --version', { encoding: 'utf8' }).trim();
-    console.log(`✔ npm version: ${npmVersion}`);
-  } catch {
-    issues.push({
-      type: 'npm',
-      autoFix: false,
-      message: 'npm not found',
-      suggestion: 'Install Node.js from https://nodejs.org (includes npm)',
-    });
-    console.log('✗ npm not found');
-    hasErrors = true;
-  }
-
-  // Check 3: Git
-  try {
-    const gitVersion = execSync('git --version', { encoding: 'utf8' }).trim();
-    console.log(`✔ Git installed: ${gitVersion}`);
-  } catch {
-    issues.push({
-      type: 'git',
-      autoFix: false,
-      message: 'Git not found (optional but recommended)',
-      suggestion: 'Install Git from https://git-scm.com',
-    });
-    console.log('⚠️  Git not found (optional but recommended)');
-  }
-
-  // Check 4: grimoire installation
-  const grimoireCoreDir = path.join(__dirname, '..', '.grimoire');
-  if (fs.existsSync(grimoireCoreDir)) {
-    console.log(`✔ Grimoire: v${packageJson.version}`);
-
-    // Check for corruption using validate (if available)
-    try {
-      const validatorPath = path.join(__dirname, '..', 'packages', 'installer', 'src', 'installer', 'post-install-validator');
-      const { PostInstallValidator } = require(validatorPath);
-      const validator = new PostInstallValidator(process.cwd(), path.join(__dirname, '..'));
-      const report = await validator.validate();
-
-      if (report.stats && (report.stats.missingFiles > 0 || report.stats.corruptedFiles > 0)) {
-        issues.push({
-          type: 'grimoire_corrupted',
-          autoFix: true,
-          message: `grimoire Core: ${report.stats.missingFiles} missing, ${report.stats.corruptedFiles} corrupted files`,
-          fixAction: async () => {
-            console.log('  🔧 Repairing grimoire installation...');
-            await validator.repair();
-            console.log('  ✓ Repair complete');
-          },
-        });
-        hasErrors = true;
-        console.log(`⚠️  grimoire Core: ${report.stats.missingFiles} missing, ${report.stats.corruptedFiles} corrupted files`);
-      }
-    } catch {
-      // Validation not available, skip corruption check
-    }
-  } else {
-    issues.push({
-      type: 'grimoire_missing',
-      autoFix: true,
-      message: 'grimoire Core not installed',
-      fixAction: async () => {
-        console.log('  🔧 Installing grimoire...');
-        try {
-          execSync('npx grimoire-framework install --force --quiet', { stdio: 'inherit', timeout: 60000 });
-          console.log('  ✓ Installation complete');
-        } catch (installError) {
-          console.error(`  ✗ Installation failed: ${installError.message}`);
-          throw installError;
-        }
-      },
-    });
-    hasErrors = true;
-    console.log('✗ grimoire Core not installed');
-    console.log('  Run: npx grimoire-framework');
-  }
-
-  // Check 5: grimoire Pro status
-  const proDetector = require('./utils/pro-detector');
-  if (proDetector.isProAvailable()) {
-    console.log('✔ grimoire Pro: Active (Full Version)');
-  }
-
-  // Apply fixes if --fix
-  if (shouldFix && issues.length > 0) {
-    console.log('\n🔧 Attempting fixes...\n');
-
-    let fixed = 0;
-    let manual = 0;
-
-    for (const issue of issues) {
-      if (issue.autoFix && issue.fixAction) {
-        if (isDryRun) {
-          console.log(`  [DRY RUN] Would fix: ${issue.type}`);
-          fixed++;
-        } else {
-          try {
-            await issue.fixAction();
-            fixed++;
-          } catch (fixError) {
-            console.error(`  ✗ Failed to fix ${issue.type}: ${fixError.message}`);
-            manual++;
-          }
-        }
-      } else {
-        manual++;
-        console.log(`  ⚠️  ${issue.message}`);
-        console.log(`     💡 Fix: ${issue.suggestion}`);
-      }
-    }
-
-    console.log('');
-    if (isDryRun) {
-      console.log(`✅ Dry run completed - ${fixed} issues would be fixed`);
-      if (manual > 0) {
-        console.log(`⚠️  ${manual} issues require manual action`);
-      }
-    } else {
-      if (fixed > 0) {
-        console.log(`✅ Fixed ${fixed} issue${fixed > 1 ? 's' : ''}`);
-      }
-      if (manual > 0) {
-        console.log(`⚠️  ${manual} issue${manual > 1 ? 's' : ''} require manual action`);
-        process.exit(1);
-      }
-    }
-  } else {
-    // Summary (no --fix)
-    console.log('');
-    if (hasErrors) {
-      console.log('⚠️  Some issues were detected. Run with --fix to auto-repair.');
-      process.exit(1);
-    } else {
-      console.log('✅ All checks passed! Your installation is healthy.');
-    }
-  }
-}
-
-// Helper: Format bytes to human readable
-function formatBytes(bytes) {
-  if (bytes === 0) return '0 Bytes';
-  const k = 1024;
-  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
-  const i = Math.floor(Math.log(bytes) / Math.log(k));
-  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
-}
-
-// Helper: Remove grimoire sections from .gitignore
-function cleanGitignore(gitignorePath) {
-  if (!fs.existsSync(gitignorePath)) return { removed: false };
-
-  const content = fs.readFileSync(gitignorePath, 'utf8');
-  const lines = content.split('\n');
-  const newLines = [];
-  let ingrimoireSection = false;
-  let removedLines = 0;
-
-  for (const line of lines) {
-    if (line.includes('# grimoire') || line.includes('# Added by grimoire')) {
-      ingrimoireSection = true;
-      removedLines++;
-      continue;
-    }
-    if (ingrimoireSection && line.trim() === '') {
-      ingrimoireSection = false;
-      continue;
-    }
-    if (ingrimoireSection) {
-      removedLines++;
-      continue;
-    }
-    newLines.push(line);
-  }
-
-  if (removedLines > 0) {
-    fs.writeFileSync(gitignorePath, newLines.join('\n'));
-    return { removed: true, lines: removedLines };
-  }
-  return { removed: false };
-}
-
-// Helper: Show uninstall help
-function showUninstallHelp() {
-  console.log(`
-Usage: npx grimoire-framework uninstall [options]
-
-Remove grimoire from the current project.
-
-Options:
-  --force      Skip confirmation prompt
-  --keep-data  Keep .grimoire/ directory (settings and history)
-  --dry-run    Show what would be removed without removing
-  -h, --help   Show this help message
-
-What gets removed:
-  - .grimoire/     Framework core files
-  - docs/stories/   Story files (if created by grimoire)
-  - squads/         Squad definitions
-  - .gitignore      grimoire-added entries only
-
-What is preserved (with --keep-data):
-  - .grimoire/          Project settings and agent history
-
-Exit Codes:
-  0  Uninstall successful
-  1  Uninstall failed or cancelled
-
-Examples:
-  # Interactive uninstall (with confirmation)
-  npx grimoire-framework uninstall
-
-  # Force uninstall without prompts
-  npx grimoire-framework uninstall --force
-
-  # See what would be removed
-  npx grimoire-framework uninstall --dry-run
-
-  # Uninstall but keep project data
-  npx grimoire-framework uninstall --keep-data
-`);
-}
-
-// Helper: Show doctor help
-function showDoctorHelp() {
-  console.log(`
-Usage: npx grimoire-framework doctor [options]
-
-Run health checks on your grimoire installation.
-
-Options:
-  --fix        Automatically fix detected issues
-  --dry-run    Show what --fix would do without making changes
-  --quiet      Minimal output (exit code only)
-  -h, --help   Show this help message
-
-Checks performed:
-  • Required directories exist (.grimoire/, .grimoire/)
-  • Configuration files are valid JSON/YAML
-  • Agent definitions are complete
-  • Task files have required fields
-  • Dependencies are installed
-
-Exit Codes:
-  0  All checks passed (or issues fixed with --fix)
-  1  Issues detected (run with --fix to repair)
-
-Examples:
-  # Run health check
-  npx grimoire-framework doctor
-
-  # Auto-fix detected issues
-  npx grimoire-framework doctor --fix
-
-  # Preview what would be fixed
-  npx grimoire-framework doctor --fix --dry-run
-`);
-}
-
-// Uninstall grimoire from project
-async function runUninstall(options = {}) {
-  const { force = false, keepData = false, dryRun = false, quiet = false } = options;
-  const cwd = process.cwd();
-
-  // Items to remove
-  const itemsToRemove = [
-    { path: '.grimoire', description: 'Framework core' },
-    { path: 'squads', description: 'Squad definitions' },
-  ];
-
-  // Optionally remove .grimoire
-  if (!keepData) {
-    itemsToRemove.push({ path: '.grimoire', description: 'Project data and settings' });
-  }
-
-  // Check what exists
-  const existingItems = itemsToRemove.filter(item =>
-    fs.existsSync(path.join(cwd, item.path)),
-  );
-
-  if (existingItems.length === 0) {
-    console.log('ℹ️  No grimoire installation found in this directory.');
-    return;
-  }
-
-  // Calculate total size
-  let totalSize = 0;
-  const itemSizes = [];
-
-  for (const item of existingItems) {
-    const itemPath = path.join(cwd, item.path);
-    try {
-      const stats = fs.statSync(itemPath);
-      if (stats.isDirectory()) {
-        // Simple recursive size calculation
-        const getSize = (dir) => {
-          let size = 0;
-          try {
-            const files = fs.readdirSync(dir);
-            for (const file of files) {
-              const filePath = path.join(dir, file);
-              const stat = fs.statSync(filePath);
-              if (stat.isDirectory()) {
-                size += getSize(filePath);
-              } else {
-                size += stat.size;
-              }
-            }
-          } catch { /* ignore errors */ }
-          return size;
-        };
-        const size = getSize(itemPath);
-        totalSize += size;
-        itemSizes.push({ ...item, size });
-      } else {
-        totalSize += stats.size;
-        itemSizes.push({ ...item, size: stats.size });
-      }
-    } catch {
-      itemSizes.push({ ...item, size: 0 });
-    }
-  }
-
-  // Show what will be removed
-  if (!quiet) {
-    console.log('\n📋 Items to be removed:\n');
-    for (const item of itemSizes) {
-      const sizeStr = item.size > 0 ? ` (${formatBytes(item.size)})` : '';
-      console.log(`  • ${item.path}/${sizeStr} - ${item.description}`);
-    }
-    console.log(`\n  Total: ${formatBytes(totalSize)}`);
-
-    // Check for .gitignore cleanup
-    const gitignorePath = path.join(cwd, '.gitignore');
-    if (fs.existsSync(gitignorePath)) {
-      const content = fs.readFileSync(gitignorePath, 'utf8');
-      if (content.includes('# grimoire') || content.includes('# Added by grimoire')) {
-        console.log('  • .gitignore grimoire entries will be cleaned');
-      }
-    }
-    console.log('');
-  }
-
-  // Dry run - stop here
-  if (dryRun) {
-    console.log('🔍 Dry run - no changes made.');
-    return;
-  }
-
-  // Confirmation
-  if (!force) {
-    const readline = require('readline');
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-
-    const answer = await new Promise(resolve => {
-      rl.question('⚠️  Are you sure you want to uninstall grimoire? (y/N): ', resolve);
-    });
-    rl.close();
-
-    if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') {
-      console.log('❌ Uninstall cancelled.');
-      process.exit(1);
-    }
-  }
-
-  // Perform removal
-  if (!quiet) console.log('\n🗑️  Removing grimoire components...\n');
-
-  for (const item of existingItems) {
-    const itemPath = path.join(cwd, item.path);
-    try {
-      fs.rmSync(itemPath, { recursive: true, force: true });
-      if (!quiet) console.log(`  ✓ Removed ${item.path}/`);
-    } catch (error) {
-      console.error(`  ✗ Failed to remove ${item.path}: ${error.message}`);
-    }
-  }
-
-  // Clean .gitignore
-  const gitignorePath = path.join(cwd, '.gitignore');
-  const gitignoreResult = cleanGitignore(gitignorePath);
-  if (gitignoreResult.removed && !quiet) {
-    console.log(`  ✓ Cleaned ${gitignoreResult.lines} grimoire entries from .gitignore`);
-  }
-
-  // Summary
-  if (!quiet) {
-    console.log('\n✅ grimoire has been uninstalled.');
-    if (keepData) {
-      console.log('   Your project data in .grimoire/ has been preserved.');
-    }
-    console.log('\n   To reinstall: npx grimoire-framework install');
-  }
-}
-
-// Helper: Show install help
-function showInstallHelp() {
-  console.log(`
-Usage: npx grimoire-framework install [options]
-
-Install grimoire in the current directory.
-
-Options:
-  --force      Overwrite existing grimoire installation
-  --quiet      Minimal output (no banner, no prompts) - ideal for CI/CD
-  --dry-run    Simulate installation without modifying files
-  --merge      Auto-merge existing config files (brownfield mode)
-  --no-merge   Disable merge option, use legacy overwrite behavior
-  -h, --help   Show this help message
-
-Smart Merge (Brownfield):
-  When installing in a project with existing config files (.env, CLAUDE.md),
-  grimoire can merge new settings while preserving your customizations.
-
-  - .env files: Adds new variables, preserves existing values
-  - CLAUDE.md: Updates grimoire sections, keeps your custom rules
-
-Exit Codes:
-  0  Installation successful
-  1  Installation failed
-
-Examples:
-  # Interactive installation
-  npx grimoire-framework install
-
-  # Force reinstall without prompts
-  npx grimoire-framework install --force
-
-  # Brownfield: merge configs automatically
-  npx grimoire-framework install --merge
-
-  # Silent install for CI/CD
-  npx grimoire-framework install --quiet --force
-
-  # Preview what would be installed
-  npx grimoire-framework install --dry-run
-`);
-}
-
-// Helper: Create new project
-// Helper: Show init help
-function showInitHelp() {
-  console.log(`
-Usage: npx grimoire-framework init <project-name> [options]
-
-Create a new grimoire project with the specified name.
-
-Options:
-  --force              Force creation in non-empty directory
-  --skip-install       Skip npm dependency installation
-  --template <name>    Use specific template (default: default)
-  -t <name>            Shorthand for --template
-  -h, --help           Show this help message
-
-Available Templates:
-  default     Full installation with all agents, tasks, and workflows
-  minimal     Essential files only (dev agent + basic tasks)
-  enterprise  Everything + dashboards + team integrations
-
-Examples:
-  npx grimoire-framework init my-project
-  npx grimoire-framework init my-project --template minimal
-  npx grimoire-framework init my-project --force --skip-install
-  npx grimoire-framework init . --template enterprise
-`);
-}
-
-async function initProject() {
-  // 1. Parse ALL args after 'init'
-  const initArgs = args.slice(1);
-
-  // 2. Handle --help FIRST (before creating any directories)
-  if (initArgs.includes('--help') || initArgs.includes('-h')) {
-    showInitHelp();
-    return;
-  }
-
-  // 3. Parse flags
-  const isForce = initArgs.includes('--force');
-  const skipInstall = initArgs.includes('--skip-install');
-
-  // Template with argument
-  const templateIndex = initArgs.findIndex((a) => a === '--template' || a === '-t');
-  let template = 'default';
-  if (templateIndex !== -1) {
-    template = initArgs[templateIndex + 1];
-    if (!template || template.startsWith('-')) {
-      console.error('❌ --template requires a template name');
-      console.error('Available templates: default, minimal, enterprise');
-      process.exit(1);
-    }
-  }
-
-  // Validate template
-  const validTemplates = ['default', 'minimal', 'enterprise'];
-  if (!validTemplates.includes(template)) {
-    console.error(`❌ Unknown template: ${template}`);
-    console.error(`Available templates: ${validTemplates.join(', ')}`);
-    process.exit(1);
-  }
-
-  // 4. Extract project name (anything that doesn't start with - and isn't a template value)
-  const projectName = initArgs.find((arg, i) => {
-    if (arg.startsWith('-')) return false;
-    // Skip if it's the value after --template
-    const prevArg = initArgs[i - 1];
-    if (prevArg === '--template' || prevArg === '-t') return false;
-    return true;
-  });
-
-  if (!projectName) {
-    console.error('❌ Project name is required');
-    console.log('\nUsage: npx grimoire-framework init <project-name> [options]');
-    console.log('Run with --help for more information.');
-    process.exit(1);
-  }
-
-  // 5. Handle "." to install in current directory
-  const isCurrentDir = projectName === '.';
-  const targetPath = isCurrentDir ? process.cwd() : path.join(process.cwd(), projectName);
-  const displayName = isCurrentDir ? path.basename(process.cwd()) : projectName;
-
-  // 6. Check if directory exists
-  if (fs.existsSync(targetPath) && !isCurrentDir) {
-    const contents = fs.readdirSync(targetPath).filter((f) => !f.startsWith('.'));
-    if (contents.length > 0 && !isForce) {
-      console.error(`❌ Directory already exists and is not empty: ${projectName}`);
-      console.error('Use --force to overwrite.');
-      process.exit(1);
-    }
-    if (contents.length > 0 && isForce) {
-      console.log(`⚠️  Using --force: overwriting existing directory: ${projectName}`);
-    } else {
-      console.log(`✓ Using existing empty directory: ${projectName}`);
-    }
-  } else if (!fs.existsSync(targetPath)) {
-    fs.mkdirSync(targetPath, { recursive: true });
-    console.log(`✓ Created directory: ${projectName}`);
-  }
-
-  console.log(`Creating new grimoire project: ${displayName}`);
-  if (template !== 'default') {
-    console.log(`Template: ${template}`);
-  }
-  if (skipInstall) {
-    console.log('Skip install: enabled');
-  }
-  console.log('');
-
-  // 7. Change to project directory (if not already there)
-  if (!isCurrentDir) {
-    process.chdir(targetPath);
-  }
-
-  // 8. Run the initialization wizard with options
-  await runWizard({
-    template,
-    skipInstall,
-    force: isForce,
-  });
-}
-
-// Command routing (async main function)
-async function main() {
-  switch (command) {
-    case 'workers':
-      // Service Discovery CLI - Story 2.7
-      try {
-        const { run } = require('../.grimoire/cli/index.js');
-        await run(process.argv);
-      } catch (error) {
-        console.error(`❌ Workers command error: ${error.message}`);
-        process.exit(1);
-      }
-      break;
-
-    case 'config':
-      // Layered Configuration CLI - Story PRO-4
-      try {
-        const { run } = require('../.grimoire/cli/index.js');
-        await run(process.argv);
-      } catch (error) {
-        console.error(`❌ Config command error: ${error.message}`);
-        process.exit(1);
-      }
-      break;
-
-    case 'pro':
-      // grimoire Pro License Management - Story PRO-6
-      try {
-        const { run } = require('../.grimoire/cli/index.js');
-        await run(process.argv);
-      } catch (error) {
-        console.error(`❌ Pro command error: ${error.message}`);
-        process.exit(1);
-      }
-      break;
-
-    case 'install': {
-      // Install in current project with flag support
-      const installArgs = args.slice(1);
-      if (installArgs.includes('--help') || installArgs.includes('-h')) {
-        showInstallHelp();
-        break;
-      }
-      const installOptions = {
-        force: installArgs.includes('--force'),
-        quiet: installArgs.includes('--quiet'),
-        dryRun: installArgs.includes('--dry-run'),
-        forceMerge: installArgs.includes('--merge'),
-        noMerge: installArgs.includes('--no-merge'),
-      };
-      if (!installOptions.quiet) {
-        console.log('grimoire-FullStack Installation\n');
-      }
-      await runWizard(installOptions);
-      break;
-    }
-
-    case 'uninstall': {
-      // Uninstall grimoire from project
-      const uninstallArgs = args.slice(1);
-      if (uninstallArgs.includes('--help') || uninstallArgs.includes('-h')) {
-        showUninstallHelp();
-        break;
-      }
-      const uninstallOptions = {
-        force: uninstallArgs.includes('--force'),
-        keepData: uninstallArgs.includes('--keep-data'),
-        dryRun: uninstallArgs.includes('--dry-run'),
-        quiet: uninstallArgs.includes('--quiet'),
-      };
-      await runUninstall(uninstallOptions);
-      break;
-    }
-
-    case 'init': {
-      // Create new project (flags parsed inside initProject)
-      await initProject();
-      break;
-    }
-
-    case 'info':
-      showInfo();
-      break;
-
-    case 'doctor': {
-      // Run health check with flag support
-      const doctorArgs = args.slice(1);
-      if (doctorArgs.includes('--help') || doctorArgs.includes('-h')) {
-        showDoctorHelp();
-        break;
-      }
-      const doctorOptions = {
-        fix: doctorArgs.includes('--fix'),
-        dryRun: doctorArgs.includes('--dry-run'),
-        quiet: doctorArgs.includes('--quiet'),
-      };
-      await runDoctor(doctorOptions);
-      break;
-    }
-
-    case 'validate':
-      // Post-installation validation - Story 6.19
-      await runValidate();
-      break;
-
-    case 'update':
-      // Update to latest version - Epic 7
-      await runUpdate();
-      break;
-
-    case '--version':
-    case '-v':
-    case '-V':
-      await showVersion();
-      break;
-
-    case '--help':
-    case '-h':
-      showHelp();
-      break;
-
-    case undefined:
-      // No arguments - run wizard directly (npx default behavior)
-      console.log('grimoire-FullStack Installation\n');
-      await runWizard();
-      break;
-
-    default:
-      console.error(`❌ Unknown command: ${command}`);
-      console.log('\nRun with --help to see available commands');
-      process.exit(1);
-  }
-}
-
-// Execute main function
-main().catch((error) => {
-  console.error('❌ Fatal error:', error.message);
-  process.exit(1);
-});
-
-
+#!/usr/bin/env node
+
+/**
+ * grimoire-FullStack CLI
+ * Main entry point - Standalone (no external dependencies for npx compatibility)
+ * Version: 4.0.0
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+// Read package.json for version
+const packageJsonPath = path.join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+// Parse arguments
+const args = process.argv.slice(2);
+const command = args[0];
+
+// Helper: Run initialization wizard
+async function runWizard(options = {}) {
+  // Use the v4 wizard from packages/installer/src/wizard/index.js
+  const wizardPath = path.join(__dirname, '..', 'packages', 'installer', 'src', 'wizard', 'index.js');
+
+  if (!fs.existsSync(wizardPath)) {
+    // Fallback to legacy wizard if new wizard not found
+    const legacyScript = path.join(__dirname, 'grimoire-init.js');
+    if (fs.existsSync(legacyScript)) {
+      if (!options.quiet) {
+        console.log('⚠️  Using legacy wizard (src/wizard not found)');
+      }
+      // Legacy wizard doesn't support options, pass via env vars
+      process.env.grimoire_INSTALL_FORCE = options.force ? '1' : '';
+      process.env.grimoire_INSTALL_QUIET = options.quiet ? '1' : '';
+      process.env.grimoire_INSTALL_DRY_RUN = options.dryRun ? '1' : '';
+      require(legacyScript);
+      return;
+    }
+    console.error('❌ Initialization wizard not found');
+    console.error('Please ensure grimoire-FullStack is installed correctly.');
+    process.exit(1);
+  }
+
+  try {
+    // Run the v4 wizard with options
+    const { runWizard: executeWizard } = require(wizardPath);
+    await executeWizard(options);
+  } catch (error) {
+    console.error('❌ Wizard error:', error.message);
+    process.exit(1);
+  }
+}
+
+// Helper: Show help
+function showHelp() {
+  console.log(`
+grimoire-FullStack v${packageJson.version}
+AI-Orchestrated System for Full Stack Development
+
+USAGE:
+  npx grimoire-framework              # Run installation wizard
+  npx grimoire-framework install      # Install in current project
+  npx grimoire-framework init <name>  # Create new project
+  npx grimoire-framework update       # Update to latest version
+  npx grimoire-framework validate     # Validate installation integrity
+  npx grimoire-framework info         # Show system info
+  npx grimoire-framework doctor       # Run diagnostics
+  npx grimoire-framework --version    # Show version
+  npx grimoire-framework --version -d # Show detailed version info
+  npx grimoire-framework --help       # Show this help
+
+UPDATE:
+  grimoire-framework update                    # Update to latest version
+  grimoire-framework update --check            # Check for updates without applying
+  grimoire-framework update --dry-run          # Preview what would be updated
+  grimoire-framework update --force            # Force update even if up-to-date
+  grimoire-framework update --verbose          # Show detailed output
+
+VALIDATION:
+  grimoire-framework validate                    # Validate installation integrity
+  grimoire-framework validate --repair           # Repair missing/corrupted files
+  grimoire-framework validate --repair --dry-run # Preview repairs
+  grimoire-framework validate --detailed         # Show detailed file list
+
+CONFIGURATION:
+  grimoire-framework config show                       # Show resolved configuration
+  grimoire-framework config show --debug               # Show with source annotations
+  grimoire-framework config diff --levels L1,L2        # Compare config levels
+  grimoire-framework config migrate                    # Migrate monolithic to layered
+  grimoire-framework config validate                   # Validate config files
+  grimoire-framework config init-local                 # Create local-config.yaml
+
+SERVICE DISCOVERY:
+  grimoire-framework workers search <query>            # Search for workers
+  grimoire-framework workers search "json" --category=data
+  grimoire-framework workers search "transform" --tags=etl,data
+  grimoire-framework workers search "api" --format=json
+
+EXAMPLES:
+  # Install in current directory
+  npx grimoire-framework
+
+  # Install with minimal mode (only expansion-creator)
+  npx grimoire-minimal
+
+  # Create new project
+  npx grimoire-framework init my-project
+
+  # Search for workers
+  grimoire-framework workers search "json csv"
+
+For more information, visit: https://github.com/grimoireAI/grimoire
+`);
+}
+
+// Helper: Show version
+async function showVersion() {
+  const isDetailed = args.includes('--detailed') || args.includes('-d');
+
+  if (!isDetailed) {
+    // Simple version output (backwards compatible)
+    console.log(packageJson.version);
+    return;
+  }
+
+  // Detailed version output (Story 7.2: Version Tracking)
+  console.log(`grimoire-FullStack v${packageJson.version}`);
+  console.log('Package: grimoire');
+
+  // Check for local installation
+  const localVersionPath = path.join(process.cwd(), '.grimoire', 'version.json');
+
+  if (fs.existsSync(localVersionPath)) {
+    try {
+      const versionInfo = JSON.parse(fs.readFileSync(localVersionPath, 'utf8'));
+      console.log('\n📦 Local Installation:');
+      console.log(`  Version:    ${versionInfo.version}`);
+      console.log(`  Mode:       ${versionInfo.mode || 'unknown'}`);
+
+      if (versionInfo.installedAt) {
+        const installedDate = new Date(versionInfo.installedAt);
+        console.log(`  Installed:  ${installedDate.toLocaleDateString()}`);
+      }
+
+      if (versionInfo.updatedAt) {
+        const updatedDate = new Date(versionInfo.updatedAt);
+        console.log(`  Updated:    ${updatedDate.toLocaleDateString()}`);
+      }
+
+      if (versionInfo.fileHashes) {
+        const fileCount = Object.keys(versionInfo.fileHashes).length;
+        console.log(`  Files:      ${fileCount} tracked`);
+      }
+
+      if (versionInfo.customized && versionInfo.customized.length > 0) {
+        console.log(`  Customized: ${versionInfo.customized.length} files`);
+      }
+
+      // Version comparison
+      if (versionInfo.version !== packageJson.version) {
+        console.log('\n⚠️  Version mismatch!');
+        console.log(`  Local:  ${versionInfo.version}`);
+        console.log(`  Latest: ${packageJson.version}`);
+        console.log('  Run \'npx grimoire-framework update\' to update.');
+      } else {
+        console.log('\n✅ Up to date');
+      }
+    } catch (error) {
+      console.log(`\n⚠️  Could not read version.json: ${error.message}`);
+    }
+  } else {
+    console.log('\n📭 No local installation found');
+    console.log('  Run \'npx grimoire-framework install\' to install grimoire in this project.');
+  }
+}
+
+// Helper: Show system info
+function showInfo() {
+  console.log('📊 grimoire-FullStack System Information\n');
+  console.log(`Version: ${packageJson.version}`);
+  console.log(`Platform: ${process.platform}`);
+  console.log(`Node.js: ${process.version}`);
+  console.log(`Architecture: ${process.arch}`);
+  console.log(`Working Directory: ${process.cwd()}`);
+  console.log(`Install Location: ${path.join(__dirname, '..')}`);
+
+  // Check if .grimoire exists
+  const grimoireCoreDir = path.join(__dirname, '..', '.grimoire');
+  if (fs.existsSync(grimoireCoreDir)) {
+    console.log('\n✓ grimoire Core installed');
+
+    // Count components
+    const countFiles = (dir) => {
+      try {
+        return fs.readdirSync(dir).length;
+      } catch {
+        return 0;
+      }
+    };
+
+    console.log(`  - Agents: ${countFiles(path.join(grimoireCoreDir, 'development', 'agents'))}`);
+    console.log(`  - Tasks: ${countFiles(path.join(grimoireCoreDir, 'development', 'tasks'))}`);
+    console.log(`  - Templates: ${countFiles(path.join(grimoireCoreDir, 'development', 'templates'))}`);
+    console.log(`  - Workflows: ${countFiles(path.join(grimoireCoreDir, 'development', 'workflows'))}`);
+  } else {
+    console.log('\n⚠️  grimoire Core not found');
+  }
+
+  // Check grimoire Pro status (Task 5.1)
+  const proDir = path.join(__dirname, '..', 'pro');
+  if (fs.existsSync(proDir)) {
+    console.log('\n✓ grimoire Pro installed');
+
+    try {
+      const { featureGate } = require(path.join(proDir, 'license', 'feature-gate'));
+      const state = featureGate.getLicenseState();
+      const info = featureGate.getLicenseInfo();
+
+      const stateEmoji = {
+        'Active': '✅',
+        'Grace': '⚠️',
+        'Expired': '❌',
+        'Not Activated': '➖',
+      };
+
+      console.log(`  - License: ${stateEmoji[state] || ''} ${state}`);
+
+      if (info && info.features) {
+        const availableCount = featureGate.listAvailable().length;
+        console.log(`  - Features: ${availableCount} available`);
+      }
+    } catch {
+      console.log('  - License: Unable to check status');
+    }
+  }
+}
+
+// Helper: Run installation validation
+async function runValidate() {
+  const validateArgs = args.slice(1); // Remove 'validate' from args
+
+  try {
+    // Load the validate command module
+    const { createValidateCommand } = require('../.grimoire/cli/commands/validate/index.js');
+    const validateCmd = createValidateCommand();
+
+    // Parse and execute (Note: don't include 'validate' as it's the command name, not an argument)
+    await validateCmd.parseAsync(['node', 'grimoire', ...validateArgs]);
+  } catch (_error) {
+    // Fallback: Run quick validation inline
+    console.log('Running installation validation...\n');
+
+    try {
+      const validatorPath = path.join(
+        __dirname,
+        '..',
+        'packages',
+        'installer',
+        'src',
+        'installer',
+        'post-install-validator.js',
+      );
+      const { PostInstallValidator, formatReport } = require(validatorPath);
+
+      const projectRoot = process.cwd();
+      const validator = new PostInstallValidator(projectRoot, path.join(__dirname, '..'));
+      const report = await validator.validate();
+
+      console.log(formatReport(report, { colors: true }));
+
+      if (
+        report.status === 'failed' ||
+        report.stats.missingFiles > 0 ||
+        report.stats.corruptedFiles > 0
+      ) {
+        process.exit(1);
+      }
+    } catch (validatorError) {
+      console.error(`❌ Validation error: ${validatorError.message}`);
+      if (args.includes('--verbose') || args.includes('-v')) {
+        console.error(validatorError.stack);
+      }
+      process.exit(2);
+    }
+  }
+}
+
+// Helper: Run update command
+async function runUpdate() {
+  const updateArgs = args.slice(1);
+  const isCheck = updateArgs.includes('--check');
+  const isDryRun = updateArgs.includes('--dry-run');
+  const isForce = updateArgs.includes('--force');
+  const isVerbose = updateArgs.includes('--verbose') || updateArgs.includes('-v');
+
+  try {
+    const updaterPath = path.join(__dirname, '..', 'packages', 'installer', 'src', 'updater', 'index.js');
+
+    if (!fs.existsSync(updaterPath)) {
+      console.error('❌ Updater module not found');
+      console.error('Please ensure grimoire-FullStack is installed correctly.');
+      process.exit(1);
+    }
+
+    const { grimoireUpdater, formatCheckResult, formatUpdateResult } = require(updaterPath);
+
+    const updater = new grimoireUpdater(process.cwd(), {
+      verbose: isVerbose,
+      force: isForce,
+    });
+
+    if (isCheck) {
+      // Check only mode
+      console.log('🔍 Checking for updates...\n');
+      const result = await updater.checkForUpdates();
+      console.log(formatCheckResult(result, { colors: true }));
+
+      if (result.status === 'check_failed') {
+        process.exit(1);
+      }
+    } else {
+      // Update mode
+      console.log('🔄 grimoire Update\n');
+
+      const result = await updater.update({
+        dryRun: isDryRun,
+        onProgress: (phase, message) => {
+          if (isVerbose) {
+            console.log(`[${phase}] ${message}`);
+          }
+        },
+      });
+
+      console.log(formatUpdateResult(result, { colors: true }));
+
+      if (!result.success && result.error !== 'Already up to date') {
+        process.exit(1);
+      }
+    }
+  } catch (error) {
+    console.error(`❌ Update error: ${error.message}`);
+    if (args.includes('--verbose') || args.includes('-v')) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Helper: Run doctor diagnostics
+async function runDoctor() {
+  const doctorArgs = args.slice(1);
+  const shouldFix = doctorArgs.includes('--fix');
+  const isDryRun = doctorArgs.includes('--dry-run');
+  const showHelp = doctorArgs.includes('--help') || doctorArgs.includes('-h');
+
+  if (showHelp) {
+    console.log(`
+Usage: grimoire doctor [options]
+
+Run system diagnostics and optionally fix issues.
+
+Options:
+  --fix          Attempt to automatically fix detected issues
+  --dry-run      Show what would be fixed without making changes
+  -h, --help     Show this help message
+
+Examples:
+  $ npx grimoire-framework doctor              # Run diagnostics
+  $ npx grimoire-framework doctor --fix        # Fix detected issues
+  $ npx grimoire-framework doctor --dry-run    # Preview fixes
+`);
+    return;
+  }
+
+  console.log('🏥 grimoire System Diagnostics\n');
+
+  const issues = [];
+  let hasErrors = false;
+
+  // Helper: Compare semver versions
+  const compareVersions = (a, b) => {
+    const pa = a.split('.').map((n) => parseInt(n, 10));
+    const pb = b.split('.').map((n) => parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+      const na = pa[i] || 0;
+      const nb = pb[i] || 0;
+      if (na > nb) return 1;
+      if (na < nb) return -1;
+    }
+    return 0;
+  };
+
+  // Check 1: Node.js version
+  const nodeVersion = process.version.replace('v', '');
+  const requiredNodeVersion = '18.0.0';
+  const nodeOk = compareVersions(nodeVersion, requiredNodeVersion) >= 0;
+
+  if (!nodeOk) {
+    issues.push({
+      type: 'node_version',
+      autoFix: false,
+      message: `Node.js version: ${process.version} (requires >=18.0.0)`,
+      suggestion: 'nvm install 20 && nvm use 20',
+    });
+    hasErrors = true;
+  }
+  console.log(
+    `${nodeOk ? '✔' : '✗'} Node.js version: ${process.version} ${nodeOk ? '(meets requirement: >=18.0.0)' : '(requires >=18.0.0)'}`,
+  );
+
+  // Check 2: npm
+  try {
+    const npmVersion = execSync('npm --version', { encoding: 'utf8' }).trim();
+    console.log(`✔ npm version: ${npmVersion}`);
+  } catch {
+    issues.push({
+      type: 'npm',
+      autoFix: false,
+      message: 'npm not found',
+      suggestion: 'Install Node.js from https://nodejs.org (includes npm)',
+    });
+    console.log('✗ npm not found');
+    hasErrors = true;
+  }
+
+  // Check 3: Git
+  try {
+    const gitVersion = execSync('git --version', { encoding: 'utf8' }).trim();
+    console.log(`✔ Git installed: ${gitVersion}`);
+  } catch {
+    issues.push({
+      type: 'git',
+      autoFix: false,
+      message: 'Git not found (optional but recommended)',
+      suggestion: 'Install Git from https://git-scm.com',
+    });
+    console.log('⚠️  Git not found (optional but recommended)');
+  }
+
+  // Check 4: grimoire installation
+  const grimoireCoreDir = path.join(__dirname, '..', '.grimoire');
+  if (fs.existsSync(grimoireCoreDir)) {
+    console.log(`✔ Grimoire: v${packageJson.version}`);
+
+    // Check for corruption using validate (if available)
+    try {
+      const validatorPath = path.join(__dirname, '..', 'packages', 'installer', 'src', 'installer', 'post-install-validator');
+      const { PostInstallValidator } = require(validatorPath);
+      const validator = new PostInstallValidator(process.cwd(), path.join(__dirname, '..'));
+      const report = await validator.validate();
+
+      if (report.stats && (report.stats.missingFiles > 0 || report.stats.corruptedFiles > 0)) {
+        issues.push({
+          type: 'grimoire_corrupted',
+          autoFix: true,
+          message: `grimoire Core: ${report.stats.missingFiles} missing, ${report.stats.corruptedFiles} corrupted files`,
+          fixAction: async () => {
+            console.log('  🔧 Repairing grimoire installation...');
+            await validator.repair();
+            console.log('  ✓ Repair complete');
+          },
+        });
+        hasErrors = true;
+        console.log(`⚠️  grimoire Core: ${report.stats.missingFiles} missing, ${report.stats.corruptedFiles} corrupted files`);
+      }
+    } catch {
+      // Validation not available, skip corruption check
+    }
+  } else {
+    issues.push({
+      type: 'grimoire_missing',
+      autoFix: true,
+      message: 'grimoire Core not installed',
+      fixAction: async () => {
+        console.log('  🔧 Installing grimoire...');
+        try {
+          execSync('npx grimoire-framework install --force --quiet', { stdio: 'inherit', timeout: 60000 });
+          console.log('  ✓ Installation complete');
+        } catch (installError) {
+          console.error(`  ✗ Installation failed: ${installError.message}`);
+          throw installError;
+        }
+      },
+    });
+    hasErrors = true;
+    console.log('✗ grimoire Core not installed');
+    console.log('  Run: npx grimoire-framework');
+  }
+
+  // Check 5: grimoire Pro status
+  const proDetector = require('./utils/pro-detector');
+  if (proDetector.isProAvailable()) {
+    console.log('✔ grimoire Pro: Active (Full Version)');
+  }
+
+  // Apply fixes if --fix
+  if (shouldFix && issues.length > 0) {
+    console.log('\n🔧 Attempting fixes...\n');
+
+    let fixed = 0;
+    let manual = 0;
+
+    for (const issue of issues) {
+      if (issue.autoFix && issue.fixAction) {
+        if (isDryRun) {
+          console.log(`  [DRY RUN] Would fix: ${issue.type}`);
+          fixed++;
+        } else {
+          try {
+            await issue.fixAction();
+            fixed++;
+          } catch (fixError) {
+            console.error(`  ✗ Failed to fix ${issue.type}: ${fixError.message}`);
+            manual++;
+          }
+        }
+      } else {
+        manual++;
+        console.log(`  ⚠️  ${issue.message}`);
+        console.log(`     💡 Fix: ${issue.suggestion}`);
+      }
+    }
+
+    console.log('');
+    if (isDryRun) {
+      console.log(`✅ Dry run completed - ${fixed} issues would be fixed`);
+      if (manual > 0) {
+        console.log(`⚠️  ${manual} issues require manual action`);
+      }
+    } else {
+      if (fixed > 0) {
+        console.log(`✅ Fixed ${fixed} issue${fixed > 1 ? 's' : ''}`);
+      }
+      if (manual > 0) {
+        console.log(`⚠️  ${manual} issue${manual > 1 ? 's' : ''} require manual action`);
+        process.exit(1);
+      }
+    }
+  } else {
+    // Summary (no --fix)
+    console.log('');
+    if (hasErrors) {
+      console.log('⚠️  Some issues were detected. Run with --fix to auto-repair.');
+      process.exit(1);
+    } else {
+      console.log('✅ All checks passed! Your installation is healthy.');
+    }
+  }
+}
+
+// Helper: Format bytes to human readable
+function formatBytes(bytes) {
+  if (bytes === 0) return '0 Bytes';
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+
+// Helper: Remove grimoire sections from .gitignore
+function cleanGitignore(gitignorePath) {
+  if (!fs.existsSync(gitignorePath)) return { removed: false };
+
+  const content = fs.readFileSync(gitignorePath, 'utf8');
+  const lines = content.split('\n');
+  const newLines = [];
+  let ingrimoireSection = false;
+  let removedLines = 0;
+
+  for (const line of lines) {
+    if (line.includes('# grimoire') || line.includes('# Added by grimoire')) {
+      ingrimoireSection = true;
+      removedLines++;
+      continue;
+    }
+    if (ingrimoireSection && line.trim() === '') {
+      ingrimoireSection = false;
+      continue;
+    }
+    if (ingrimoireSection) {
+      removedLines++;
+      continue;
+    }
+    newLines.push(line);
+  }
+
+  if (removedLines > 0) {
+    fs.writeFileSync(gitignorePath, newLines.join('\n'));
+    return { removed: true, lines: removedLines };
+  }
+  return { removed: false };
+}
+
+// Helper: Show uninstall help
+function showUninstallHelp() {
+  console.log(`
+Usage: npx grimoire-framework uninstall [options]
+
+Remove grimoire from the current project.
+
+Options:
+  --force      Skip confirmation prompt
+  --keep-data  Keep .grimoire/ directory (settings and history)
+  --dry-run    Show what would be removed without removing
+  -h, --help   Show this help message
+
+What gets removed:
+  - .grimoire/     Framework core files
+  - docs/stories/   Story files (if created by grimoire)
+  - squads/         Squad definitions
+  - .gitignore      grimoire-added entries only
+
+What is preserved (with --keep-data):
+  - .grimoire/          Project settings and agent history
+
+Exit Codes:
+  0  Uninstall successful
+  1  Uninstall failed or cancelled
+
+Examples:
+  # Interactive uninstall (with confirmation)
+  npx grimoire-framework uninstall
+
+  # Force uninstall without prompts
+  npx grimoire-framework uninstall --force
+
+  # See what would be removed
+  npx grimoire-framework uninstall --dry-run
+
+  # Uninstall but keep project data
+  npx grimoire-framework uninstall --keep-data
+`);
+}
+
+// Helper: Show doctor help
+function showDoctorHelp() {
+  console.log(`
+Usage: npx grimoire-framework doctor [options]
+
+Run health checks on your grimoire installation.
+
+Options:
+  --fix        Automatically fix detected issues
+  --dry-run    Show what --fix would do without making changes
+  --quiet      Minimal output (exit code only)
+  -h, --help   Show this help message
+
+Checks performed:
+  • Required directories exist (.grimoire/, .grimoire/)
+  • Configuration files are valid JSON/YAML
+  • Agent definitions are complete
+  • Task files have required fields
+  • Dependencies are installed
+
+Exit Codes:
+  0  All checks passed (or issues fixed with --fix)
+  1  Issues detected (run with --fix to repair)
+
+Examples:
+  # Run health check
+  npx grimoire-framework doctor
+
+  # Auto-fix detected issues
+  npx grimoire-framework doctor --fix
+
+  # Preview what would be fixed
+  npx grimoire-framework doctor --fix --dry-run
+`);
+}
+
+// Uninstall grimoire from project
+async function runUninstall(options = {}) {
+  const { force = false, keepData = false, dryRun = false, quiet = false } = options;
+  const cwd = process.cwd();
+
+  // Items to remove
+  const itemsToRemove = [
+    { path: '.grimoire', description: 'Framework core' },
+    { path: 'squads', description: 'Squad definitions' },
+  ];
+
+  // Optionally remove .grimoire
+  if (!keepData) {
+    itemsToRemove.push({ path: '.grimoire', description: 'Project data and settings' });
+  }
+
+  // Check what exists
+  const existingItems = itemsToRemove.filter(item =>
+    fs.existsSync(path.join(cwd, item.path)),
+  );
+
+  if (existingItems.length === 0) {
+    console.log('ℹ️  No grimoire installation found in this directory.');
+    return;
+  }
+
+  // Calculate total size
+  let totalSize = 0;
+  const itemSizes = [];
+
+  for (const item of existingItems) {
+    const itemPath = path.join(cwd, item.path);
+    try {
+      const stats = fs.statSync(itemPath);
+      if (stats.isDirectory()) {
+        // Simple recursive size calculation
+        const getSize = (dir) => {
+          let size = 0;
+          try {
+            const files = fs.readdirSync(dir);
+            for (const file of files) {
+              const filePath = path.join(dir, file);
+              const stat = fs.statSync(filePath);
+              if (stat.isDirectory()) {
+                size += getSize(filePath);
+              } else {
+                size += stat.size;
+              }
+            }
+          } catch { /* ignore errors */ }
+          return size;
+        };
+        const size = getSize(itemPath);
+        totalSize += size;
+        itemSizes.push({ ...item, size });
+      } else {
+        totalSize += stats.size;
+        itemSizes.push({ ...item, size: stats.size });
+      }
+    } catch {
+      itemSizes.push({ ...item, size: 0 });
+    }
+  }
+
+  // Show what will be removed
+  if (!quiet) {
+    console.log('\n📋 Items to be removed:\n');
+    for (const item of itemSizes) {
+      const sizeStr = item.size > 0 ? ` (${formatBytes(item.size)})` : '';
+      console.log(`  • ${item.path}/${sizeStr} - ${item.description}`);
+    }
+    console.log(`\n  Total: ${formatBytes(totalSize)}`);
+
+    // Check for .gitignore cleanup
+    const gitignorePath = path.join(cwd, '.gitignore');
+    if (fs.existsSync(gitignorePath)) {
+      const content = fs.readFileSync(gitignorePath, 'utf8');
+      if (content.includes('# grimoire') || content.includes('# Added by grimoire')) {
+        console.log('  • .gitignore grimoire entries will be cleaned');
+      }
+    }
+    console.log('');
+  }
+
+  // Dry run - stop here
+  if (dryRun) {
+    console.log('🔍 Dry run - no changes made.');
+    return;
+  }
+
+  // Confirmation
+  if (!force) {
+    const readline = require('readline');
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    const answer = await new Promise(resolve => {
+      rl.question('⚠️  Are you sure you want to uninstall grimoire? (y/N): ', resolve);
+    });
+    rl.close();
+
+    if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') {
+      console.log('❌ Uninstall cancelled.');
+      process.exit(1);
+    }
+  }
+
+  // Perform removal
+  if (!quiet) console.log('\n🗑️  Removing grimoire components...\n');
+
+  for (const item of existingItems) {
+    const itemPath = path.join(cwd, item.path);
+    try {
+      fs.rmSync(itemPath, { recursive: true, force: true });
+      if (!quiet) console.log(`  ✓ Removed ${item.path}/`);
+    } catch (error) {
+      console.error(`  ✗ Failed to remove ${item.path}: ${error.message}`);
+    }
+  }
+
+  // Clean .gitignore
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const gitignoreResult = cleanGitignore(gitignorePath);
+  if (gitignoreResult.removed && !quiet) {
+    console.log(`  ✓ Cleaned ${gitignoreResult.lines} grimoire entries from .gitignore`);
+  }
+
+  // Summary
+  if (!quiet) {
+    console.log('\n✅ grimoire has been uninstalled.');
+    if (keepData) {
+      console.log('   Your project data in .grimoire/ has been preserved.');
+    }
+    console.log('\n   To reinstall: npx grimoire-framework install');
+  }
+}
+
+// Helper: Show install help
+function showInstallHelp() {
+  console.log(`
+Usage: npx grimoire-framework install [options]
+
+Install grimoire in the current directory.
+
+Options:
+  --force      Overwrite existing grimoire installation
+  --quiet      Minimal output (no banner, no prompts) - ideal for CI/CD
+  --dry-run    Simulate installation without modifying files
+  --merge      Auto-merge existing config files (brownfield mode)
+  --no-merge   Disable merge option, use legacy overwrite behavior
+  -h, --help   Show this help message
+
+Smart Merge (Brownfield):
+  When installing in a project with existing config files (.env, CLAUDE.md),
+  grimoire can merge new settings while preserving your customizations.
+
+  - .env files: Adds new variables, preserves existing values
+  - CLAUDE.md: Updates grimoire sections, keeps your custom rules
+
+Exit Codes:
+  0  Installation successful
+  1  Installation failed
+
+Examples:
+  # Interactive installation
+  npx grimoire-framework install
+
+  # Force reinstall without prompts
+  npx grimoire-framework install --force
+
+  # Brownfield: merge configs automatically
+  npx grimoire-framework install --merge
+
+  # Silent install for CI/CD
+  npx grimoire-framework install --quiet --force
+
+  # Preview what would be installed
+  npx grimoire-framework install --dry-run
+`);
+}
+
+// Helper: Create new project
+// Helper: Show init help
+function showInitHelp() {
+  console.log(`
+Usage: npx grimoire-framework init <project-name> [options]
+
+Create a new grimoire project with the specified name.
+
+Options:
+  --force              Force creation in non-empty directory
+  --skip-install       Skip npm dependency installation
+  --template <name>    Use specific template (default: default)
+  -t <name>            Shorthand for --template
+  -h, --help           Show this help message
+
+Available Templates:
+  default     Full installation with all agents, tasks, and workflows
+  minimal     Essential files only (dev agent + basic tasks)
+  enterprise  Everything + dashboards + team integrations
+
+Examples:
+  npx grimoire-framework init my-project
+  npx grimoire-framework init my-project --template minimal
+  npx grimoire-framework init my-project --force --skip-install
+  npx grimoire-framework init . --template enterprise
+`);
+}
+
+async function initProject() {
+  // 1. Parse ALL args after 'init'
+  const initArgs = args.slice(1);
+
+  // 2. Handle --help FIRST (before creating any directories)
+  if (initArgs.includes('--help') || initArgs.includes('-h')) {
+    showInitHelp();
+    return;
+  }
+
+  // 3. Parse flags
+  const isForce = initArgs.includes('--force');
+  const skipInstall = initArgs.includes('--skip-install');
+
+  // Template with argument
+  const templateIndex = initArgs.findIndex((a) => a === '--template' || a === '-t');
+  let template = 'default';
+  if (templateIndex !== -1) {
+    template = initArgs[templateIndex + 1];
+    if (!template || template.startsWith('-')) {
+      console.error('❌ --template requires a template name');
+      console.error('Available templates: default, minimal, enterprise');
+      process.exit(1);
+    }
+  }
+
+  // Validate template
+  const validTemplates = ['default', 'minimal', 'enterprise'];
+  if (!validTemplates.includes(template)) {
+    console.error(`❌ Unknown template: ${template}`);
+    console.error(`Available templates: ${validTemplates.join(', ')}`);
+    process.exit(1);
+  }
+
+  // 4. Extract project name (anything that doesn't start with - and isn't a template value)
+  const projectName = initArgs.find((arg, i) => {
+    if (arg.startsWith('-')) return false;
+    // Skip if it's the value after --template
+    const prevArg = initArgs[i - 1];
+    if (prevArg === '--template' || prevArg === '-t') return false;
+    return true;
+  });
+
+  if (!projectName) {
+    console.error('❌ Project name is required');
+    console.log('\nUsage: npx grimoire-framework init <project-name> [options]');
+    console.log('Run with --help for more information.');
+    process.exit(1);
+  }
+
+  // 5. Handle "." to install in current directory
+  const isCurrentDir = projectName === '.';
+  const targetPath = isCurrentDir ? process.cwd() : path.join(process.cwd(), projectName);
+  const displayName = isCurrentDir ? path.basename(process.cwd()) : projectName;
+
+  // 6. Check if directory exists
+  if (fs.existsSync(targetPath) && !isCurrentDir) {
+    const contents = fs.readdirSync(targetPath).filter((f) => !f.startsWith('.'));
+    if (contents.length > 0 && !isForce) {
+      console.error(`❌ Directory already exists and is not empty: ${projectName}`);
+      console.error('Use --force to overwrite.');
+      process.exit(1);
+    }
+    if (contents.length > 0 && isForce) {
+      console.log(`⚠️  Using --force: overwriting existing directory: ${projectName}`);
+    } else {
+      console.log(`✓ Using existing empty directory: ${projectName}`);
+    }
+  } else if (!fs.existsSync(targetPath)) {
+    fs.mkdirSync(targetPath, { recursive: true });
+    console.log(`✓ Created directory: ${projectName}`);
+  }
+
+  console.log(`Creating new grimoire project: ${displayName}`);
+  if (template !== 'default') {
+    console.log(`Template: ${template}`);
+  }
+  if (skipInstall) {
+    console.log('Skip install: enabled');
+  }
+  console.log('');
+
+  // 7. Change to project directory (if not already there)
+  if (!isCurrentDir) {
+    process.chdir(targetPath);
+  }
+
+  // 8. Run the initialization wizard with options
+  await runWizard({
+    template,
+    skipInstall,
+    force: isForce,
+  });
+}
+
+// Command routing (async main function)
+async function main() {
+  switch (command) {
+    case 'workers':
+      // Service Discovery CLI - Story 2.7
+      try {
+        const { run } = require('../.grimoire/cli/index.js');
+        await run(process.argv);
+      } catch (error) {
+        console.error(`❌ Workers command error: ${error.message}`);
+        process.exit(1);
+      }
+      break;
+
+    case 'config':
+      // Layered Configuration CLI - Story PRO-4
+      try {
+        const { run } = require('../.grimoire/cli/index.js');
+        await run(process.argv);
+      } catch (error) {
+        console.error(`❌ Config command error: ${error.message}`);
+        process.exit(1);
+      }
+      break;
+
+    case 'pro':
+      // grimoire Pro License Management - Story PRO-6
+      try {
+        const { run } = require('../.grimoire/cli/index.js');
+        await run(process.argv);
+      } catch (error) {
+        console.error(`❌ Pro command error: ${error.message}`);
+        process.exit(1);
+      }
+      break;
+
+    case 'install': {
+      // Install in current project with flag support
+      const installArgs = args.slice(1);
+      if (installArgs.includes('--help') || installArgs.includes('-h')) {
+        showInstallHelp();
+        break;
+      }
+      const installOptions = {
+        force: installArgs.includes('--force'),
+        quiet: installArgs.includes('--quiet'),
+        dryRun: installArgs.includes('--dry-run'),
+        forceMerge: installArgs.includes('--merge'),
+        noMerge: installArgs.includes('--no-merge'),
+      };
+      if (!installOptions.quiet) {
+        console.log('grimoire-FullStack Installation\n');
+      }
+      await runWizard(installOptions);
+      break;
+    }
+
+    case 'uninstall': {
+      // Uninstall grimoire from project
+      const uninstallArgs = args.slice(1);
+      if (uninstallArgs.includes('--help') || uninstallArgs.includes('-h')) {
+        showUninstallHelp();
+        break;
+      }
+      const uninstallOptions = {
+        force: uninstallArgs.includes('--force'),
+        keepData: uninstallArgs.includes('--keep-data'),
+        dryRun: uninstallArgs.includes('--dry-run'),
+        quiet: uninstallArgs.includes('--quiet'),
+      };
+      await runUninstall(uninstallOptions);
+      break;
+    }
+
+    case 'init': {
+      // Create new project (flags parsed inside initProject)
+      await initProject();
+      break;
+    }
+
+    case 'info':
+      showInfo();
+      break;
+
+    case 'doctor': {
+      // Run health check with flag support
+      const doctorArgs = args.slice(1);
+      if (doctorArgs.includes('--help') || doctorArgs.includes('-h')) {
+        showDoctorHelp();
+        break;
+      }
+      const doctorOptions = {
+        fix: doctorArgs.includes('--fix'),
+        dryRun: doctorArgs.includes('--dry-run'),
+        quiet: doctorArgs.includes('--quiet'),
+      };
+      await runDoctor(doctorOptions);
+      break;
+    }
+
+    case 'validate':
+      // Post-installation validation - Story 6.19
+      await runValidate();
+      break;
+
+    case 'update':
+      // Update to latest version - Epic 7
+      await runUpdate();
+      break;
+
+    case '--version':
+    case '-v':
+    case '-V':
+      await showVersion();
+      break;
+
+    case '--help':
+    case '-h':
+      showHelp();
+      break;
+
+    case undefined:
+      // No arguments - run wizard directly (npx default behavior)
+      console.log('grimoire-FullStack Installation\n');
+      await runWizard();
+      break;
+
+    default:
+      console.error(`❌ Unknown command: ${command}`);
+      console.log('\nRun with --help to see available commands');
+      process.exit(1);
+  }
+}
+
+// Execute main function
+main().catch((error) => {
+  console.error('❌ Fatal error:', error.message);
+  process.exit(1);
+});
+
+