filemayor 3.6.0 → 4.0.5

package/index.js

@@ -1,877 +1,895 @@
-#!/usr/bin/env node
-
-/**
- * ═══════════════════════════════════════════════════════════════════
- *
- *   ███████╗██╗██╗     ███████╗███╗   ███╗ █████╗ ██╗   ██╗ ██████╗ ██████╗
- *   ██╔════╝██║██║     ██╔════╝████╗ ████║██╔══██╗╚██╗ ██╔╝██╔═══██╗██╔══██╗
- *   █████╗  ██║██║     █████╗  ██╔████╔██║███████║ ╚████╔╝ ██║   ██║██████╔╝
- *   ██╔══╝  ██║██║     ██╔══╝  ██║╚██╔╝██║██╔══██║  ╚██╔╝  ██║   ██║██╔══██╗
- *   ██║     ██║███████╗███████╗██║ ╚═╝ ██║██║  ██║   ██║   ╚██████╔╝██║  ██║
- *   ╚═╝     ╚═╝╚══════╝╚══════╝╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝
- *
- *   Your Digital Life Organizer — CLI Edition
- *   Created by Lehlohonolo Goodwill Nchefu (Chevza)
- *   Works everywhere: terminals, servers, data centers, CI/CD
- *
- * ═══════════════════════════════════════════════════════════════════
- */
-
-'use strict';
-
-// ─── Load .env (zero-dependency) ─────────────────────────────────
-try {
-    const _fs = require('fs');
-    const _path = require('path');
-    const envPath = _path.join(__dirname, '..', '.env');
-    _fs.readFileSync(envPath, 'utf-8').split('\n').forEach(line => {
-        const trimmed = line.trim();
-        if (trimmed && !trimmed.startsWith('#')) {
-            const [key, ...vals] = trimmed.split('=');
-            if (key && vals.length && !process.env[key.trim()]) {
-                process.env[key.trim()] = vals.join('=').trim();
-            }
-        }
-    });
-} catch { /* .env not found — that's fine, user may set env vars directly */ }
-
-const path = require('path');
-const os = require('os');
-const fs = require('fs');
-
-// Core modules
-const { scan, scanByCategory, scanSummary } = require('./core/scanner');
-const { organize, generatePlan, rollback, loadJournal } = require('./core/organizer');
-const { findJunk, clean } = require('./core/cleaner');
-const { FileWatcher } = require('./core/watcher');
-const { loadConfig, createConfigFile } = require('./core/config');
-const { analyzeDirectory } = require('./core/analyzer');
-const reporter = require('./core/reporter');
-const { formatBytes } = require('./core/scanner');
-const { getCategories } = require('./core/categories');
-const { checkPermissions } = require('./core/security');
-const { activateLicense, deactivateLicense, getLicenseInfo, checkProFeature, checkBulkLimit } = require('./core/license');
-const { ExplainEngine, CureEngine, ApplyEngine, DedupeEngine } = require('./core/index');
-
-const { c, banner, Spinner, success, error, warn, info } = reporter;
-
-// ─── Version ──────────────────────────────────────────────────────
-const VERSION = '3.6.0';
-
-// ─── Path Helpers ─────────────────────────────────────────────────
-
-/**
- * Expand ~ to user home directory (cross-platform).
- * On Unix shells, ~ is expanded by the shell before reaching Node.
- * On Windows PowerShell, it is NOT — so we handle it here.
- */
-function expandTilde(p) {
-    if (!p) return p;
-    if (p === '~') return os.homedir();
-    if (p.startsWith('~/') || p.startsWith('~\\')) {
-        return path.join(os.homedir(), p.slice(2));
-    }
-    return p;
-}
-
-// ─── Argument Parser ──────────────────────────────────────────────
-
-function parseArgs(argv) {
-    const args = {
-        command: null,
-        target: null,
-        flags: {},
-        positional: []
-    };
-
-    const raw = argv.slice(2);
-    let i = 0;
-
-    while (i < raw.length) {
-        const arg = raw[i];
-
-        if (arg === '--help' || arg === '-h') {
-            args.flags.help = true;
-        } else if (arg === '--version' || arg === '-V') {
-            args.flags.version = true;
-        } else if (arg === '--dry-run') {
-            args.flags.dryRun = true;
-        } else if (arg === '--json') {
-            args.flags.format = 'json';
-        } else if (arg === '--csv') {
-            args.flags.format = 'csv';
-        } else if (arg === '--minimal') {
-            args.flags.format = 'minimal';
-        } else if (arg === '--yes' || arg === '-y') {
-            args.flags.yes = true;
-        } else if (arg === '--verbose' || arg === '-v') {
-            args.flags.verbose = true;
-        } else if (arg === '--quiet' || arg === '-q') {
-            args.flags.quiet = true;
-        } else if (arg === '--no-color') {
-            args.flags.noColor = true;
-        } else if (arg === '--recursive' || arg === '-r') {
-            args.flags.recursive = true;
-        } else if (arg === '--depth' && raw[i + 1]) {
-            args.flags.depth = parseInt(raw[++i], 10);
-        } else if (arg === '--naming' && raw[i + 1]) {
-            args.flags.naming = raw[++i];
-        } else if (arg === '--output' && raw[i + 1]) {
-            args.flags.outputDir = raw[++i];
-        } else if (arg === '--config' && raw[i + 1]) {
-            args.flags.config = raw[++i];
-        } else if (arg === '--duplicates' && raw[i + 1]) {
-            args.flags.duplicates = raw[++i];
-        } else if (arg === '--extensions' && raw[i + 1]) {
-            args.flags.extensions = raw[++i].split(',');
-        } else if (arg === '--category' && raw[i + 1]) {
-            args.flags.category = raw[++i].split(',');
-        } else if (arg === '--min-size' && raw[i + 1]) {
-            args.flags.minSize = parseSizeArg(raw[++i]);
-        } else if (arg === '--max-size' && raw[i + 1]) {
-            args.flags.maxSize = parseSizeArg(raw[++i]);
-        } else if (arg.startsWith('--')) {
-            // Unknown flag with potential value
-            const key = arg.slice(2).replace(/-([a-z])/g, (_, l) => l.toUpperCase());
-            if (raw[i + 1] && !raw[i + 1].startsWith('-')) {
-                args.flags[key] = raw[++i];
-            } else {
-                args.flags[key] = true;
-            }
-        } else if (arg.startsWith('-') && arg.length === 2) {
-            args.flags[arg.slice(1)] = true;
-        } else if (!args.command) {
-            args.command = arg;
-        } else if (!args.target) {
-            args.target = expandTilde(arg);
-        } else {
-            args.positional.push(arg);
-        }
-
-        i++;
-    }
-
-    return args;
-}
-
-function parseSizeArg(str) {
-    const match = str.match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb|tb)?$/i);
-    if (!match) return 0;
-    const num = parseFloat(match[1]);
-    const unit = (match[2] || 'b').toLowerCase();
-    const multipliers = { b: 1, kb: 1024, mb: 1024 ** 2, gb: 1024 ** 3, tb: 1024 ** 4 };
-    return Math.floor(num * (multipliers[unit] || 1));
-}
-
-// ─── Help Text ────────────────────────────────────────────────────
-
-function printHelp() {
-    console.log(`
-${banner()}
-  ${c('bold', 'USAGE')}
-    ${c('cyan', 'filemayor')} ${c('yellow', '<command>')} ${c('dim', '[path]')} ${c('dim', '[options]')}
-
-    ${c('yellow', 'explain')}    ${c('dim', '<path>')}    Diagnose folder health (Viral!)
-    ${c('yellow', 'cure')}       ${c('dim', '<path>')}    Plan treatment using AI
-    ${c('yellow', 'apply')}                Execute the cure plan
-    ${c('yellow', 'duplicates')} ${c('dim', '<path>')}    Find duplicate files
-    ${c('yellow', 'dedupe')}     ${c('dim', '<path>')}    Remove duplicate files
-
-  ${c('bold', 'COMMANDS')}
-    ${c('yellow', 'scan')}      ${c('dim', '<path>')}    Scan directory and report contents
-    ${c('yellow', 'analyze')}   ${c('dim', '<path>')}    Deep analysis (duplicates, bloat, savings)
-    ${c('yellow', 'organize')}  ${c('dim', '<path>')}    Organize files into categories
-    ${c('yellow', 'clean')}     ${c('dim', '<path>')}    Find and remove junk files
-    ${c('yellow', 'watch')}     ${c('dim', '<path>')}    Watch directory for changes ${c('magenta', '[PRO]')}
-    ${c('yellow', 'init')}                Create .filemayor.yml config
-    ${c('yellow', 'undo')}      ${c('dim', '<path>')}    Undo last organization
-    ${c('yellow', 'info')}                System info and version
-    ${c('yellow', 'license')}  ${c('dim', '<action>')}  Manage license (activate|status|deactivate)
-
-  ${c('bold', 'OPTIONS')}
-    ${c('dim', '--dry-run')}           Preview changes without executing
-    ${c('dim', '--json')}              Output as JSON
-    ${c('dim', '--csv')}               Output as CSV
-    ${c('dim', '--minimal')}           Minimal output (paths only)
-    ${c('dim', '--yes, -y')}           Skip confirmation prompts
-    ${c('dim', '--verbose, -v')}       Detailed logging
-    ${c('dim', '--quiet, -q')}         Suppress output (exit code only)
-    ${c('dim', '--no-color')}          Disable colored output
-    ${c('dim', '--config <path>')}     Custom config file
-    ${c('dim', '--depth <n>')}         Max recursion depth
-    ${c('dim', '--naming <type>')}     Naming: original|category_prefix|date_prefix|clean
-    ${c('dim', '--duplicates <s>')}    Duplicates: rename|skip|overwrite
-    ${c('dim', '--extensions <e>')}    Filter by extensions (comma-separated)
-    ${c('dim', '--output <path>')}     Output directory for organized files
-    ${c('dim', '--category <c>')}      Filter by category (comma-separated)
-    ${c('dim', '--min-size <s>')}      Minimum file size (e.g., 1mb)
-    ${c('dim', '--max-size <s>')}      Maximum file size (e.g., 100mb)
-    ${c('dim', '--help, -h')}          Show this help
-    ${c('dim', '--version, -V')}       Show version
-
-  ${c('bold', 'EXAMPLES')}
-    ${c('dim', '$')} filemayor scan ~/Downloads
-    ${c('dim', '$')} filemayor organize ~/Downloads --dry-run
-    ${c('dim', '$')} filemayor organize ~/Downloads --naming category_prefix
-    ${c('dim', '$')} filemayor clean /var/tmp --yes
-    ${c('dim', '$')} filemayor scan . --json | jq '.files | length'
-    ${c('dim', '$')} filemayor watch ~/Downloads
-    ${c('dim', '$')} filemayor init
-
-  ${c('bold', 'INSTALL')}
-    ${c('dim', '$')} npm install -g filemayor
-
-  ${c('dim', `FileMayor v${VERSION} — https://filemayor.com`)}
-`);
-}
-
-// ─── Commands ─────────────────────────────────────────────────────
-
-async function cmdScan(target, flags, config) {
-    const targetPath = path.resolve(target || '.');
-    const format = flags.format || config.output.format;
-
-    const spinner = new Spinner(`Scanning ${c('cyan', targetPath)}...`);
-    if (format === 'table' && !flags.quiet) spinner.start();
-
-    try {
-        const options = {
-            maxDepth: flags.depth || config.scanner.maxDepth,
-            includeHidden: config.scanner.includeHidden,
-            ignore: config.organize.ignore,
-            extensions: flags.extensions || null,
-            minSize: flags.minSize || config.scanner.minSize,
-            maxSize: flags.maxSize || config.scanner.maxSize || Infinity,
-            followSymlinks: config.scanner.followSymlinks,
-        };
-
-        const result = scan(targetPath, options);
-
-        spinner.stop();
-
-        if (flags.quiet) {
-            process.exit(result.files.length > 0 ? 0 : 1);
-            return;
-        }
-
-        console.log(reporter.formatScanReport(result, format));
-    } catch (err) {
-        spinner.fail(err.message);
-        process.exit(1);
-    }
-}
-
-async function cmdAnalyze(target, flags, config) {
-    const targetPath = path.resolve(target || '.');
-    const format = flags.format || config.output.format;
-
-    const spinner = new Spinner(`Analyzing ${c('cyan', targetPath)}...`);
-    if (format === 'table' && !flags.quiet) spinner.start();
-
-    try {
-        const options = {
-            maxDepth: flags.depth || config.scanner.maxDepth,
-            minSize: flags.minSize || 1024,
-        };
-
-        const result = analyzeDirectory(targetPath, options);
-
-        spinner.stop();
-
-        if (flags.quiet) {
-            process.exit(result.summary.potentialSavings > 0 ? 0 : 1);
-            return;
-        }
-
-        console.log(reporter.formatAnalyzeReport(result, format));
-    } catch (err) {
-        spinner.fail(err.message);
-        process.exit(1);
-    }
-}
-
-async function cmdOrganize(target, flags, config) {
-    const targetPath = path.resolve(target || '.');
-    const format = flags.format || config.output.format;
-    const dryRun = flags.dryRun || false;
-
-    const spinner = new Spinner(`${dryRun ? 'Planning' : 'Organizing'} ${c('cyan', targetPath)}...`);
-    if (format === 'table' && !flags.quiet) spinner.start();
-
-    try {
-        const result = organize(targetPath, {
-            dryRun,
-            naming: flags.naming || config.organize.naming,
-            outputDir: flags.outputDir || null,
-            duplicateStrategy: flags.duplicates || config.organize.duplicates,
-            scanOptions: {
-                maxDepth: flags.depth || config.organize.maxDepth,
-                includeHidden: config.organize.includeHidden,
-                ignore: config.organize.ignore,
-                extensions: flags.extensions || null,
-            },
-            onProgress: format === 'table' ? (p) => {
-                spinner.update(`${dryRun ? 'Planning' : 'Organizing'} ${p.percent}% — ${p.file}`);
-            } : null,
-        });
-
-        spinner.stop();
-
-        if (flags.quiet) {
-            process.exit(0);
-            return;
-        }
-
-        console.log(reporter.formatOrganizeReport(result, format));
-
-        if (!dryRun && result.execSummary) {
-            const exec = result.execSummary;
-            if (exec.failed > 0) process.exit(1);
-        }
-    } catch (err) {
-        spinner.fail(err.message);
-        process.exit(1);
-    }
-}
-
-async function cmdClean(target, flags, config) {
-    const targetPath = path.resolve(target || '.');
-    const format = flags.format || config.output.format;
-    const dryRun = flags.dryRun || !flags.yes;
-
-    // If --yes not passed and not --dry-run, force dry run
-    if (!flags.yes && !flags.dryRun) {
-        console.log(warn('Running in dry-run mode. Use --yes to actually delete files.'));
-    }
-
-    const spinner = new Spinner(`Scanning for junk in ${c('cyan', targetPath)}...`);
-    if (format === 'table' && !flags.quiet) spinner.start();
-
-    try {
-        const result = clean(targetPath, {
-            dryRun,
-            categories: flags.category || config.clean.categories,
-            maxDepth: flags.depth || config.clean.maxDepth,
-            includeDirectories: config.clean.includeDirectories,
-            onProgress: format === 'table' ? (p) => {
-                spinner.update(`${p.phase === 'scanning' ? 'Scanning' : 'Deleting'} ${p.current || ''}...`);
-            } : null,
-        });
-
-        spinner.stop();
-
-        if (flags.quiet) {
-            process.exit(result.junk.length > 0 ? 0 : 1);
-            return;
-        }
-
-        console.log(reporter.formatCleanReport(result, format));
-    } catch (err) {
-        spinner.fail(err.message);
-        process.exit(1);
-    }
-}
-
-async function cmdWatch(target, flags, config) {
-    // Pro feature gate
-    const gate = checkProFeature('watch', 'Watch Mode');
-    if (!gate.allowed) {
-        console.log(gate.message);
-        process.exit(0);
-    }
-
-    const targetPath = path.resolve(target || '.');
-    const format = flags.format || config.output.format;
-
-    console.log(banner());
-    console.log(info(`Watching ${c('cyan', targetPath)} for changes...`));
-    console.log(c('dim', '  Press Ctrl+C to stop\n'));
-
-    const watcher = new FileWatcher({
-        directories: [targetPath, ...(config.watch.directories || [])],
-        rules: config.watch.rules || [],
-        debounceMs: config.watch.debounceMs || 500,
-        recursive: flags.recursive !== false,
-        autoOrganize: config.watch.autoOrganize || false,
-        organizeOptions: {
-            naming: config.organize.naming,
-            duplicateStrategy: config.organize.duplicates,
-        },
-    });
-
-    watcher.on('watching', (data) => {
-        console.log(success(`Watching: ${data.directory}`));
-    });
-
-    watcher.on('change', (event) => {
-        if (format === 'json') {
-            console.log(JSON.stringify(event));
-        } else {
-            const action = event.exists
-                ? c('green', event.type === 'rename' ? 'NEW' : 'CHG')
-                : c('red', 'DEL');
-            const cat = event.category ? c('dim', ` [${event.category}]`) : '';
-            console.log(`  ${action} ${event.filename}${cat} ${c('dim', event.sizeHuman)}`);
-        }
-    });
-
-    watcher.on('action', (data) => {
-        console.log(`  ${c('yellow', '→')} ${data.action}: ${path.basename(data.source)} → ${data.destination || ''}`);
-    });
-
-    watcher.on('error', (err) => {
-        console.error(error(err.error || err.message));
-    });
-
-    watcher.start();
-
-    // Handle shutdown
-    process.on('SIGINT', () => {
-        console.log('\n');
-        watcher.stop();
-        const stats = watcher.getStats();
-        console.log(info(`Processed ${stats.eventsProcessed} events, ${stats.filesActioned} actions`));
-        process.exit(0);
-    });
-}
-
-async function cmdInit(flags) {
-    try {
-        const configPath = createConfigFile(process.cwd());
-        console.log(success(`Created ${c('cyan', configPath)}`));
-        console.log(c('dim', '  Edit this file to customize FileMayor settings'));
-    } catch (err) {
-        console.error(error(err.message));
-        process.exit(1);
-    }
-}
-
-async function cmdUndo(target, flags) {
-    const targetPath = path.resolve(target || '.');
-    const journalPath = path.join(targetPath, '.filemayor-journal.json');
-
-    const journal = loadJournal(journalPath);
-    if (journal.length === 0) {
-        console.log(info('No operations to undo'));
-        return;
-    }
-
-    console.log(info(`Found ${journal.length} operations to undo`));
-
-    const spinner = new Spinner('Undoing operations...');
-    spinner.start();
-
-    const result = rollback(journal, {
-        onProgress: (p) => {
-            spinner.update(`Undoing ${p.percent}% — ${p.file}`);
-        }
-    });
-
-    spinner.stop();
-    console.log(success(`Undone ${result.undone} operations`));
-    if (result.failed > 0) {
-        console.log(warn(`${result.failed} operations could not be undone`));
-        for (const err of result.errors) {
-            console.log(c('dim', `  ${err}`));
-        }
-    }
-
-    // Clear journal
-    try {
-        fs.writeFileSync(journalPath, '[]', 'utf8');
-    } catch { /* ignore */ }
-}
-
-// ==================== DIAGNOSTIC TRIAD (v3.5) ====================
-
-let activePlanState = null;
-
-async function cmdExplain(target, flags) {
-    const targetPath = path.resolve(target || '.');
-    const spinner = new Spinner(`Diagnosing ${c('cyan', targetPath)}...`);
-    spinner.start();
-
-    try {
-        const engine = new ExplainEngine();
-        const result = engine.run(targetPath);
-        spinner.stop();
-        console.log(reporter.formatExplainReport(result));
-    } catch (err) {
-        spinner.fail(err.message);
-        process.exit(1);
-    }
-}
-
-async function cmdCure(target, flags) {
-    const targetPath = path.resolve(target || '.');
-    const prompt = flags.prompt || 'Clean up this folder and group similar files.';
-    
-    if (!process.env.GEMINI_API_KEY) {
-        console.log(error('GEMINI_API_KEY environment variable is required for AI curative features.'));
-        process.exit(1);
-    }
-
-    const spinner = new Spinner(`Consulting AI for ${c('cyan', targetPath)}...`);
-    spinner.start();
-
-    try {
-        const engine = new CureEngine(targetPath, process.env.GEMINI_API_KEY);
-        activePlanState = await engine.generatePlan(prompt);
-        spinner.stop();
-        
-        // Cache plan locally for 'apply' command
-        const cachePath = path.join(os.tmpdir(), 'filemayor-plan.json');
-        fs.writeFileSync(cachePath, JSON.stringify(activePlanState), 'utf8');
-        
-        console.log(reporter.formatCureReport(activePlanState));
-    } catch (err) {
-        spinner.fail(err.message);
-        process.exit(1);
-    }
-}
-
-async function cmdApply(flags) {
-    const cachePath = path.join(os.tmpdir(), 'filemayor-plan.json');
-    if (!fs.existsSync(cachePath)) {
-        console.log(error('No plan found. Run "filemayor cure" first.'));
-        process.exit(1);
-    }
-
-    const plan = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
-
-    // [Sprint B] Logic Guardrail: Check batch volume & destructive patterns
-    const LogicGuardrail = require('./core/guardrail');
-    const { FileMayorJailer } = require('./core/jailer');
-    const guardrail = new LogicGuardrail(50);
-    const jailer = new FileMayorJailer(process.cwd());
-
-    if (plan.plan && Array.isArray(plan.plan)) {
-        const approved = await guardrail.verifyBatch(plan.plan);
-        if (!approved) {
-            console.log(warn('Operation cancelled by user.'));
-            return;
-        }
-
-        // [Sprint B] Jailer: Validate every move before execution
-        const blocked = [];
-        for (const step of plan.plan) {
-            const check = jailer.validateMove(step.source, step.destination);
-            if (!check.safe) {
-                blocked.push({ file: path.basename(step.source), reason: check.error });
-            }
-        }
-        if (blocked.length > 0) {
-            console.log(error(`Jailer blocked ${blocked.length} unsafe operations:`));
-            for (const b of blocked) {
-                console.log(c('dim', `  ✗ ${b.file}: ${b.reason}`));
-            }
-            plan.plan = plan.plan.filter(step => jailer.validateMove(step.source, step.destination).safe);
-            if (plan.plan.length === 0) {
-                console.log(error('No safe operations remain. Aborting.'));
-                return;
-            }
-            console.log(info(`Proceeding with ${plan.plan.length} safe operations.`));
-        }
-    }
-
-    const spinner = new Spinner(`Executing cure...`);
-    spinner.start();
-
-    try {
-        const engine = new ApplyEngine();
-        const result = await engine.apply(plan, (p) => {
-            spinner.update(`Relocating: ${p.index}/${p.total} — ${path.basename(p.current || '')}`);
-        });
-        spinner.succeed(`Cure applied! ${result.stats.success} files moved.`);
-        fs.unlinkSync(cachePath); // Clear plan
-    } catch (err) {
-        spinner.fail(err.message);
-        process.exit(1);
-    }
-}
-
-async function cmdDuplicates(target, flags) {
-    const targetPath = path.resolve(target || '.');
-    const spinner = new Spinner(`Hunting duplicates in ${c('cyan', targetPath)}...`);
-    spinner.start();
-
-    try {
-        const engine = new DedupeEngine();
-        const result = engine.find(targetPath);
-        spinner.stop();
-        console.log(reporter.formatDedupeReport(result));
-    } catch (err) {
-        spinner.fail(err.message);
-        process.exit(1);
-    }
-}
-
-async function cmdDedupe(target, flags) {
-    const targetPath = path.resolve(target || '.');
-    const spinner = new Spinner(`Deduplicating ${c('cyan', targetPath)}...`);
-    spinner.start();
-
-    try {
-        const engine = new DedupeEngine();
-        const report = engine.find(targetPath);
-        if (report.sets === 0) {
-            spinner.succeed('Total order restored: No duplicates found.');
-            return;
-        }
-
-        const result = await engine.clean(report);
-        spinner.succeed(`Purged ${result.deleted} duplicates. Reclaimed ${result.freedHuman}.`);
-    } catch (err) {
-        spinner.fail(err.message);
-        process.exit(1);
-    }
-}
-
-async function cmdInfo(config) {
-    console.log(banner());
-    console.log(`  ${c('bold', 'Version')}    ${VERSION}`);
-    console.log(`  ${c('bold', 'Node')}       ${process.version}`);
-    console.log(`  ${c('bold', 'Platform')}   ${os.platform()} ${os.arch()}`);
-    console.log(`  ${c('bold', 'OS')}         ${os.type()} ${os.release()}`);
-    console.log(`  ${c('bold', 'Home')}       ${os.homedir()}`);
-    console.log(`  ${c('bold', 'CWD')}        ${process.cwd()}`);
-
-    // Config info
-    console.log(`  ${c('bold', 'Config')}     ${config._source || 'defaults'}`);
-
-    // Categories
-    const cats = getCategories();
-    const catCount = Object.keys(cats).length;
-    const extCount = Object.values(cats).reduce((sum, cat) => sum + cat.extensions.length, 0);
-    console.log(`  ${c('bold', 'Categories')} ${catCount} categories, ${extCount} extensions`);
-
-    // Permissions
-    const perms = checkPermissions(process.cwd());
-    const permStr = `${perms.read ? c('green', 'R') : c('red', '-')}${perms.write ? c('green', 'W') : c('red', '-')}${perms.execute ? c('green', 'X') : c('red', '-')}`;
-    console.log(`  ${c('bold', 'Permissions')} ${permStr} (current directory)`);
-
-    console.log('');
-}
-
-// ─── License Command ──────────────────────────────────────────────
-
-async function cmdLicense(action, positional, flags) {
-    const subAction = action || 'status';
-
-    switch (subAction) {
-        case 'activate': {
-            const key = positional[0] || flags.key;
-            if (!key) {
-                console.error(error('Usage: filemayor license activate <key>'));
-                console.log(c('dim', '  Example: filemayor license activate FM-PRO-XXXX-XXXX-XXXXX'));
-                process.exit(1);
-            }
-            const result = activateLicense(key);
-            if (result.success) {
-                console.log(success(result.message));
-                console.log(c('dim', `  Tier: ${result.tier}`));
-            } else {
-                console.error(error(result.message));
-                process.exit(1);
-            }
-            break;
-        }
-
-        case 'deactivate':
-        case 'remove': {
-            const result = deactivateLicense();
-            if (result.success) {
-                console.log(success(result.message));
-            } else {
-                console.log(info(result.message));
-            }
-            break;
-        }
-
-        case 'status':
-        default: {
-            const li = getLicenseInfo();
-            console.log(banner());
-            console.log(c('bold', '  License Status'));
-            console.log(c('dim', `  ${'─'.repeat(40)}`));
-            console.log(`  ${c('bold', 'Tier:')}        ${li.active ? c('green', li.name) : c('yellow', 'Free')}`);
-            console.log(`  ${c('bold', 'Status:')}      ${li.active ? c('green', '● Active') : c('dim', '○ No license')}`);
-            if (li.key) {
-                const masked = li.key.substring(0, 7) + '****' + li.key.substring(li.key.length - 5);
-                console.log(`  ${c('bold', 'Key:')}         ${c('dim', masked)}`);
-            }
-            if (li.activatedAt) {
-                console.log(`  ${c('bold', 'Activated:')}   ${c('dim', new Date(li.activatedAt).toLocaleDateString())}`);
-            }
-            console.log('');
-            console.log(c('bold', '  Features'));
-            console.log(c('dim', `  ${'─'.repeat(40)}`));
-            const allFeatures = [
-                { id: 'scan', label: 'Directory Scanning', free: true },
-                { id: 'organize', label: 'File Organization', free: true },
-                { id: 'clean', label: 'Junk Cleanup', free: true },
-                { id: 'undo', label: 'Undo Operations', free: true },
-                { id: 'watch', label: 'Watch Mode', free: false },
-                { id: 'sop-ai', label: 'AI SOP Parsing', free: false },
-                { id: 'bulk-organize', label: 'Bulk Organize (50+ files)', free: false },
-                { id: 'csv-export', label: 'CSV Export', free: false },
-            ];
-            for (const feat of allFeatures) {
-                const has = li.features.includes('*') || li.features.includes(feat.id);
-                const icon = has ? c('green', '✓') : c('dim', '○');
-                const label = has ? feat.label : c('dim', feat.label);
-                const tag = !feat.free && !has ? c('magenta', ' [PRO]') : '';
-                console.log(`  ${icon}  ${label}${tag}`);
-            }
-            console.log('');
-            if (!li.active) {
-                console.log(c('dim', '  Get a license: https://filemayor.lemonsqueezy.com/checkout/buy/7fdcc87f-0660-4c1c-b3db-99f94773b71a'));
-                console.log(c('dim', '  Activate: filemayor license activate <key>'));
-                console.log('');
-            }
-            break;
-        }
-    }
-}
-
-// ─── Main Entry Point ─────────────────────────────────────────────
-
-async function main() {
-    const args = parseArgs(process.argv);
-
-    // Version
-    if (args.flags.version) {
-        console.log(VERSION);
-        return;
-    }
-
-    // Colors
-    if (args.flags.noColor || process.env.NO_COLOR) {
-        reporter.setColors(false);
-    }
-
-    // Load config
-    let config;
-    try {
-        const configResult = loadConfig({
-            configPath: args.flags.config || null,
-            cliOverrides: {},
-        });
-        config = configResult.config;
-        config._source = configResult.source;
-
-        // Show validation warnings
-        if (configResult.validation.warnings.length > 0 && args.flags.verbose) {
-            for (const w of configResult.validation.warnings) {
-                console.error(warn(`Config: ${w}`));
-            }
-        }
-        if (!configResult.validation.valid) {
-            for (const e of configResult.validation.errors) {
-                console.error(error(`Config: ${e}`));
-            }
-        }
-    } catch (err) {
-        console.error(error(`Config error: ${err.message}`));
-        process.exit(1);
-    }
-
-    // No command — show help
-    if (!args.command || args.flags.help) {
-        printHelp();
-        return;
-    }
-
-    // Route commands
-    switch (args.command) {
-        case 'scan':
-        case 's':
-            await cmdScan(args.target, args.flags, config);
-            break;
-
-        case 'explain':
-        case 'dx':
-            await cmdExplain(args.target, args.flags);
-            break;
-
-        case 'cure':
-        case 'plan':
-            await cmdCure(args.target, args.flags);
-            break;
-
-        case 'apply':
-        case 'exec':
-            await cmdApply(args.flags);
-            break;
-
-        case 'duplicates':
-        case 'dupes':
-            await cmdDuplicates(args.target, args.flags);
-            break;
-
-        case 'dedupe':
-            await cmdDedupe(args.target, args.flags);
-            break;
-
-        case 'analyze':
-        case 'a':
-            await cmdAnalyze(args.target, args.flags, config);
-            break;
-
-        case 'organize':
-        case 'org':
-        case 'o':
-            await cmdOrganize(args.target, args.flags, config);
-            break;
-
-        case 'clean':
-        case 'cl':
-        case 'c':
-            await cmdClean(args.target, args.flags, config);
-            break;
-
-        case 'watch':
-        case 'w':
-            await cmdWatch(args.target, args.flags, config);
-            break;
-
-        case 'init':
-        case 'i':
-            await cmdInit(args.flags);
-            break;
-
-        case 'undo':
-        case 'u':
-            await cmdUndo(args.target, args.flags);
-            break;
-
-        case 'info':
-            await cmdInfo(config);
-            break;
-
-        case 'license':
-        case 'lic':
-        case 'l':
-            await cmdLicense(args.target, args.positional, args.flags);
-            break;
-
-        case 'help':
-            printHelp();
-            break;
-
-        default:
-            console.error(error(`Unknown command: "${args.command}"`));
-            console.log(c('dim', 'Run "filemayor --help" for usage'));
-            process.exit(1);
-    }
-}
-
-// ─── Run ──────────────────────────────────────────────────────────
-
-main().catch(err => {
-    console.error(error(err.message));
-    if (process.env.DEBUG) {
-        console.error(err.stack);
-    }
-    process.exit(1);
-});
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ *
+ *   ███████╗██╗██╗     ███████╗███╗   ███╗ █████╗ ██╗   ██╗ ██████╗ ██████╗
+ *   ██╔════╝██║██║     ██╔════╝████╗ ████║██╔══██╗╚██╗ ██╔╝██╔═══██╗██╔══██╗
+ *   █████╗  ██║██║     █████╗  ██╔████╔██║███████║ ╚████╔╝ ██║   ██║██████╔╝
+ *   ██╔══╝  ██║██║     ██╔══╝  ██║╚██╔╝██║██╔══██║  ╚██╔╝  ██║   ██║██╔══██╗
+ *   ██║     ██║███████╗███████╗██║ ╚═╝ ██║██║  ██║   ██║   ╚██████╔╝██║  ██║
+ *   ╚═╝     ╚═╝╚══════╝╚══════╝╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝
+ *
+ *   Your Digital Life Organizer — CLI Edition
+ *   Created by Lehlohonolo Goodwill Nchefu (Chevza)
+ *   Works everywhere: terminals, servers, data centers, CI/CD
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+// ─── Load .env (zero-dependency) ─────────────────────────────────
+try {
+    const _fs = require('fs');
+    const _path = require('path');
+    const envPath = _path.join(__dirname, '..', '.env');
+    _fs.readFileSync(envPath, 'utf-8').split('\n').forEach(line => {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith('#')) {
+            const [key, ...vals] = trimmed.split('=');
+            if (key && vals.length && !process.env[key.trim()]) {
+                process.env[key.trim()] = vals.join('=').trim();
+            }
+        }
+    });
+} catch { /* .env not found — that's fine, user may set env vars directly */ }
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+// Core modules
+const { scan, scanByCategory, scanSummary } = require('./core/scanner');
+const { organize, generatePlan, rollback, loadJournal } = require('./core/organizer');
+const { findJunk, clean } = require('./core/cleaner');
+const { FileWatcher } = require('./core/watcher');
+const { loadConfig, createConfigFile } = require('./core/config');
+const { analyzeDirectory } = require('./core/analyzer');
+const reporter = require('./core/reporter');
+const { formatBytes } = require('./core/scanner');
+const { getCategories } = require('./core/categories');
+const { checkPermissions } = require('./core/security');
+const { activateLicense, deactivateLicense, getLicenseInfo, checkProFeature, checkBulkLimit } = require('./core/license');
+const { ExplainEngine, CureEngine, ApplyEngine, DedupeEngine } = require('./core/index');
+const { ping: telemetryPing } = require('./core/telemetry');
+
+const { c, banner, Spinner, success, error, warn, info } = reporter;
+
+// ─── Version ──────────────────────────────────────────────────────
+const VERSION = '4.0.5';
+
+// ─── Path Helpers ─────────────────────────────────────────────────
+
+/**
+ * Expand ~ to user home directory (cross-platform).
+ * On Unix shells, ~ is expanded by the shell before reaching Node.
+ * On Windows PowerShell, it is NOT — so we handle it here.
+ */
+function expandTilde(p) {
+    if (!p) return p;
+    if (p === '~') return os.homedir();
+    if (p.startsWith('~/') || p.startsWith('~\\')) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return p;
+}
+
+// ─── Argument Parser ──────────────────────────────────────────────
+
+function parseArgs(argv) {
+    const args = {
+        command: null,
+        target: null,
+        flags: {},
+        positional: []
+    };
+
+    const raw = argv.slice(2);
+    let i = 0;
+
+    while (i < raw.length) {
+        const arg = raw[i];
+
+        if (arg === '--help' || arg === '-h') {
+            args.flags.help = true;
+        } else if (arg === '--version' || arg === '-V') {
+            args.flags.version = true;
+        } else if (arg === '--dry-run') {
+            args.flags.dryRun = true;
+        } else if (arg === '--json') {
+            args.flags.format = 'json';
+        } else if (arg === '--csv') {
+            args.flags.format = 'csv';
+        } else if (arg === '--minimal') {
+            args.flags.format = 'minimal';
+        } else if (arg === '--yes' || arg === '-y') {
+            args.flags.yes = true;
+        } else if (arg === '--verbose' || arg === '-v') {
+            args.flags.verbose = true;
+        } else if (arg === '--quiet' || arg === '-q') {
+            args.flags.quiet = true;
+        } else if (arg === '--no-color') {
+            args.flags.noColor = true;
+        } else if (arg === '--recursive' || arg === '-r') {
+            args.flags.recursive = true;
+        } else if (arg === '--depth' && raw[i + 1]) {
+            args.flags.depth = parseInt(raw[++i], 10);
+        } else if (arg === '--naming' && raw[i + 1]) {
+            args.flags.naming = raw[++i];
+        } else if (arg === '--output' && raw[i + 1]) {
+            args.flags.outputDir = raw[++i];
+        } else if (arg === '--config' && raw[i + 1]) {
+            args.flags.config = raw[++i];
+        } else if (arg === '--duplicates' && raw[i + 1]) {
+            args.flags.duplicates = raw[++i];
+        } else if (arg === '--extensions' && raw[i + 1]) {
+            args.flags.extensions = raw[++i].split(',');
+        } else if (arg === '--category' && raw[i + 1]) {
+            args.flags.category = raw[++i].split(',');
+        } else if (arg === '--min-size' && raw[i + 1]) {
+            args.flags.minSize = parseSizeArg(raw[++i]);
+        } else if (arg === '--max-size' && raw[i + 1]) {
+            args.flags.maxSize = parseSizeArg(raw[++i]);
+        } else if (arg.startsWith('--')) {
+            // Unknown flag with potential value
+            const key = arg.slice(2).replace(/-([a-z])/g, (_, l) => l.toUpperCase());
+            if (raw[i + 1] && !raw[i + 1].startsWith('-')) {
+                args.flags[key] = raw[++i];
+            } else {
+                args.flags[key] = true;
+            }
+        } else if (arg.startsWith('-') && arg.length === 2) {
+            args.flags[arg.slice(1)] = true;
+        } else if (!args.command) {
+            args.command = arg;
+        } else if (!args.target) {
+            args.target = expandTilde(arg);
+        } else {
+            args.positional.push(arg);
+        }
+
+        i++;
+    }
+
+    return args;
+}
+
+function parseSizeArg(str) {
+    const match = str.match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb|tb)?$/i);
+    if (!match) return 0;
+    const num = parseFloat(match[1]);
+    const unit = (match[2] || 'b').toLowerCase();
+    const multipliers = { b: 1, kb: 1024, mb: 1024 ** 2, gb: 1024 ** 3, tb: 1024 ** 4 };
+    return Math.floor(num * (multipliers[unit] || 1));
+}
+
+// ─── Help Text ────────────────────────────────────────────────────
+
+function printHelp() {
+    console.log(`
+${banner()}
+  ${c('bold', 'USAGE')}
+    ${c('cyan', 'filemayor')} ${c('yellow', '<command>')} ${c('dim', '[path]')} ${c('dim', '[options]')}
+
+    ${c('yellow', 'explain')}    ${c('dim', '<path>')}    Diagnose folder health
+    ${c('yellow', 'cure')}       ${c('dim', '<path>')}    Plan treatment using AI
+    ${c('yellow', 'apply')}                Execute the cure plan
+    ${c('yellow', 'duplicates')} ${c('dim', '<path>')}    Find duplicate files
+    ${c('yellow', 'dedupe')}     ${c('dim', '<path>')}    Remove duplicate files
+
+  ${c('bold', 'COMMANDS')}
+    ${c('yellow', 'scan')}      ${c('dim', '<path>')}    Scan directory and report contents
+    ${c('yellow', 'analyze')}   ${c('dim', '<path>')}    Deep analysis (duplicates, bloat, savings)
+    ${c('yellow', 'organize')}  ${c('dim', '<path>')}    Organize files into categories
+    ${c('yellow', 'clean')}     ${c('dim', '<path>')}    Find and remove junk files
+    ${c('yellow', 'watch')}     ${c('dim', '<path>')}    Watch directory for changes
+    ${c('yellow', 'init')}                Create .filemayor.yml config
+    ${c('yellow', 'undo')}      ${c('dim', '<path>')}    Undo last organization
+    ${c('yellow', 'info')}                System info and version
+    ${c('yellow', 'license')}  ${c('dim', '<action>')}  Manage license (activate|status|deactivate)
+
+  ${c('bold', 'OPTIONS')}
+    ${c('dim', '--dry-run')}           Preview changes without executing
+    ${c('dim', '--json')}              Output as JSON
+    ${c('dim', '--csv')}               Output as CSV
+    ${c('dim', '--minimal')}           Minimal output (paths only)
+    ${c('dim', '--yes, -y')}           Skip confirmation prompts
+    ${c('dim', '--verbose, -v')}       Detailed logging
+    ${c('dim', '--quiet, -q')}         Suppress output (exit code only)
+    ${c('dim', '--no-color')}          Disable colored output
+    ${c('dim', '--config <path>')}     Custom config file
+    ${c('dim', '--depth <n>')}         Max recursion depth
+    ${c('dim', '--naming <type>')}     Naming: original|category_prefix|date_prefix|clean
+    ${c('dim', '--duplicates <s>')}    Duplicates: rename|skip|overwrite
+    ${c('dim', '--extensions <e>')}    Filter by extensions (comma-separated)
+    ${c('dim', '--output <path>')}     Output directory for organized files
+    ${c('dim', '--category <c>')}      Filter by category (comma-separated)
+    ${c('dim', '--min-size <s>')}      Minimum file size (e.g., 1mb)
+    ${c('dim', '--max-size <s>')}      Maximum file size (e.g., 100mb)
+    ${c('dim', '--help, -h')}          Show this help
+    ${c('dim', '--version, -V')}       Show version
+
+  ${c('bold', 'EXAMPLES')}
+    ${c('dim', '$')} filemayor scan ~/Downloads
+    ${c('dim', '$')} filemayor organize ~/Downloads --dry-run
+    ${c('dim', '$')} filemayor organize ~/Downloads --naming category_prefix
+    ${c('dim', '$')} filemayor clean /var/tmp --yes
+    ${c('dim', '$')} filemayor scan . --json | jq '.files | length'
+    ${c('dim', '$')} filemayor watch ~/Downloads
+    ${c('dim', '$')} filemayor init
+
+  ${c('bold', 'INSTALL')}
+    ${c('dim', '$')} npm install -g filemayor
+
+  ${c('dim', `FileMayor v${VERSION} — https://filemayor.com`)}
+`);
+}
+
+// ─── Commands ─────────────────────────────────────────────────────
+
+async function cmdScan(target, flags, config) {
+    const targetPath = path.resolve(target || '.');
+    const format = flags.format || config.output.format;
+
+    const spinner = new Spinner(`Scanning ${c('cyan', targetPath)}...`);
+    if (format === 'table' && !flags.quiet) spinner.start();
+
+    try {
+        const options = {
+            maxDepth: flags.depth || config.scanner.maxDepth,
+            includeHidden: config.scanner.includeHidden,
+            ignore: config.organize.ignore,
+            extensions: flags.extensions || null,
+            minSize: flags.minSize || config.scanner.minSize,
+            maxSize: flags.maxSize || config.scanner.maxSize || Infinity,
+            followSymlinks: config.scanner.followSymlinks,
+        };
+
+        const result = scan(targetPath, options);
+
+        spinner.stop();
+
+        if (flags.quiet) {
+            process.exit(result.files.length > 0 ? 0 : 1);
+            return;
+        }
+
+        console.log(reporter.formatScanReport(result, format));
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdAnalyze(target, flags, config) {
+    const targetPath = path.resolve(target || '.');
+    const format = flags.format || config.output.format;
+
+    const spinner = new Spinner(`Analyzing ${c('cyan', targetPath)}...`);
+    if (format === 'table' && !flags.quiet) spinner.start();
+
+    try {
+        const options = {
+            maxDepth: flags.depth || config.scanner.maxDepth,
+            minSize: flags.minSize || 1024,
+        };
+
+        const result = analyzeDirectory(targetPath, options);
+
+        spinner.stop();
+
+        if (flags.quiet) {
+            process.exit(result.summary.potentialSavings > 0 ? 0 : 1);
+            return;
+        }
+
+        console.log(reporter.formatAnalyzeReport(result, format));
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdOrganize(target, flags, config) {
+    const targetPath = path.resolve(target || '.');
+    const format = flags.format || config.output.format;
+    const dryRun = flags.dryRun || false;
+
+    const spinner = new Spinner(`${dryRun ? 'Planning' : 'Organizing'} ${c('cyan', targetPath)}...`);
+    if (format === 'table' && !flags.quiet) spinner.start();
+
+    try {
+        // Bulk limit check — generate plan first to count operations
+        if (!dryRun) {
+            const preview = await organize(targetPath, {
+                dryRun: true,
+                naming: flags.naming || config.organize.naming,
+                outputDir: flags.outputDir || null,
+                duplicateStrategy: flags.duplicates || config.organize.duplicates,
+                scanOptions: {
+                    maxDepth: flags.depth || config.organize.maxDepth,
+                    includeHidden: config.organize.includeHidden,
+                    ignore: config.organize.ignore,
+                    extensions: flags.extensions || null,
+                },
+            });
+            const opCount = preview?.plan?.length || 0;
+            const gate = checkBulkLimit(opCount);
+            if (!gate.allowed) {
+                spinner.stop();
+                console.log('\n' + gate.message);
+                process.exit(0);
+            }
+        }
+
+        const result = await organize(targetPath, {
+            dryRun,
+            naming: flags.naming || config.organize.naming,
+            outputDir: flags.outputDir || null,
+            duplicateStrategy: flags.duplicates || config.organize.duplicates,
+            scanOptions: {
+                maxDepth: flags.depth || config.organize.maxDepth,
+                includeHidden: config.organize.includeHidden,
+                ignore: config.organize.ignore,
+                extensions: flags.extensions || null,
+            },
+            onProgress: format === 'table' ? (p) => {
+                spinner.update(`${dryRun ? 'Planning' : 'Organizing'} ${p.percent}% — ${p.file}`);
+            } : null,
+        });
+
+        spinner.stop();
+
+        if (flags.quiet) {
+            process.exit(0);
+            return;
+        }
+
+        console.log(reporter.formatOrganizeReport(result, format));
+
+        if (!dryRun && result.execSummary) {
+            const exec = result.execSummary;
+            if (exec.failed > 0) process.exit(1);
+        }
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdClean(target, flags, config) {
+    const targetPath = path.resolve(target || '.');
+    const format = flags.format || config.output.format;
+    const dryRun = flags.dryRun || !flags.yes;
+
+    // If --yes not passed and not --dry-run, force dry run
+    if (!flags.yes && !flags.dryRun) {
+        console.log(warn('Running in dry-run mode. Use --yes to actually delete files.'));
+    }
+
+    const spinner = new Spinner(`Scanning for junk in ${c('cyan', targetPath)}...`);
+    if (format === 'table' && !flags.quiet) spinner.start();
+
+    try {
+        const result = clean(targetPath, {
+            dryRun,
+            categories: flags.category || config.clean.categories,
+            maxDepth: flags.depth || config.clean.maxDepth,
+            includeDirectories: config.clean.includeDirectories,
+            onProgress: format === 'table' ? (p) => {
+                spinner.update(`${p.phase === 'scanning' ? 'Scanning' : 'Deleting'} ${p.current || ''}...`);
+            } : null,
+        });
+
+        spinner.stop();
+
+        if (flags.quiet) {
+            process.exit(result.junk.length > 0 ? 0 : 1);
+            return;
+        }
+
+        console.log(reporter.formatCleanReport(result, format));
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdWatch(target, flags, config) {
+    const targetPath = path.resolve(target || '.');
+    const format = flags.format || config.output.format;
+
+    console.log(banner());
+    console.log(info(`Watching ${c('cyan', targetPath)} for changes...`));
+    console.log(c('dim', '  Press Ctrl+C to stop\n'));
+
+    const watcher = new FileWatcher({
+        directories: [targetPath, ...(config.watch.directories || [])],
+        rules: config.watch.rules || [],
+        debounceMs: config.watch.debounceMs || 500,
+        recursive: flags.recursive !== false,
+        autoOrganize: config.watch.autoOrganize || false,
+        organizeOptions: {
+            naming: config.organize.naming,
+            duplicateStrategy: config.organize.duplicates,
+        },
+    });
+
+    watcher.on('watching', (data) => {
+        console.log(success(`Watching: ${data.directory}`));
+    });
+
+    watcher.on('change', (event) => {
+        if (format === 'json') {
+            console.log(JSON.stringify(event));
+        } else {
+            const action = event.exists
+                ? c('green', event.type === 'rename' ? 'NEW' : 'CHG')
+                : c('red', 'DEL');
+            const cat = event.category ? c('dim', ` [${event.category}]`) : '';
+            console.log(`  ${action} ${event.filename}${cat} ${c('dim', event.sizeHuman)}`);
+        }
+    });
+
+    watcher.on('action', (data) => {
+        console.log(`  ${c('yellow', '→')} ${data.action}: ${path.basename(data.source)} → ${data.destination || ''}`);
+    });
+
+    watcher.on('error', (err) => {
+        console.error(error(err.error || err.message));
+    });
+
+    watcher.start();
+
+    // Handle shutdown
+    process.on('SIGINT', () => {
+        console.log('\n');
+        watcher.stop();
+        const stats = watcher.getStats();
+        console.log(info(`Processed ${stats.eventsProcessed} events, ${stats.filesActioned} actions`));
+        process.exit(0);
+    });
+}
+
+async function cmdInit(flags) {
+    try {
+        const configPath = createConfigFile(process.cwd());
+        console.log(success(`Created ${c('cyan', configPath)}`));
+        console.log(c('dim', '  Edit this file to customize FileMayor settings'));
+    } catch (err) {
+        console.error(error(err.message));
+        process.exit(1);
+    }
+}
+
+async function cmdUndo(target, flags) {
+    const { JOURNAL_PATH, rollback: fsRollback } = require('./core/fs-abstraction');
+
+    if (!fs.existsSync(JOURNAL_PATH)) {
+        console.log(info('No operations to undo (journal is empty)'));
+        return;
+    }
+
+    const spinner = new Spinner('Undoing operations...');
+    spinner.start();
+
+    try {
+        const result = await fsRollback(JOURNAL_PATH);
+        spinner.stop();
+        if (result.count === 0) {
+            console.log(info('Nothing to undo — no completed operations found in the journal'));
+        } else {
+            console.log(success(`Undone ${result.count} operation${result.count === 1 ? '' : 's'}`));
+        }
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+// ==================== DIAGNOSTIC TRIAD (v3.5) ====================
+
+let activePlanState = null;
+
+async function cmdExplain(target, flags) {
+    const targetPath = path.resolve(target || '.');
+    const spinner = new Spinner(`Diagnosing ${c('cyan', targetPath)}...`);
+    spinner.start();
+
+    try {
+        const engine = new ExplainEngine();
+        const result = engine.run(targetPath);
+        spinner.stop();
+        console.log(reporter.formatExplainReport(result));
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdCure(target, flags) {
+    const targetPath = path.resolve(target || '.');
+    const prompt = flags.prompt || 'Clean up this folder and group similar files.';
+    
+    if (!process.env.GEMINI_API_KEY) {
+        console.log(error('GEMINI_API_KEY environment variable is required for AI curative features.'));
+        process.exit(1);
+    }
+
+    const spinner = new Spinner(`Consulting AI for ${c('cyan', targetPath)}...`);
+    spinner.start();
+
+    try {
+        const engine = new CureEngine(targetPath, process.env.GEMINI_API_KEY);
+        activePlanState = await engine.generatePlan(prompt);
+        spinner.stop();
+        
+        // Cache plan locally for 'apply' command
+        const cachePath = path.join(os.tmpdir(), 'filemayor-plan.json');
+        fs.writeFileSync(cachePath, JSON.stringify(activePlanState), 'utf8');
+        
+        console.log(reporter.formatCureReport(activePlanState));
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdApply(flags) {
+    const cachePath = path.join(os.tmpdir(), 'filemayor-plan.json');
+    if (!fs.existsSync(cachePath)) {
+        console.log(error('No plan found. Run "filemayor cure" first.'));
+        process.exit(1);
+    }
+
+    const plan = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+
+    // [Sprint B] Logic Guardrail: Check batch volume & destructive patterns
+    const LogicGuardrail = require('./core/guardrail');
+    const { FileMayorJailer } = require('./core/jailer');
+    const guardrail = new LogicGuardrail(50);
+    const jailer = new FileMayorJailer(process.cwd());
+
+    if (plan.plan && Array.isArray(plan.plan)) {
+        const approved = await guardrail.verifyBatch(plan.plan);
+        if (!approved) {
+            console.log(warn('Operation cancelled by user.'));
+            return;
+        }
+
+        // [Sprint B] Jailer: Validate every move before execution
+        const blocked = [];
+        for (const step of plan.plan) {
+            const check = jailer.validateMove(step.source, step.destination);
+            if (!check.safe) {
+                blocked.push({ file: path.basename(step.source), reason: check.error });
+            }
+        }
+        if (blocked.length > 0) {
+            console.log(error(`Jailer blocked ${blocked.length} unsafe operations:`));
+            for (const b of blocked) {
+                console.log(c('dim', `  ✗ ${b.file}: ${b.reason}`));
+            }
+            plan.plan = plan.plan.filter(step => jailer.validateMove(step.source, step.destination).safe);
+            if (plan.plan.length === 0) {
+                console.log(error('No safe operations remain. Aborting.'));
+                return;
+            }
+            console.log(info(`Proceeding with ${plan.plan.length} safe operations.`));
+        }
+    }
+
+    const spinner = new Spinner(`Executing cure...`);
+    spinner.start();
+
+    try {
+        const engine = new ApplyEngine();
+        const result = await engine.apply(plan, (p) => {
+            spinner.update(`Relocating: ${p.index}/${p.total} — ${path.basename(p.current || '')}`);
+        });
+        spinner.succeed(`Cure applied! ${result.stats.success} files moved.`);
+        fs.unlinkSync(cachePath); // Clear plan
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdDuplicates(target, flags) {
+    const targetPath = path.resolve(target || '.');
+    const spinner = new Spinner(`Hunting duplicates in ${c('cyan', targetPath)}...`);
+    spinner.start();
+
+    try {
+        const engine = new DedupeEngine();
+        const result = engine.find(targetPath);
+        spinner.stop();
+        console.log(reporter.formatDedupeReport(result));
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdDedupe(target, flags) {
+    const targetPath = path.resolve(target || '.');
+    const spinner = new Spinner(`Deduplicating ${c('cyan', targetPath)}...`);
+    spinner.start();
+
+    try {
+        const engine = new DedupeEngine();
+        const report = engine.find(targetPath);
+        if (report.sets === 0) {
+            spinner.succeed('Total order restored: No duplicates found.');
+            return;
+        }
+
+        const result = await engine.clean(report);
+        spinner.succeed(`Purged ${result.deleted} duplicates. Reclaimed ${result.freedHuman}.`);
+    } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+
+async function cmdInfo(config) {
+    console.log(banner());
+    console.log(`  ${c('bold', 'Version')}    ${VERSION}`);
+    console.log(`  ${c('bold', 'Node')}       ${process.version}`);
+    console.log(`  ${c('bold', 'Platform')}   ${os.platform()} ${os.arch()}`);
+    console.log(`  ${c('bold', 'OS')}         ${os.type()} ${os.release()}`);
+    console.log(`  ${c('bold', 'Home')}       ${os.homedir()}`);
+    console.log(`  ${c('bold', 'CWD')}        ${process.cwd()}`);
+
+    // Config info
+    console.log(`  ${c('bold', 'Config')}     ${config._source || 'defaults'}`);
+
+    // Categories
+    const cats = getCategories();
+    const catCount = Object.keys(cats).length;
+    const extCount = Object.values(cats).reduce((sum, cat) => sum + cat.extensions.length, 0);
+    console.log(`  ${c('bold', 'Categories')} ${catCount} categories, ${extCount} extensions`);
+
+    // Permissions
+    const perms = checkPermissions(process.cwd());
+    const permStr = `${perms.read ? c('green', 'R') : c('red', '-')}${perms.write ? c('green', 'W') : c('red', '-')}${perms.execute ? c('green', 'X') : c('red', '-')}`;
+    console.log(`  ${c('bold', 'Permissions')} ${permStr} (current directory)`);
+
+    // Telemetry disclosure
+    const telemetryOff = process.env.FILEMAYOR_NO_TELEMETRY === '1';
+    console.log(`  ${c('bold', 'Telemetry')}  ${telemetryOff ? c('dim', 'off (FILEMAYOR_NO_TELEMETRY=1)') : c('dim', 'on — anonymous version+OS+command ping once per version. Set FILEMAYOR_NO_TELEMETRY=1 to disable.')}`);
+
+    console.log('');
+}
+
+// ─── License Command ──────────────────────────────────────────────
+
+async function cmdLicense(action, positional, flags) {
+    const subAction = action || 'status';
+
+    switch (subAction) {
+        case 'activate': {
+            const key = positional[0] || flags.key;
+            if (!key) {
+                console.error(error('Usage: filemayor license activate <key>'));
+                console.log(c('dim', '  Example: filemayor license activate FM-PRO-XXXX-XXXX-XXXXX'));
+                process.exit(1);
+            }
+            const result = activateLicense(key);
+            if (result.success) {
+                console.log(success(result.message));
+                console.log(c('dim', `  Tier: ${result.tier}`));
+            } else {
+                console.error(error(result.message));
+                process.exit(1);
+            }
+            break;
+        }
+
+        case 'deactivate':
+        case 'remove': {
+            const result = deactivateLicense();
+            if (result.success) {
+                console.log(success(result.message));
+            } else {
+                console.log(info(result.message));
+            }
+            break;
+        }
+
+        case 'status':
+        default: {
+            const li = getLicenseInfo();
+            console.log(banner());
+            console.log(c('bold', '  License Status'));
+            console.log(c('dim', `  ${'─'.repeat(40)}`));
+            console.log(`  ${c('bold', 'Tier:')}        ${li.active ? c('green', li.name) : c('yellow', 'Free')}`);
+            console.log(`  ${c('bold', 'Status:')}      ${li.active ? c('green', '● Active') : c('dim', '○ No license')}`);
+            if (li.key) {
+                const masked = li.key.substring(0, 7) + '****' + li.key.substring(li.key.length - 5);
+                console.log(`  ${c('bold', 'Key:')}         ${c('dim', masked)}`);
+            }
+            if (li.activatedAt) {
+                console.log(`  ${c('bold', 'Activated:')}   ${c('dim', new Date(li.activatedAt).toLocaleDateString())}`);
+            }
+            console.log('');
+            console.log(c('bold', '  Features'));
+            console.log(c('dim', `  ${'─'.repeat(40)}`));
+            const allFeatures = [
+                { id: 'scan', label: 'Directory Scanning', free: true },
+                { id: 'organize', label: 'File Organization', free: true },
+                { id: 'clean', label: 'Junk Cleanup', free: true },
+                { id: 'undo', label: 'Undo Operations', free: true },
+                { id: 'watch', label: 'Watch Mode', free: true },
+                { id: 'sop-ai', label: 'AI SOP Parsing', free: true },
+                { id: 'bulk-organize', label: 'Bulk Organize', free: true },
+                { id: 'csv-export', label: 'CSV Export', free: true },
+            ];
+            for (const feat of allFeatures) {
+                const has = li.features.includes('*') || li.features.includes(feat.id);
+                const icon = has ? c('green', '✓') : c('dim', '○');
+                const label = has ? feat.label : c('dim', feat.label);
+                const tag = !feat.free && !has ? c('magenta', ' [PRO]') : '';
+                console.log(`  ${icon}  ${label}${tag}`);
+            }
+            console.log('');
+            if (!li.active) {
+                console.log(c('dim', '  All features are free. License keys are optional: https://filemayor.com'));
+                console.log(c('dim', '  Activate: filemayor license activate <key>'));
+                console.log('');
+            }
+            break;
+        }
+    }
+}
+
+// ─── Main Entry Point ─────────────────────────────────────────────
+
+async function main() {
+    const args = parseArgs(process.argv);
+
+    // Version
+    if (args.flags.version) {
+        console.log(VERSION);
+        return;
+    }
+
+    // Colors
+    if (args.flags.noColor || process.env.NO_COLOR) {
+        reporter.setColors(false);
+    }
+
+    // Load config
+    let config;
+    try {
+        const configResult = loadConfig({
+            configPath: args.flags.config || null,
+            cliOverrides: {},
+        });
+        config = configResult.config;
+        config._source = configResult.source;
+
+        // Show validation warnings
+        if (configResult.validation.warnings.length > 0 && args.flags.verbose) {
+            for (const w of configResult.validation.warnings) {
+                console.error(warn(`Config: ${w}`));
+            }
+        }
+        if (!configResult.validation.valid) {
+            for (const e of configResult.validation.errors) {
+                console.error(error(`Config: ${e}`));
+            }
+        }
+    } catch (err) {
+        console.error(error(`Config error: ${err.message}`));
+        process.exit(1);
+    }
+
+    // No command — show help
+    if (!args.command || args.flags.help) {
+        printHelp();
+        return;
+    }
+
+    // Anonymous first-run ping (fire-and-forget, opt-out with FILEMAYOR_NO_TELEMETRY=1)
+    telemetryPing(VERSION, args.command);
+
+    // Route commands
+    switch (args.command) {
+        case 'scan':
+        case 's':
+            await cmdScan(args.target, args.flags, config);
+            break;
+
+        case 'explain':
+        case 'dx':
+            await cmdExplain(args.target, args.flags);
+            break;
+
+        case 'cure':
+        case 'plan':
+            await cmdCure(args.target, args.flags);
+            break;
+
+        case 'apply':
+        case 'exec':
+            await cmdApply(args.flags);
+            break;
+
+        case 'duplicates':
+        case 'dupes':
+            await cmdDuplicates(args.target, args.flags);
+            break;
+
+        case 'dedupe':
+            await cmdDedupe(args.target, args.flags);
+            break;
+
+        case 'analyze':
+        case 'a':
+            await cmdAnalyze(args.target, args.flags, config);
+            break;
+
+        case 'organize':
+        case 'org':
+        case 'o':
+            await cmdOrganize(args.target, args.flags, config);
+            break;
+
+        case 'clean':
+        case 'cl':
+        case 'c':
+            await cmdClean(args.target, args.flags, config);
+            break;
+
+        case 'watch':
+        case 'w':
+            await cmdWatch(args.target, args.flags, config);
+            break;
+
+        case 'init':
+        case 'i':
+            await cmdInit(args.flags);
+            break;
+
+        case 'undo':
+        case 'u':
+            await cmdUndo(args.target, args.flags);
+            break;
+
+        case 'info':
+            await cmdInfo(config);
+            break;
+
+        case 'license':
+        case 'lic':
+        case 'l':
+            await cmdLicense(args.target, args.positional, args.flags);
+            break;
+
+        case 'help':
+            printHelp();
+            break;
+
+        case 'mcp':
+            // Start the MCP server (STDIO transport)
+            require('./mcp-server').startServer();
+            return; // Keep process alive — server runs until stdin closes
+
+        default:
+            console.error(error(`Unknown command: "${args.command}"`));
+            console.log(c('dim', 'Run "filemayor --help" for usage'));
+            process.exit(1);
+    }
+}
+
+// ─── Run ──────────────────────────────────────────────────────────
+
+main().catch(err => {
+    console.error(error(err.message));
+    if (process.env.DEBUG) {
+        console.error(err.stack);
+    }
+    process.exit(1);
+});