@runhalo/cli 0.1.0 → 0.4.0

package/dist/index.js

@@ -37,19 +37,47 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RULES_CACHE_PATH = exports.MAX_HISTORY_ENTRIES = exports.HALO_HISTORY_PATH = exports.HALO_CONFIG_PATH = exports.HALO_CONFIG_DIR = exports.FREE_SCAN_LIMIT = void 0;
 exports.scan = scan;
+exports.fix = fix;
+exports.init = init;
 exports.scanFile = scanFile;
 exports.scanDirectory = scanDirectory;
 exports.createEngine = createEngine;
 exports.formatSARIF = formatSARIF;
 exports.formatJSON = formatJSON;
 exports.formatText = formatText;
+exports.loadConfig = loadConfig;
+exports.saveConfig = saveConfig;
+exports.firstRunPrompt = firstRunPrompt;
+exports.loadHistory = loadHistory;
+exports.saveHistory = saveHistory;
+exports.formatTrend = formatTrend;
+exports.generateHtmlReport = generateHtmlReport;
+exports.generatePdfReport = generatePdfReport;
+exports.escapeHtml = escapeHtml;
+exports.validateLicenseKey = validateLicenseKey;
+exports.activateLicense = activateLicense;
+exports.checkScanLimit = checkScanLimit;
+exports.checkProFeature = checkProFeature;
+exports.resolvePacks = resolvePacks;
+exports.resolveRules = resolveRules;
+exports.fetchRulesFromAPI = fetchRulesFromAPI;
+exports.readRulesCache = readRulesCache;
+exports.writeRulesCache = writeRulesCache;
+exports.loadBaselineRules = loadBaselineRules;
 const commander_1 = require("commander");
 const glob_1 = require("glob");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const readline = __importStar(require("readline"));
 const engine_1 = require("@runhalo/engine");
+const pdfkit_1 = __importDefault(require("pdfkit"));
 // CLI configuration
 const program = new commander_1.Command();
 /**
@@ -75,7 +103,12 @@ function getDefaultPatterns() {
         '**/*.h',
         '**/*.hpp',
         '**/*.cs',
-        '**/*.qml'
+        '**/*.qml',
+        // Added P3-0: Go, Ruby, XML for multi-language coverage
+        '**/*.go',
+        '**/*.rb',
+        '**/*.xml',
+        '**/*.erb'
     ];
 }
 /**
@@ -175,7 +208,7 @@ function formatSARIF(results, rules) {
 /**
  * Format violations as JSON output
  */
-function formatJSON(results) {
+function formatJSON(results, scoreResult) {
     const output = {
         version: '1.0.0',
         scannedAt: new Date().toISOString(),
@@ -183,6 +216,15 @@ function formatJSON(results) {
         totalViolations: results.reduce((sum, r) => sum + r.violations.length, 0),
         results: results
     };
+    if (scoreResult) {
+        output.complianceScore = {
+            score: scoreResult.score,
+            grade: scoreResult.grade,
+            pointsDeducted: scoreResult.pointsDeducted,
+            bySeverity: scoreResult.bySeverity,
+            rulesTriggered: scoreResult.rulesTriggered,
+        };
+    }
     return JSON.stringify(output, null, 2);
 }
 // ANSI color codes for terminal output
@@ -199,6 +241,7 @@ const colors = {
     bgYellow: '\x1b[43m',
     bgBlue: '\x1b[44m',
     magenta: '\x1b[35m',
+    green: '\x1b[32m',
 };
 // Detect if color should be used (respect NO_COLOR env and pipe detection)
 const useColor = !process.env.NO_COLOR && process.stdout.isTTY !== false;
@@ -208,7 +251,7 @@ function c(color, text) {
 /**
  * Format violations as human-readable text
  */
-function formatText(results, verbose = false, fileCount = 0) {
+function formatText(results, verbose = false, fileCount = 0, scoreResult) {
     let output = '';
     let totalViolations = 0;
     let criticalCount = 0;
@@ -270,7 +313,12 @@ function formatText(results, verbose = false, fileCount = 0) {
     }
     if (totalViolations === 0) {
         const scannedMsg = fileCount > 0 ? ` (${fileCount} files scanned)` : '';
-        return `${c(colors.bold, '✅ No COPPA issues detected!')}${scannedMsg}\n`;
+        let cleanOutput = `${c(colors.bold, '✅ No COPPA issues detected!')}${scannedMsg}\n`;
+        // Show perfect score for clean repos
+        if (scoreResult) {
+            cleanOutput += `\n${formatScoreLine(scoreResult)}\n`;
+        }
+        return cleanOutput;
     }
     // Summary header
     let header = `\n${c(colors.bold, `⚠  Found ${totalViolations} issue(s)`)}`;
@@ -290,8 +338,664 @@ function formatText(results, verbose = false, fileCount = 0) {
     if (lowCount > 0)
         parts.push(c(colors.dim, `${lowCount} low`));
     header += `   ${parts.join(c(colors.dim, ' · '))}\n`;
+    // Compliance score line
+    if (scoreResult) {
+        header += `\n${formatScoreLine(scoreResult)}\n`;
+    }
     return header + output;
 }
+/**
+ * Format the compliance score line with grade coloring
+ */
+function formatScoreLine(scoreResult) {
+    const { score, grade } = scoreResult;
+    // Color the grade based on value
+    let gradeColor;
+    switch (grade) {
+        case 'A':
+            gradeColor = '\x1b[32m'; // green
+            break;
+        case 'B':
+            gradeColor = '\x1b[36m'; // cyan
+            break;
+        case 'C':
+            gradeColor = '\x1b[33m'; // yellow
+            break;
+        case 'D':
+            gradeColor = '\x1b[33m'; // yellow
+            break;
+        default:
+            gradeColor = '\x1b[31m'; // red for F
+    }
+    const gradeStr = c(gradeColor + colors.bold, grade);
+    const scoreStr = c(colors.bold, `${score}/100`);
+    return `${c(colors.bold, '📊 COPPA Compliance Score:')} ${scoreStr} (${gradeStr})`;
+}
+/**
+ * Format trend line comparing current score to last scan for the same project.
+ * Returns empty string if no prior history exists.
+ */
+function formatTrend(currentScore, projectPath) {
+    const history = loadHistory();
+    const projectHistory = history.filter(h => h.projectPath === projectPath);
+    if (projectHistory.length === 0)
+        return '';
+    const last = projectHistory[projectHistory.length - 1];
+    const diff = currentScore - last.score;
+    if (diff > 0) {
+        return `  ${c('\x1b[32m', `↑ ${last.score}% → ${currentScore}% (+${diff} since last scan)`)}`;
+    }
+    else if (diff < 0) {
+        return `  ${c(colors.red, `↓ ${last.score}% → ${currentScore}% (${diff} since last scan)`)}`;
+    }
+    else {
+        return `  ${c(colors.dim, `→ ${currentScore}% (no change since last scan)`)}`;
+    }
+}
+// ==================== HTML Report Generator ====================
+/**
+ * Generate a self-contained HTML compliance report.
+ * Light theme for email-ability. All CSS inline. No external dependencies.
+ */
+function generateHtmlReport(results, scoreResult, fileCount, projectPath, history) {
+    const scanDate = new Date().toLocaleDateString('en-US', {
+        weekday: 'long', year: 'numeric', month: 'long', day: 'numeric'
+    });
+    const scanTime = new Date().toLocaleTimeString('en-US', {
+        hour: '2-digit', minute: '2-digit'
+    });
+    const totalViolations = results.reduce((sum, r) => sum + r.violations.length, 0);
+    const allViolations = results.flatMap(r => r.violations);
+    // Grade color
+    const gradeColorMap = {
+        A: '#22c55e', B: '#3b82f6', C: '#eab308', D: '#f97316', F: '#ef4444'
+    };
+    const gradeColor = gradeColorMap[scoreResult.grade] || '#6b7280';
+    // Trend HTML
+    let trendHtml = '';
+    if (history && history.length > 0) {
+        const projectHistory = history.filter(h => h.projectPath === projectPath);
+        if (projectHistory.length > 0) {
+            const last = projectHistory[projectHistory.length - 1];
+            const diff = scoreResult.score - last.score;
+            if (diff > 0) {
+                trendHtml = `<div style="margin-top:8px;color:#22c55e;font-size:14px;">↑ ${last.score}% → ${scoreResult.score}% (+${diff} since last scan)</div>`;
+            }
+            else if (diff < 0) {
+                trendHtml = `<div style="margin-top:8px;color:#ef4444;font-size:14px;">↓ ${last.score}% → ${scoreResult.score}% (${diff} since last scan)</div>`;
+            }
+            else {
+                trendHtml = `<div style="margin-top:8px;color:#6b7280;font-size:14px;">→ ${scoreResult.score}% (no change since last scan)</div>`;
+            }
+        }
+    }
+    // Severity bar segments
+    const { critical = 0, high = 0, medium = 0, low = 0 } = scoreResult.bySeverity || {};
+    const severityTotal = critical + high + medium + low;
+    const severityBar = severityTotal > 0 ? `
+    <div style="display:flex;height:8px;border-radius:4px;overflow:hidden;margin:12px 0;">
+      ${critical > 0 ? `<div style="width:${(critical / severityTotal * 100).toFixed(1)}%;background:#ef4444;"></div>` : ''}
+      ${high > 0 ? `<div style="width:${(high / severityTotal * 100).toFixed(1)}%;background:#f97316;"></div>` : ''}
+      ${medium > 0 ? `<div style="width:${(medium / severityTotal * 100).toFixed(1)}%;background:#eab308;"></div>` : ''}
+      ${low > 0 ? `<div style="width:${(low / severityTotal * 100).toFixed(1)}%;background:#3b82f6;"></div>` : ''}
+    </div>` : '';
+    // Violations by file
+    const violationsHtml = results.map(result => {
+        if (result.violations.length === 0)
+            return '';
+        const relPath = path.relative(projectPath, result.filePath) || result.filePath;
+        const fileViolations = result.violations.map(v => {
+            const sevColors = {
+                critical: '#ef4444', high: '#f97316', medium: '#eab308', low: '#3b82f6'
+            };
+            const sevColor = sevColors[v.severity] || '#6b7280';
+            const sevBg = {
+                critical: '#fef2f2', high: '#fff7ed', medium: '#fefce8', low: '#eff6ff'
+            };
+            const bg = sevBg[v.severity] || '#f9fafb';
+            const snippet = v.codeSnippet
+                ? `<pre style="background:#f1f5f9;border:1px solid #e2e8f0;border-radius:4px;padding:8px;font-size:12px;overflow-x:auto;margin:4px 0 0 0;">${escapeHtml(v.codeSnippet)}</pre>`
+                : '';
+            return `
+        <div style="padding:12px;margin:8px 0;background:${bg};border-left:3px solid ${sevColor};border-radius:4px;">
+          <div style="display:flex;align-items:center;gap:8px;margin-bottom:4px;">
+            <span style="display:inline-block;padding:2px 8px;border-radius:12px;font-size:11px;font-weight:600;color:white;background:${sevColor};text-transform:uppercase;">${v.severity}</span>
+            <code style="font-size:12px;color:#6366f1;">${v.ruleId}</code>
+            <span style="font-size:12px;color:#6b7280;">Line ${v.line}</span>
+          </div>
+          <div style="font-size:13px;color:#1e293b;margin-bottom:4px;">${escapeHtml(v.message)}</div>
+          ${snippet}
+          ${v.fixSuggestion ? `<div style="font-size:12px;color:#059669;margin-top:6px;">💡 ${escapeHtml(v.fixSuggestion)}</div>` : ''}
+          ${v.penalty ? `<div style="font-size:11px;color:#dc2626;margin-top:4px;">⚠ Penalty: ${escapeHtml(v.penalty)}</div>` : ''}
+        </div>`;
+        }).join('');
+        return `
+      <details style="margin:8px 0;border:1px solid #e2e8f0;border-radius:8px;overflow:hidden;">
+        <summary style="padding:12px 16px;background:#f8fafc;cursor:pointer;font-weight:500;font-size:14px;display:flex;justify-content:space-between;align-items:center;">
+          <span style="font-family:monospace;color:#1e293b;">${escapeHtml(relPath)}</span>
+          <span style="background:#fee2e2;color:#dc2626;padding:2px 8px;border-radius:12px;font-size:12px;font-weight:600;">${result.violations.length} issue${result.violations.length !== 1 ? 's' : ''}</span>
+        </summary>
+        <div style="padding:8px 16px 16px 16px;">
+          ${fileViolations}
+        </div>
+      </details>`;
+    }).filter(Boolean).join('');
+    // Auto-fixable section
+    const autoFixable = allViolations.filter(v => ['coppa-sec-006', 'coppa-sec-010', 'coppa-sec-015', 'coppa-default-020'].includes(v.ruleId));
+    const autoFixHtml = autoFixable.length > 0 ? `
+    <div style="margin:24px 0;padding:16px;background:#f0fdf4;border:1px solid #bbf7d0;border-radius:8px;">
+      <h3 style="margin:0 0 8px 0;color:#166534;font-size:16px;">🔧 Auto-Fixable Issues (${autoFixable.length})</h3>
+      <p style="margin:0 0 12px 0;color:#15803d;font-size:13px;">These violations can be automatically fixed. Run:</p>
+      <code style="display:block;background:#166534;color:#bbf7d0;padding:10px 14px;border-radius:6px;font-size:13px;">npx runhalo fix .</code>
+    </div>` : '';
+    // Recommendations
+    const recommendations = [];
+    if (critical > 0)
+        recommendations.push(`<li style="color:#dc2626;"><strong>Fix ${critical} critical issue${critical !== 1 ? 's' : ''} immediately</strong> — these represent the highest compliance risk and largest potential penalties.</li>`);
+    if (high > 0)
+        recommendations.push(`<li style="color:#ea580c;"><strong>Address ${high} high-severity issue${high !== 1 ? 's' : ''}</strong> — these are significant compliance gaps that should be resolved before release.</li>`);
+    if (autoFixable.length > 0)
+        recommendations.push(`<li style="color:#059669;"><strong>Run <code>npx runhalo fix .</code></strong> to automatically resolve ${autoFixable.length} issue${autoFixable.length !== 1 ? 's' : ''} (HTTP→HTTPS, default privacy settings, input sanitization).</li>`);
+    if (medium > 0)
+        recommendations.push(`<li style="color:#ca8a04;">Review ${medium} medium-severity issue${medium !== 1 ? 's' : ''} — these may require design changes or policy updates.</li>`);
+    if (totalViolations === 0)
+        recommendations.push(`<li style="color:#22c55e;"><strong>No issues detected!</strong> Your codebase passes all current COPPA compliance checks.</li>`);
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Halo COPPA Compliance Report — ${scanDate}</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; color: #1e293b; background: #ffffff; line-height: 1.6; }
+    .container { max-width: 800px; margin: 0 auto; padding: 32px 24px; }
+    h1 { font-size: 24px; font-weight: 700; margin-bottom: 4px; }
+    h2 { font-size: 18px; font-weight: 600; margin: 32px 0 16px 0; color: #0f172a; border-bottom: 2px solid #e2e8f0; padding-bottom: 8px; }
+    .header { border-bottom: 3px solid #6366f1; padding-bottom: 24px; margin-bottom: 32px; }
+    .score-section { display: flex; align-items: center; gap: 32px; margin: 24px 0; }
+    .score-circle { width: 120px; height: 120px; border-radius: 50%; display: flex; align-items: center; justify-content: center; flex-shrink: 0; }
+    .score-inner { width: 96px; height: 96px; border-radius: 50%; background: white; display: flex; flex-direction: column; align-items: center; justify-content: center; }
+    .score-value { font-size: 28px; font-weight: 700; }
+    .score-label { font-size: 11px; color: #6b7280; text-transform: uppercase; letter-spacing: 0.05em; }
+    .grade-badge { display: inline-block; font-size: 36px; font-weight: 800; padding: 4px 16px; border-radius: 8px; }
+    .severity-table { width: 100%; border-collapse: collapse; margin: 12px 0; }
+    .severity-table td, .severity-table th { padding: 8px 12px; text-align: left; border-bottom: 1px solid #f1f5f9; font-size: 13px; }
+    .severity-table th { color: #6b7280; font-weight: 500; font-size: 12px; text-transform: uppercase; letter-spacing: 0.05em; }
+    .severity-dot { display: inline-block; width: 10px; height: 10px; border-radius: 50%; margin-right: 6px; }
+    .recommendations { margin: 16px 0; }
+    .recommendations li { margin: 8px 0; font-size: 14px; line-height: 1.5; }
+    .footer { margin-top: 48px; padding-top: 24px; border-top: 1px solid #e2e8f0; color: #94a3b8; font-size: 12px; }
+    details summary::-webkit-details-marker { display: none; }
+    details summary::before { content: '▶ '; font-size: 10px; color: #94a3b8; }
+    details[open] summary::before { content: '▼ '; }
+    @media (max-width: 600px) { .score-section { flex-direction: column; align-items: flex-start; } }
+    @media print { details { open: true; } details[open] summary { display: none; } }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="header">
+      <div style="display:flex;align-items:center;gap:12px;margin-bottom:16px;">
+        <div style="width:32px;height:32px;border-radius:8px;background:linear-gradient(135deg,#6366f1,#a855f7);display:flex;align-items:center;justify-content:center;">
+          <span style="color:white;font-weight:700;font-size:14px;">H</span>
+        </div>
+        <h1>COPPA Compliance Report</h1>
+      </div>
+      <div style="font-size:13px;color:#6b7280;">
+        <span>${scanDate} at ${scanTime}</span>
+        <span style="margin:0 8px;">·</span>
+        <span>${fileCount} files scanned</span>
+        <span style="margin:0 8px;">·</span>
+        <span style="font-family:monospace;">${escapeHtml(projectPath)}</span>
+      </div>
+    </div>
+
+    <div class="score-section">
+      <div class="score-circle" style="background:conic-gradient(${gradeColor} ${scoreResult.score * 3.6}deg, #e2e8f0 0);">
+        <div class="score-inner">
+          <div class="score-value">${scoreResult.score}</div>
+          <div class="score-label">out of 100</div>
+        </div>
+      </div>
+      <div>
+        <div class="grade-badge" style="color:${gradeColor};background:${gradeColor}15;">Grade ${scoreResult.grade}</div>
+        <div style="margin-top:8px;font-size:14px;color:#475569;">${totalViolations} violation${totalViolations !== 1 ? 's' : ''} found across ${results.filter(r => r.violations.length > 0).length} file${results.filter(r => r.violations.length > 0).length !== 1 ? 's' : ''}</div>
+        ${trendHtml}
+      </div>
+    </div>
+
+    <h2>Severity Breakdown</h2>
+    ${severityBar}
+    <table class="severity-table">
+      <tr><th>Severity</th><th>Count</th><th>Points Deducted</th></tr>
+      <tr><td><span class="severity-dot" style="background:#ef4444;"></span>Critical</td><td><strong>${critical}</strong></td><td>${critical > 0 ? '-' + (critical * 10) : '—'}</td></tr>
+      <tr><td><span class="severity-dot" style="background:#f97316;"></span>High</td><td><strong>${high}</strong></td><td>${high > 0 ? '-' + (high * 5) : '—'}</td></tr>
+      <tr><td><span class="severity-dot" style="background:#eab308;"></span>Medium</td><td><strong>${medium}</strong></td><td>${medium > 0 ? '-' + (medium * 2) : '—'}</td></tr>
+      <tr><td><span class="severity-dot" style="background:#3b82f6;"></span>Low</td><td><strong>${low}</strong></td><td>${low > 0 ? '-' + low : '—'}</td></tr>
+    </table>
+
+    ${autoFixHtml}
+
+    ${totalViolations > 0 ? `<h2>Violations by File</h2>${violationsHtml}` : ''}
+
+    ${recommendations.length > 0 ? `
+    <h2>Recommendations</h2>
+    <ol class="recommendations">
+      ${recommendations.join('\n      ')}
+    </ol>` : ''}
+
+    <div class="footer">
+      <p><strong>Disclaimer:</strong> Halo is a developer tool designed to assist with code analysis and identifying potential privacy issues. It is not legal advice and does not guarantee compliance with COPPA, GDPR, or any other regulation. Always consult with qualified legal counsel regarding your specific compliance obligations.</p>
+      <p style="margin-top:8px;">Generated by <strong>Halo</strong> v${CLI_VERSION} · <a href="https://runhalo.dev" style="color:#6366f1;">runhalo.dev</a></p>
+    </div>
+  </div>
+</body>
+</html>`;
+}
+/**
+ * Escape HTML special characters
+ */
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+// ==================== PDF Report Generator (P3-2) ====================
+// PDF color constants
+const PDF_COLORS = {
+    primary: '#6366f1', // Halo accent (indigo)
+    purple: '#a855f7',
+    green: '#22c55e',
+    cyan: '#3b82f6',
+    yellow: '#eab308',
+    orange: '#f97316',
+    red: '#ef4444',
+    darkText: '#0f172a',
+    bodyText: '#1e293b',
+    mutedText: '#64748b',
+    lightText: '#94a3b8',
+    border: '#e2e8f0',
+    lightBg: '#f8fafc',
+    white: '#ffffff',
+};
+function gradeColor(grade) {
+    switch (grade) {
+        case 'A': return PDF_COLORS.green;
+        case 'B': return PDF_COLORS.cyan;
+        case 'C': return PDF_COLORS.yellow;
+        case 'D': return PDF_COLORS.orange;
+        default: return PDF_COLORS.red;
+    }
+}
+function severityColor(severity) {
+    switch (severity) {
+        case 'critical': return PDF_COLORS.red;
+        case 'high': return PDF_COLORS.orange;
+        case 'medium': return PDF_COLORS.yellow;
+        default: return PDF_COLORS.cyan;
+    }
+}
+/**
+ * Generate a government-procurement-grade PDF compliance report.
+ * Uses PDFKit — pure JS, no browser dependencies, CI-safe.
+ */
+function generatePdfReport(results, scoreResult, fileCount, projectPath, history) {
+    return new Promise((resolve, reject) => {
+        const doc = new pdfkit_1.default({
+            size: 'LETTER',
+            margins: { top: 60, bottom: 60, left: 60, right: 60 },
+            info: {
+                Title: 'COPPA 2.0 Compliance Report',
+                Author: 'Halo by Mindful Media',
+                Subject: `Compliance scan of ${projectPath}`,
+                Creator: `Halo v${CLI_VERSION}`,
+            },
+        });
+        const chunks = [];
+        doc.on('data', (chunk) => chunks.push(chunk));
+        doc.on('end', () => resolve(Buffer.concat(chunks)));
+        doc.on('error', reject);
+        const pageWidth = doc.page.width - 120; // 60px margins each side
+        const scanDate = new Date().toLocaleDateString('en-US', {
+            weekday: 'long', year: 'numeric', month: 'long', day: 'numeric'
+        });
+        const scanTime = new Date().toLocaleTimeString('en-US', {
+            hour: '2-digit', minute: '2-digit'
+        });
+        const totalViolations = results.reduce((sum, r) => sum + r.violations.length, 0);
+        const allViolations = results.flatMap(r => r.violations);
+        const { critical = 0, high = 0, medium = 0, low = 0 } = scoreResult.bySeverity || {};
+        // ═══════════════ HELPER: Page footer ═══════════════
+        let pageNum = 0;
+        function addFooter() {
+            pageNum++;
+            const y = doc.page.height - 40;
+            doc.save();
+            doc.fontSize(7).fillColor(PDF_COLORS.lightText);
+            doc.text(`Generated by Halo v${CLI_VERSION} — runhalo.dev`, 60, y, { width: pageWidth / 2, align: 'left' });
+            doc.text(`Page ${pageNum}`, 60, y, { width: pageWidth, align: 'right' });
+            doc.restore();
+        }
+        // ═══════════════ COVER PAGE ═══════════════
+        doc.save();
+        // Logo block
+        const logoX = 60;
+        const logoY = 100;
+        doc.roundedRect(logoX, logoY, 48, 48, 10).fill(PDF_COLORS.primary);
+        doc.fontSize(24).fillColor(PDF_COLORS.white).text('H', logoX + 14, logoY + 10, { width: 48 });
+        // Title
+        doc.fontSize(32).fillColor(PDF_COLORS.darkText).text('COPPA 2.0', 60, 180, { width: pageWidth });
+        doc.fontSize(32).fillColor(PDF_COLORS.darkText).text('Compliance Report', 60, 220, { width: pageWidth });
+        // Divider
+        doc.moveTo(60, 270).lineTo(60 + pageWidth, 270).lineWidth(2).strokeColor(PDF_COLORS.primary).stroke();
+        // Metadata
+        doc.fontSize(11).fillColor(PDF_COLORS.mutedText);
+        doc.text(`Project:  ${projectPath}`, 60, 290);
+        doc.text(`Date:     ${scanDate} at ${scanTime}`, 60, 308);
+        doc.text(`Files:    ${fileCount} files scanned`, 60, 326);
+        doc.text(`Scanner:  Halo v${CLI_VERSION}`, 60, 344);
+        // Score display (centered, large)
+        const scoreY = 420;
+        const scoreCenterX = 60 + pageWidth / 2;
+        // Score circle background
+        doc.circle(scoreCenterX, scoreY, 60).lineWidth(8).strokeColor(PDF_COLORS.border).stroke();
+        // Score arc (proportional to score)
+        if (scoreResult.score > 0) {
+            const startAngle = -Math.PI / 2;
+            const endAngle = startAngle + (scoreResult.score / 100) * 2 * Math.PI;
+            // Draw score arc
+            doc.save();
+            doc.circle(scoreCenterX, scoreY, 60).lineWidth(8).strokeColor(gradeColor(scoreResult.grade)).stroke();
+            doc.restore();
+        }
+        // Score number
+        doc.fontSize(36).fillColor(PDF_COLORS.darkText);
+        const scoreText = `${scoreResult.score}`;
+        doc.text(scoreText, scoreCenterX - 30, scoreY - 20, { width: 60, align: 'center' });
+        doc.fontSize(10).fillColor(PDF_COLORS.mutedText);
+        doc.text('out of 100', scoreCenterX - 30, scoreY + 20, { width: 60, align: 'center' });
+        // Grade badge
+        doc.fontSize(48).fillColor(gradeColor(scoreResult.grade));
+        doc.text(`Grade ${scoreResult.grade}`, 60, scoreY + 80, { width: pageWidth, align: 'center' });
+        // Summary line
+        doc.fontSize(12).fillColor(PDF_COLORS.bodyText);
+        doc.text(`${totalViolations} violation${totalViolations !== 1 ? 's' : ''} found across ${results.filter(r => r.violations.length > 0).length} file${results.filter(r => r.violations.length > 0).length !== 1 ? 's' : ''}`, 60, scoreY + 140, { width: pageWidth, align: 'center' });
+        // Confidentiality notice
+        doc.fontSize(8).fillColor(PDF_COLORS.lightText);
+        doc.text('CONFIDENTIAL — FOR INTERNAL COMPLIANCE USE ONLY', 60, doc.page.height - 80, { width: pageWidth, align: 'center' });
+        addFooter();
+        doc.restore();
+        // ═══════════════ EXECUTIVE SUMMARY ═══════════════
+        doc.addPage();
+        doc.fontSize(20).fillColor(PDF_COLORS.darkText).text('Executive Summary', 60, 60);
+        doc.moveTo(60, 88).lineTo(60 + pageWidth, 88).lineWidth(1).strokeColor(PDF_COLORS.border).stroke();
+        let y = 100;
+        // Score + grade inline
+        doc.fontSize(14).fillColor(PDF_COLORS.bodyText);
+        doc.text(`Compliance Score: ${scoreResult.score}/100 (Grade ${scoreResult.grade})`, 60, y);
+        y += 30;
+        // Trend (if available)
+        if (history && history.length > 0) {
+            const projectHistory = history.filter((h) => h.projectPath === projectPath);
+            if (projectHistory.length > 0) {
+                const last = projectHistory[projectHistory.length - 1];
+                const diff = scoreResult.score - last.score;
+                const arrow = diff > 0 ? '↑' : diff < 0 ? '↓' : '→';
+                const trendColor = diff > 0 ? PDF_COLORS.green : diff < 0 ? PDF_COLORS.red : PDF_COLORS.mutedText;
+                doc.fontSize(11).fillColor(trendColor);
+                doc.text(`${arrow} ${last.score}% → ${scoreResult.score}% (${diff > 0 ? '+' : ''}${diff} since last scan)`, 60, y);
+                y += 25;
+            }
+        }
+        // Severity breakdown table
+        y += 10;
+        doc.fontSize(14).fillColor(PDF_COLORS.darkText).text('Severity Breakdown', 60, y);
+        y += 25;
+        // Table header
+        const col1 = 60, col2 = 220, col3 = 320, col4 = 420;
+        doc.fontSize(9).fillColor(PDF_COLORS.mutedText);
+        doc.text('SEVERITY', col1, y);
+        doc.text('COUNT', col2, y);
+        doc.text('POINTS DEDUCTED', col3, y);
+        doc.text('% OF TOTAL', col4, y);
+        y += 18;
+        doc.moveTo(60, y).lineTo(60 + pageWidth, y).lineWidth(0.5).strokeColor(PDF_COLORS.border).stroke();
+        y += 8;
+        const severities = [
+            { label: 'Critical', count: critical, points: critical * 10, color: PDF_COLORS.red },
+            { label: 'High', count: high, points: high * 5, color: PDF_COLORS.orange },
+            { label: 'Medium', count: medium, points: medium * 2, color: PDF_COLORS.yellow },
+            { label: 'Low', count: low, points: low * 1, color: PDF_COLORS.cyan },
+        ];
+        for (const sev of severities) {
+            // Colored dot
+            doc.circle(col1 + 5, y + 5, 4).fill(sev.color);
+            doc.fontSize(10).fillColor(PDF_COLORS.bodyText);
+            doc.text(sev.label, col1 + 16, y);
+            doc.text(`${sev.count}`, col2, y);
+            doc.text(sev.count > 0 ? `-${sev.points}` : '—', col3, y);
+            const pct = totalViolations > 0 ? ((sev.count / totalViolations) * 100).toFixed(0) : '0';
+            doc.text(`${pct}%`, col4, y);
+            y += 20;
+        }
+        // Total row
+        doc.moveTo(60, y).lineTo(60 + pageWidth, y).lineWidth(0.5).strokeColor(PDF_COLORS.border).stroke();
+        y += 8;
+        doc.fontSize(10).fillColor(PDF_COLORS.darkText);
+        doc.text('Total', col1 + 16, y, { bold: true });
+        doc.text(`${totalViolations}`, col2, y);
+        doc.text(`-${scoreResult.pointsDeducted}`, col3, y);
+        y += 30;
+        // Key findings
+        doc.fontSize(14).fillColor(PDF_COLORS.darkText).text('Key Findings', 60, y);
+        y += 25;
+        doc.fontSize(10).fillColor(PDF_COLORS.bodyText);
+        if (totalViolations === 0) {
+            doc.text('No COPPA compliance issues were detected in this codebase. All 20 rules passed.', 60, y, { width: pageWidth });
+        }
+        else {
+            if (critical > 0) {
+                doc.fillColor(PDF_COLORS.red);
+                doc.text(`• ${critical} critical issue${critical !== 1 ? 's' : ''} require immediate attention — these represent the highest compliance risk.`, 60, y, { width: pageWidth });
+                y += 18;
+            }
+            if (high > 0) {
+                doc.fillColor(PDF_COLORS.orange);
+                doc.text(`• ${high} high-severity issue${high !== 1 ? 's' : ''} should be resolved before production release.`, 60, y, { width: pageWidth });
+                y += 18;
+            }
+            // Auto-fixable count
+            const autoFixable = allViolations.filter(v => ['coppa-sec-006', 'coppa-sec-010', 'coppa-sec-015', 'coppa-default-020'].includes(v.ruleId));
+            if (autoFixable.length > 0) {
+                doc.fillColor(PDF_COLORS.green);
+                doc.text(`• ${autoFixable.length} issue${autoFixable.length !== 1 ? 's' : ''} can be auto-fixed by running: npx runhalo fix .`, 60, y, { width: pageWidth });
+                y += 18;
+            }
+            // Unique rules triggered
+            const uniqueRules = [...new Set(allViolations.map(v => v.ruleId))];
+            doc.fillColor(PDF_COLORS.bodyText);
+            doc.text(`• ${uniqueRules.length} unique COPPA rule${uniqueRules.length !== 1 ? 's' : ''} triggered across ${fileCount} scanned files.`, 60, y, { width: pageWidth });
+        }
+        addFooter();
+        // ═══════════════ DETAILED FINDINGS ═══════════════
+        if (totalViolations > 0) {
+            doc.addPage();
+            doc.fontSize(20).fillColor(PDF_COLORS.darkText).text('Detailed Findings', 60, 60);
+            doc.moveTo(60, 88).lineTo(60 + pageWidth, 88).lineWidth(1).strokeColor(PDF_COLORS.border).stroke();
+            y = 100;
+            // Group violations by severity
+            const bySeverity = {
+                critical: [], high: [], medium: [], low: []
+            };
+            for (const result of results) {
+                for (const v of result.violations) {
+                    const relPath = path.relative(projectPath, result.filePath) || result.filePath;
+                    bySeverity[v.severity]?.push({ file: relPath, violation: v });
+                }
+            }
+            // PDF Cap: Show max 25 violations to keep PDF under ~10 pages
+            // Priority: ALL critical/high first, then fill remaining slots with medium/low
+            const PDF_VIOLATION_CAP = 25;
+            let violationsShown = 0;
+            let violationsOmitted = 0;
+            const totalAllItems = Object.values(bySeverity).reduce((sum, items) => sum + items.length, 0);
+            for (const severity of ['critical', 'high', 'medium', 'low']) {
+                const items = bySeverity[severity];
+                if (!items || items.length === 0)
+                    continue;
+                // Determine how many of this severity to show
+                const remainingSlots = PDF_VIOLATION_CAP - violationsShown;
+                if (remainingSlots <= 0) {
+                    violationsOmitted += items.length;
+                    continue;
+                }
+                const itemsToShow = items.slice(0, remainingSlots);
+                const itemsSkipped = items.length - itemsToShow.length;
+                violationsOmitted += itemsSkipped;
+                // Check if we need a new page
+                if (y > doc.page.height - 150) {
+                    addFooter();
+                    doc.addPage();
+                    y = 60;
+                }
+                // Severity header
+                doc.fontSize(14).fillColor(severityColor(severity));
+                doc.text(`${severity.charAt(0).toUpperCase() + severity.slice(1)} (${items.length}${itemsSkipped > 0 ? `, showing ${itemsToShow.length}` : ''})`, 60, y);
+                y += 22;
+                for (const item of itemsToShow) {
+                    // Check page break
+                    if (y > doc.page.height - 120) {
+                        addFooter();
+                        doc.addPage();
+                        y = 60;
+                    }
+                    // Violation entry
+                    doc.fontSize(9).fillColor(severityColor(severity));
+                    doc.text(severity.toUpperCase(), 60, y);
+                    doc.fillColor(PDF_COLORS.primary);
+                    doc.text(item.violation.ruleId, 120, y);
+                    doc.fillColor(PDF_COLORS.mutedText);
+                    doc.text(`${item.file}:${item.violation.line}`, 260, y);
+                    y += 14;
+                    // Message
+                    doc.fontSize(9).fillColor(PDF_COLORS.bodyText);
+                    const msgHeight = doc.heightOfString(item.violation.message, { width: pageWidth - 20 });
+                    doc.text(item.violation.message, 70, y, { width: pageWidth - 20 });
+                    y += msgHeight + 4;
+                    // Code snippet (if available)
+                    if (item.violation.codeSnippet) {
+                        const snippet = item.violation.codeSnippet.length > 120
+                            ? item.violation.codeSnippet.substring(0, 117) + '...'
+                            : item.violation.codeSnippet;
+                        doc.rect(70, y, pageWidth - 20, 16).fill(PDF_COLORS.lightBg);
+                        doc.fontSize(7).fillColor(PDF_COLORS.mutedText);
+                        doc.text(snippet, 74, y + 4, { width: pageWidth - 28 });
+                        y += 22;
+                    }
+                    // Fix suggestion
+                    if (item.violation.fixSuggestion) {
+                        doc.fontSize(8).fillColor(PDF_COLORS.green);
+                        const fixText = `Fix: ${item.violation.fixSuggestion}`;
+                        const fixHeight = doc.heightOfString(fixText, { width: pageWidth - 20 });
+                        doc.text(fixText, 70, y, { width: pageWidth - 20 });
+                        y += fixHeight + 4;
+                    }
+                    // Penalty
+                    if (item.violation.penalty) {
+                        doc.fontSize(7).fillColor(PDF_COLORS.red);
+                        doc.text(`Penalty: ${item.violation.penalty}`, 70, y);
+                        y += 12;
+                    }
+                    y += 8; // spacing between violations
+                    violationsShown++;
+                }
+                y += 10; // spacing between severity groups
+            }
+            // Dashboard CTA for omitted violations
+            if (violationsOmitted > 0) {
+                if (y > doc.page.height - 120) {
+                    addFooter();
+                    doc.addPage();
+                    y = 60;
+                }
+                y += 10;
+                doc.rect(60, y, pageWidth, 60).fill('#f0f0ff');
+                doc.fontSize(11).fillColor(PDF_COLORS.primary);
+                doc.text(`${violationsOmitted} additional violation(s) not shown in this report.`, 70, y + 12, { width: pageWidth - 20 });
+                doc.fontSize(10).fillColor(PDF_COLORS.bodyText);
+                doc.text('View all violations on your Halo Dashboard: https://runhalo.dev/app/dashboard.html', 70, y + 30, { width: pageWidth - 20 });
+                y += 70;
+            }
+            addFooter();
+        }
+        // ═══════════════ RECOMMENDATIONS ═══════════════
+        doc.addPage();
+        doc.fontSize(20).fillColor(PDF_COLORS.darkText).text('Recommendations', 60, 60);
+        doc.moveTo(60, 88).lineTo(60 + pageWidth, 88).lineWidth(1).strokeColor(PDF_COLORS.border).stroke();
+        y = 100;
+        let recNum = 1;
+        doc.fontSize(10).fillColor(PDF_COLORS.bodyText);
+        if (totalViolations === 0) {
+            doc.text('No issues detected. This codebase passes all current COPPA 2.0 compliance checks.', 60, y, { width: pageWidth });
+            y += 20;
+            doc.text('Recommended next steps:', 60, y, { width: pageWidth });
+            y += 16;
+            doc.text(`${recNum++}. Schedule regular scans as part of your CI/CD pipeline.`, 70, y, { width: pageWidth - 20 });
+            y += 16;
+            doc.text(`${recNum++}. Enable ethical design rules with --ethical-preview for proactive compliance.`, 70, y, { width: pageWidth - 20 });
+            y += 16;
+            doc.text(`${recNum++}. Run "npx runhalo init --ide" to teach your AI coding assistants COPPA rules.`, 70, y, { width: pageWidth - 20 });
+        }
+        else {
+            if (critical > 0) {
+                doc.fillColor(PDF_COLORS.red);
+                doc.text(`${recNum++}. Fix ${critical} critical issue${critical !== 1 ? 's' : ''} immediately — these represent the highest compliance risk and largest potential penalties.`, 70, y, { width: pageWidth - 20 });
+                y += 22;
+            }
+            if (high > 0) {
+                doc.fillColor(PDF_COLORS.orange);
+                doc.text(`${recNum++}. Address ${high} high-severity issue${high !== 1 ? 's' : ''} before production release — these are significant compliance gaps.`, 70, y, { width: pageWidth - 20 });
+                y += 22;
+            }
+            const autoFixable = allViolations.filter(v => ['coppa-sec-006', 'coppa-sec-010', 'coppa-sec-015', 'coppa-default-020'].includes(v.ruleId));
+            if (autoFixable.length > 0) {
+                doc.fillColor(PDF_COLORS.green);
+                doc.text(`${recNum++}. Run "npx runhalo fix ." to automatically resolve ${autoFixable.length} issue${autoFixable.length !== 1 ? 's' : ''}.`, 70, y, { width: pageWidth - 20 });
+                y += 22;
+            }
+            if (medium > 0) {
+                doc.fillColor(PDF_COLORS.yellow);
+                doc.text(`${recNum++}. Review ${medium} medium-severity issue${medium !== 1 ? 's' : ''} — these may require design changes or policy updates.`, 70, y, { width: pageWidth - 20 });
+                y += 22;
+            }
+            doc.fillColor(PDF_COLORS.bodyText);
+            doc.text(`${recNum++}. Integrate Halo into your CI pipeline: uses: runhalo/action@v1 in GitHub Actions.`, 70, y, { width: pageWidth - 20 });
+            y += 22;
+            doc.text(`${recNum++}. Run "npx runhalo init --ide" to teach AI coding assistants COPPA compliance patterns.`, 70, y, { width: pageWidth - 20 });
+            y += 22;
+            doc.text(`${recNum++}. Schedule re-scan after remediations to track compliance improvement.`, 70, y, { width: pageWidth - 20 });
+        }
+        // COPPA 2.0 context
+        y += 30;
+        doc.fontSize(14).fillColor(PDF_COLORS.darkText).text('Regulatory Context', 60, y);
+        y += 22;
+        doc.fontSize(9).fillColor(PDF_COLORS.bodyText);
+        doc.text('The COPPA 2.0 Final Rule (published April 22, 2025) updates the Children\'s Online Privacy Protection Act with new requirements for data retention, biometric data, push notifications, and advertising. The 12-month compliance grace period ends April 22, 2026, after which enforcement begins with penalties up to $54,540 per violation per child per day.', 60, y, { width: pageWidth });
+        // Disclaimer
+        y = doc.page.height - 130;
+        doc.moveTo(60, y).lineTo(60 + pageWidth, y).lineWidth(0.5).strokeColor(PDF_COLORS.border).stroke();
+        y += 10;
+        doc.fontSize(7).fillColor(PDF_COLORS.lightText);
+        doc.text('DISCLAIMER: Halo is a developer tool designed to assist with code analysis and identifying potential privacy issues. It is not legal advice and does not guarantee compliance with COPPA, GDPR, or any other regulation. Always consult with qualified legal counsel regarding your specific compliance obligations. This report is generated automatically and should be reviewed by a qualified compliance professional.', 60, y, { width: pageWidth });
+        addFooter();
+        // Finalize
+        doc.end();
+    });
+}
 /**
  * Load .haloignore from a directory (walks up to find it)
  */
@@ -377,6 +1081,449 @@ async function scanDirectory(dirPath, config) {
     }
     return results;
 }
+// ==================== First-Run Email Prompt ====================
+const HALO_CONFIG_DIR = path.join(os.homedir(), '.halo');
+exports.HALO_CONFIG_DIR = HALO_CONFIG_DIR;
+const HALO_CONFIG_PATH = path.join(HALO_CONFIG_DIR, 'config.json');
+exports.HALO_CONFIG_PATH = HALO_CONFIG_PATH;
+const HALO_HISTORY_PATH = path.join(HALO_CONFIG_DIR, 'history.json');
+exports.HALO_HISTORY_PATH = HALO_HISTORY_PATH;
+const MAX_HISTORY_ENTRIES = 100;
+exports.MAX_HISTORY_ENTRIES = MAX_HISTORY_ENTRIES;
+const CLI_VERSION = '0.2.1';
+const SUPABASE_URL = 'https://wrfwcmyxxbafcdvxlmug.supabase.co';
+const SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6IndyZndjbXl4eGJhZmNkdnhsbXVnIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzIzNDc5MzIsImV4cCI6MjA4NzkyMzkzMn0.6Wj58QDuojPAY_ArVbZvjhcFVuX5VvzqjaEg0FkoYJI';
+// Rules Engine API
+const RULES_API_BASE = `${SUPABASE_URL}/functions/v1`;
+const RULES_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const RULES_CACHE_PATH = path.join(os.homedir(), '.halo', 'rules-cache.json');
+exports.RULES_CACHE_PATH = RULES_CACHE_PATH;
+const RULES_FETCH_TIMEOUT_MS = 5000; // 5 second timeout
+/**
+ * Fetch rules from the Supabase rules-fetch edge function.
+ * Returns raw JSON rules (not compiled) or null on failure.
+ */
+async function fetchRulesFromAPI(packs, verbose) {
+    try {
+        const url = `${RULES_API_BASE}/rules-fetch?packs=${packs.join(',')}`;
+        const cachedEtag = readRulesCache()?.etag;
+        const headers = {};
+        if (cachedEtag) {
+            headers['If-None-Match'] = cachedEtag;
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), RULES_FETCH_TIMEOUT_MS);
+        const res = await fetch(url, { headers, signal: controller.signal });
+        clearTimeout(timeout);
+        if (res.status === 304) {
+            if (verbose)
+                console.error('📡 Rules API: 304 Not Modified (cache hit)');
+            return null; // Caller should use cache
+        }
+        if (!res.ok) {
+            if (verbose)
+                console.error(`📡 Rules API: ${res.status} ${res.statusText}`);
+            return null;
+        }
+        const data = await res.json();
+        const etag = res.headers.get('etag');
+        if (verbose)
+            console.error(`📡 Rules API: fetched ${data.rules?.length || 0} rules`);
+        return { rules: data.rules || [], etag };
+    }
+    catch (err) {
+        if (verbose)
+            console.error(`📡 Rules API: fetch failed (${err.name === 'AbortError' ? 'timeout' : err.message})`);
+        return null;
+    }
+}
+/**
+ * Read the local rules cache.
+ */
+function readRulesCache() {
+    try {
+        if (fs.existsSync(RULES_CACHE_PATH)) {
+            const cache = JSON.parse(fs.readFileSync(RULES_CACHE_PATH, 'utf-8'));
+            return cache;
+        }
+    }
+    catch {
+        // Corrupt cache — ignore
+    }
+    return null;
+}
+/**
+ * Write rules to the local cache.
+ */
+function writeRulesCache(etag, packs, rules) {
+    try {
+        const cacheDir = path.dirname(RULES_CACHE_PATH);
+        if (!fs.existsSync(cacheDir)) {
+            fs.mkdirSync(cacheDir, { recursive: true });
+        }
+        const cache = {
+            etag,
+            packs,
+            rules,
+            fetchedAt: new Date().toISOString(),
+        };
+        fs.writeFileSync(RULES_CACHE_PATH, JSON.stringify(cache, null, 2), 'utf-8');
+    }
+    catch {
+        // Silent failure — never block scan
+    }
+}
+/**
+ * Load bundled baseline rules from @runhalo/engine's rules.json.
+ */
+function loadBaselineRules(packs) {
+    try {
+        const rulesJsonPath = require.resolve('@runhalo/engine/rules/rules.json');
+        const data = JSON.parse(fs.readFileSync(rulesJsonPath, 'utf-8'));
+        return (data.rules || []).filter((r) => r.packs.some(p => packs.includes(p)));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Map CLI options to pack IDs.
+ * --pack takes precedence. Legacy flags (--ethical-preview, --ai-audit, --sector-au-sbd) are mapped.
+ */
+function resolvePacks(options) {
+    // Explicit --pack flag takes priority
+    if (options.pack && options.pack.length > 0) {
+        return options.pack;
+    }
+    // Legacy boolean flags
+    const packs = ['coppa'];
+    if (options.ethicalPreview)
+        packs.push('ethical');
+    if (options.aiAudit)
+        packs.push('ai-audit');
+    if (options.sectorAuSbd)
+        packs.push('au-sbd');
+    return packs;
+}
+/**
+ * Resolve rules with fallback chain:
+ *   API (fresh) → 304 cache hit → local cache (stale OK) → bundled baseline → null
+ */
+async function resolveRules(packs, offline, verbose) {
+    // 1. Try API (unless offline)
+    if (!offline) {
+        const apiResult = await fetchRulesFromAPI(packs, verbose);
+        if (apiResult && apiResult.rules.length > 0) {
+            // Fresh rules from API — cache and use
+            writeRulesCache(apiResult.etag, packs, apiResult.rules);
+            return apiResult.rules;
+        }
+        // apiResult === null could mean 304 (use cache) or failure (also try cache)
+    }
+    // 2. Try local cache
+    const cache = readRulesCache();
+    if (cache && cache.rules.length > 0) {
+        const cacheAge = Date.now() - new Date(cache.fetchedAt).getTime();
+        const isFresh = cacheAge < RULES_CACHE_TTL_MS;
+        const packsMatch = packs.every(p => cache.packs.includes(p));
+        if (packsMatch) {
+            if (verbose) {
+                console.error(`📦 Using cached rules (${isFresh ? 'fresh' : 'stale'}, ${cache.rules.length} rules)`);
+            }
+            return cache.rules;
+        }
+    }
+    // 3. Try bundled baseline
+    const baseline = loadBaselineRules(packs);
+    if (baseline && baseline.length > 0) {
+        if (verbose) {
+            console.error(`📦 Using bundled baseline rules (${baseline.length} rules)`);
+        }
+        return baseline;
+    }
+    // 4. Return null — engine will use hardcoded fallback
+    if (verbose) {
+        console.error('📦 No cached/baseline rules found, engine will use hardcoded fallback');
+    }
+    return null;
+}
+function loadConfig() {
+    try {
+        if (fs.existsSync(HALO_CONFIG_PATH)) {
+            return JSON.parse(fs.readFileSync(HALO_CONFIG_PATH, 'utf-8'));
+        }
+    }
+    catch {
+        // Ignore corrupt config
+    }
+    return null;
+}
+function saveConfig(config) {
+    try {
+        if (!fs.existsSync(HALO_CONFIG_DIR)) {
+            fs.mkdirSync(HALO_CONFIG_DIR, { recursive: true });
+        }
+        fs.writeFileSync(HALO_CONFIG_PATH, JSON.stringify(config, null, 2), 'utf-8');
+    }
+    catch {
+        // Silent failure — never block scan
+    }
+}
+// ==================== Scan History ====================
+function loadHistory() {
+    try {
+        if (fs.existsSync(HALO_HISTORY_PATH)) {
+            const data = JSON.parse(fs.readFileSync(HALO_HISTORY_PATH, 'utf-8'));
+            return Array.isArray(data) ? data : [];
+        }
+    }
+    catch {
+        // Silent failure — never block scan
+    }
+    return [];
+}
+function saveHistory(entry) {
+    try {
+        if (!fs.existsSync(HALO_CONFIG_DIR)) {
+            fs.mkdirSync(HALO_CONFIG_DIR, { recursive: true });
+        }
+        const history = loadHistory();
+        history.push(entry);
+        // FIFO: keep last MAX_HISTORY_ENTRIES
+        const trimmed = history.slice(-MAX_HISTORY_ENTRIES);
+        fs.writeFileSync(HALO_HISTORY_PATH, JSON.stringify(trimmed, null, 2), 'utf-8');
+    }
+    catch {
+        // Silent failure — never block scan
+    }
+}
+async function submitCliLead(email) {
+    try {
+        const res = await fetch(`${SUPABASE_URL}/rest/v1/halo_leads`, {
+            method: 'POST',
+            headers: {
+                'apikey': SUPABASE_ANON_KEY,
+                'Authorization': `Bearer ${SUPABASE_ANON_KEY}`,
+                'Content-Type': 'application/json',
+                'Prefer': 'return=minimal',
+            },
+            body: JSON.stringify({
+                email,
+                source: 'cli',
+                cli_version: CLI_VERSION,
+                node_version: process.version,
+                os: os.platform(),
+                consent_given: true,
+                consent_text: 'Opted in via Halo CLI first-run prompt',
+            }),
+        });
+        // Silent — don't care about response
+    }
+    catch {
+        // Silent failure — never block scan
+    }
+}
+// ==================== License Validation & Scan Limits (P3-1) ====================
+const FREE_SCAN_LIMIT = 5;
+exports.FREE_SCAN_LIMIT = FREE_SCAN_LIMIT;
+/**
+ * Validate a license key against Supabase validate-license edge function.
+ * Returns license info or null on failure.
+ */
+async function validateLicenseKey(licenseKey) {
+    try {
+        const res = await fetch(`${SUPABASE_URL}/functions/v1/validate-license`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${SUPABASE_ANON_KEY}`,
+            },
+            body: JSON.stringify({ license_key: licenseKey }),
+        });
+        const data = await res.json();
+        return {
+            valid: !!data.valid,
+            tier: data.tier,
+            email: data.email,
+            status: data.status,
+            expires_at: data.expires_at,
+            error: data.error,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Activate a license key — validates via Supabase, stores in ~/.halo/config.json.
+ */
+async function activateLicense(licenseKey) {
+    console.log(`\n  ${c(colors.dim, 'Validating license key...')}`);
+    const result = await validateLicenseKey(licenseKey);
+    if (!result || !result.valid) {
+        console.error(`\n  ${c(colors.red + colors.bold, '✗ Invalid license key')}`);
+        if (result?.error) {
+            console.error(`  ${c(colors.dim, result.error)}`);
+        }
+        console.error(`\n  ${c(colors.dim, 'Get a license at')} ${c(colors.cyan, 'https://runhalo.dev/#pricing')}\n`);
+        return 1;
+    }
+    // Save to config
+    const existing = loadConfig() || {
+        prompted: true,
+        promptedAt: new Date().toISOString(),
+        consent: false,
+    };
+    saveConfig({
+        ...existing,
+        license_key: licenseKey,
+        tier: result.tier,
+        email: result.email || existing.email,
+    });
+    const tierLabel = result.tier === 'enterprise' ? 'Enterprise' : 'Pro';
+    console.log(`\n  ${c('\x1b[32m' + colors.bold, `✓ Halo ${tierLabel} activated!`)}`);
+    console.log(`  ${c(colors.dim, 'Email:')} ${result.email}`);
+    console.log(`  ${c(colors.dim, 'Tier:')}  ${c(colors.cyan, tierLabel)}`);
+    if (result.expires_at) {
+        const expiryDate = new Date(result.expires_at).toLocaleDateString('en-US', {
+            year: 'numeric', month: 'long', day: 'numeric'
+        });
+        console.log(`  ${c(colors.dim, 'Valid until:')} ${expiryDate}`);
+    }
+    console.log(`\n  ${c(colors.dim, 'Unlimited scans. All Pro features unlocked.')}`);
+    console.log(`  ${c(colors.dim, 'Run')} ${c(colors.cyan, 'halo scan . --report --ethical')} ${c(colors.dim, 'to get started.')}\n`);
+    return 0;
+}
+/**
+ * Check scan limit for free-tier users.
+ * Returns true if scan is allowed, false if blocked.
+ * CI environments always bypass limits.
+ */
+function checkScanLimit() {
+    // CI always unlimited — never break builds
+    if (process.env.CI || process.stdout.isTTY === false) {
+        return true;
+    }
+    const config = loadConfig();
+    // Pro/Enterprise: unlimited
+    if (config?.tier === 'pro' || config?.tier === 'enterprise') {
+        return true;
+    }
+    // Free tier: check daily limit
+    const today = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+    if (config?.scan_date !== today) {
+        // New day — reset counter
+        saveConfig({
+            ...config,
+            prompted: config?.prompted ?? true,
+            promptedAt: config?.promptedAt ?? new Date().toISOString(),
+            consent: config?.consent ?? false,
+            scans_today: 1,
+            scan_date: today,
+        });
+        return true;
+    }
+    const scansToday = config?.scans_today ?? 0;
+    if (scansToday >= FREE_SCAN_LIMIT) {
+        // Limit reached — show upgrade message
+        console.error('');
+        console.error(`  ${c(colors.yellow + colors.bold, `⚡ Daily scan limit reached (${FREE_SCAN_LIMIT}/${FREE_SCAN_LIMIT})`)}`);
+        console.error(`  ${c(colors.dim, 'Free tier allows 5 scans per day. Your scans reset at midnight.')}`);
+        console.error('');
+        console.error(`  ${c(colors.cyan, 'Upgrade to Halo Pro ($29/mo)')}`);
+        console.error(`  ${c(colors.dim, '→ Unlimited scans, ethical design rules, HTML reports, guided fixes')}`);
+        console.error(`  ${c(colors.dim, '→')} ${c(colors.cyan, 'https://runhalo.dev/#pricing')}`);
+        console.error('');
+        return false;
+    }
+    // Increment counter
+    saveConfig({
+        ...config,
+        prompted: config?.prompted ?? true,
+        promptedAt: config?.promptedAt ?? new Date().toISOString(),
+        consent: config?.consent ?? false,
+        scans_today: scansToday + 1,
+        scan_date: today,
+    });
+    return true;
+}
+/**
+ * Check if a Pro feature is available for the current user.
+ * Returns true if allowed, false with upsell message if blocked.
+ */
+function checkProFeature(featureName, flagName) {
+    // CI always has access — don't break pipelines
+    if (process.env.CI || process.stdout.isTTY === false) {
+        return true;
+    }
+    const config = loadConfig();
+    if (config?.tier === 'pro' || config?.tier === 'enterprise') {
+        return true;
+    }
+    console.error('');
+    console.error(`  ${c(colors.yellow + colors.bold, `⚡ ${featureName} requires Halo Pro`)}`);
+    console.error(`  ${c(colors.dim, `The ${flagName} flag is a Pro feature.`)}`);
+    console.error('');
+    console.error(`  ${c(colors.cyan, 'Upgrade to Halo Pro ($29/mo)')}`);
+    console.error(`  ${c(colors.dim, '→ Unlimited scans, ethical design rules, HTML reports, guided fixes')}`);
+    console.error(`  ${c(colors.dim, '→')} ${c(colors.cyan, 'https://runhalo.dev/#pricing')}`);
+    console.error('');
+    return false;
+}
+/**
+ * First-run email prompt — one-time, optional, non-blocking.
+ * Auto-skips when: config exists, --no-prompt, !isTTY, CI env.
+ */
+async function firstRunPrompt(noPrompt) {
+    // Skip conditions
+    if (noPrompt)
+        return;
+    if (!process.stdin.isTTY)
+        return;
+    if (process.env.CI)
+        return;
+    const existing = loadConfig();
+    if (existing?.prompted)
+        return;
+    // Show prompt on stderr (never pollute stdout JSON/SARIF)
+    process.stderr.write('\n');
+    process.stderr.write('  Welcome to Halo! 👋\n');
+    process.stderr.write('  Stay updated on COPPA scanning, new rules, and Pro features.\n');
+    process.stderr.write('  We\'ll send occasional product updates. No spam. Unsubscribe anytime.\n');
+    process.stderr.write('\n');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    return new Promise((resolve) => {
+        rl.question('  Email (Enter to skip): ', (answer) => {
+            rl.close();
+            const email = answer.trim();
+            if (email && email.includes('@')) {
+                // Save config with email
+                saveConfig({
+                    email,
+                    prompted: true,
+                    promptedAt: new Date().toISOString(),
+                    consent: true,
+                });
+                // Submit to Supabase (fire-and-forget)
+                submitCliLead(email).catch(() => { });
+                process.stderr.write(`  ${c('\x1b[32m', '✓')} Thanks! We'll keep you posted.\n\n`);
+            }
+            else {
+                // Skipped — save that we prompted (never ask again)
+                saveConfig({
+                    prompted: true,
+                    promptedAt: new Date().toISOString(),
+                    consent: false,
+                });
+                process.stderr.write('\n');
+            }
+            resolve();
+        });
+    });
+}
 /**
  * Main scan function
  */
@@ -451,15 +1598,27 @@ async function scan(paths, options) {
     if (options.verbose && projectDomains.length > 0) {
         console.error(`🏠 Detected project domains: ${[...new Set(projectDomains)].join(', ')}`);
     }
-    const engine = new engine_1.HaloEngine({
+    // Resolve rules via API/cache/baseline fallback chain
+    const packs = resolvePacks(options);
+    const resolvedRawRules = await resolveRules(packs, options.offline, options.verbose);
+    const resolvedRules = resolvedRawRules ? (0, engine_1.compileRawRules)(resolvedRawRules) : undefined;
+    const engineConfig = {
         includePatterns: options.include,
         excludePatterns: options.exclude,
         rules: options.rules.length > 0 ? options.rules : undefined,
         severityFilter: options.severity.length > 0 ? options.severity : undefined,
         ignoreConfig,
         projectDomains: projectDomains.length > 0 ? [...new Set(projectDomains)] : undefined,
-        ethical: options.ethicalPreview
-    });
+        // If we got rules from API/cache, use loadedRules. Otherwise fall through to legacy flags.
+        ...(resolvedRules
+            ? { loadedRules: resolvedRules }
+            : {
+                ethical: options.ethicalPreview,
+                aiAudit: options.aiAudit,
+                sectorAuSbd: options.sectorAuSbd,
+            }),
+    };
+    const engine = new engine_1.HaloEngine(engineConfig);
     const results = [];
     let fileCount = 0;
     // Collect all files to scan
@@ -523,6 +1682,17 @@ async function scan(paths, options) {
         }
         console.error(`🔍 Scanning ${uniqueFiles.length} files...`);
     }
+    // Scan start banner (text format only, stderr so it doesn't pollute JSON/SARIF)
+    if (options.format === 'text') {
+        const packNameMap = {
+            'coppa': 'COPPA',
+            'ethical': 'Ethical Design',
+            'ai-audit': 'AI Audit',
+            'au-sbd': 'AU Safety by Design',
+        };
+        const packLabel = packs.map(p => packNameMap[p] || p).join(' + ');
+        console.error(c(colors.dim, `🔍 Scanning ${uniqueFiles.length} files (${packLabel})...`));
+    }
     // Max file size: 1MB (skip large/binary files)
     const MAX_FILE_SIZE = 1024 * 1024;
     // Scan each file
@@ -559,6 +1729,24 @@ async function scan(paths, options) {
             }
         }
     }
+    // Calculate compliance score
+    const allViolations = results.flatMap(r => r.violations);
+    const scorer = new engine_1.ComplianceScoreEngine();
+    const scoreResult = scorer.calculate(allViolations, fileCount);
+    // Scan history: compute trend BEFORE saving (so we compare to previous, not current)
+    const projectPath = path.resolve(paths[0] || '.');
+    const trendLine = formatTrend(scoreResult.score, projectPath);
+    // Save to history (silent, never blocks)
+    saveHistory({
+        scannedAt: new Date().toISOString(),
+        score: scoreResult.score,
+        grade: scoreResult.grade,
+        totalViolations: scoreResult.totalViolations,
+        bySeverity: scoreResult.bySeverity,
+        filesScanned: fileCount,
+        projectPath,
+        rulesTriggered: scoreResult.rulesTriggered,
+    });
     // Format output
     let output;
     switch (options.format) {
@@ -566,10 +1754,35 @@ async function scan(paths, options) {
             output = formatSARIF(results, engine.getRules());
             break;
         case 'json':
-            output = formatJSON(results);
+            output = formatJSON(results, scoreResult);
             break;
         default:
-            output = formatText(results, options.verbose, fileCount);
+            output = formatText(results, options.verbose, fileCount, scoreResult);
+            // Append trend line for text output
+            if (trendLine) {
+                output += trendLine + '\n';
+            }
+    }
+    // Generate report if requested (HTML or PDF based on filename extension)
+    if (options.report) {
+        const reportFilename = typeof options.report === 'string'
+            ? options.report
+            : 'halo-report.html';
+        const projectHistory = loadHistory().filter(h => h.projectPath === projectPath);
+        // Exclude the entry we just saved (last one) so trend is accurate
+        const historyForReport = projectHistory.slice(0, -1);
+        if (reportFilename.endsWith('.pdf')) {
+            // PDF report (government-procurement grade)
+            const pdfBuffer = await generatePdfReport(results, scoreResult, fileCount, projectPath, historyForReport);
+            fs.writeFileSync(reportFilename, pdfBuffer);
+            console.error(`📄 PDF report written to ${reportFilename}`);
+        }
+        else {
+            // HTML report (default)
+            const html = generateHtmlReport(results, scoreResult, fileCount, projectPath, historyForReport);
+            fs.writeFileSync(reportFilename, html, 'utf-8');
+            console.error(`📄 HTML report written to ${reportFilename}`);
+        }
     }
     // Write output (only one path — no duplication)
     if (options.output) {
@@ -579,6 +1792,15 @@ async function scan(paths, options) {
     else {
         process.stdout.write(output);
     }
+    // Post-scan CTA (text format only — goes to stderr so it won't pollute piped output)
+    if (options.format === 'text') {
+        console.error('');
+        console.error('─────────────────────────────────────────');
+        console.error('📊 Track results over time:  runhalo.dev/app/dashboard');
+        console.error('🔗 Share your score:         runhalo.dev/app/score');
+        console.error('⬆️  Upload (Pro):            runhalo scan . --upload');
+        console.error('─────────────────────────────────────────');
+    }
     // Return exit code based on violations
     const hasCriticalOrHigh = results.some(r => r.violations.some(v => v.severity === 'critical' || v.severity === 'high'));
     if (hasCriticalOrHigh) {
@@ -589,14 +1811,231 @@ async function scan(paths, options) {
     }
     return 0; // No violations
 }
+/**
+ * Main fix function
+ * Flow: discover files → scan → filter auto-fixable → apply fixes → re-scan → write (or dry-run)
+ */
+async function fix(paths, options) {
+    const scanRoot = paths[0] || '.';
+    if (!fs.existsSync(scanRoot)) {
+        console.error(`❌ Path not found: ${scanRoot}`);
+        return 3;
+    }
+    const engine = new engine_1.HaloEngine({});
+    const fixer = new engine_1.FixEngine();
+    // Collect files (reuse scan discovery logic)
+    const allFiles = [];
+    for (const scanPath of paths) {
+        let stats;
+        try {
+            stats = fs.statSync(scanPath);
+        }
+        catch {
+            console.error(`❌ Path not found: ${scanPath}`);
+            return 3;
+        }
+        if (stats.isDirectory()) {
+            const patterns = options.include.length > 0
+                ? options.include
+                : getDefaultPatterns();
+            const excludes = options.exclude.length > 0
+                ? options.exclude
+                : getDefaultExcludePatterns();
+            for (const pattern of patterns) {
+                const fullPattern = path.join(scanPath, pattern);
+                const files = await (0, glob_1.glob)(fullPattern, {
+                    ignore: excludes,
+                    absolute: true
+                });
+                allFiles.push(...files);
+            }
+        }
+        else if (stats.isFile()) {
+            allFiles.push(path.resolve(scanPath));
+        }
+    }
+    const uniqueFiles = [...new Set(allFiles)];
+    if (options.verbose) {
+        console.error(`🔍 Scanning ${uniqueFiles.length} files for auto-fixable violations...`);
+    }
+    const MAX_FILE_SIZE = 1024 * 1024;
+    let totalApplied = 0;
+    let totalSkipped = 0;
+    let totalFiles = 0;
+    let filesFixed = 0;
+    const fixedRuleIds = new Set();
+    // Track all violations for Pro tease summary
+    let totalAutoViolations = 0;
+    let totalGuidedViolations = 0;
+    let totalFlagOnlyViolations = 0;
+    for (const filePath of uniqueFiles) {
+        try {
+            const stat = fs.statSync(filePath);
+            if (stat.size > MAX_FILE_SIZE)
+                continue;
+            const content = fs.readFileSync(filePath, 'utf-8');
+            if (content.substring(0, 512).includes('\0'))
+                continue;
+            const violations = engine.scanFile(filePath, content);
+            if (violations.length === 0) {
+                totalFiles++;
+                continue;
+            }
+            // Count violations by tier for Pro tease
+            for (const v of violations) {
+                const spec = engine_1.REMEDIATION_MAP[v.ruleId];
+                if (!spec)
+                    continue;
+                switch (spec.fixability) {
+                    case 'auto':
+                        totalAutoViolations++;
+                        break;
+                    case 'guided':
+                        totalGuidedViolations++;
+                        break;
+                    case 'flag-only':
+                        totalFlagOnlyViolations++;
+                        break;
+                }
+            }
+            // Apply auto-fixes
+            const result = fixer.applyFixes(content, violations, {
+                rules: options.rules.length > 0 ? options.rules : undefined,
+            });
+            const applied = result.fixes.filter(f => f.status === 'applied');
+            const skipped = result.fixes.filter(f => f.status === 'skipped');
+            if (applied.length > 0) {
+                filesFixed++;
+                totalApplied += applied.length;
+                applied.forEach(f => fixedRuleIds.add(f.ruleId));
+                if (options.dryRun) {
+                    // Show diff
+                    const diff = fixer.generateDiff(filePath, content, result.fixedContent);
+                    console.log(diff);
+                    console.log('');
+                }
+                else {
+                    // Write fixed content
+                    fs.writeFileSync(filePath, result.fixedContent, 'utf-8');
+                }
+                // Show warnings for behavior-changing fixes
+                for (const f of applied) {
+                    if (f.warning) {
+                        const relPath = path.relative(process.cwd(), filePath);
+                        console.error(`  ${c(colors.yellow, '⚠')}  ${c(colors.dim, relPath + ':' + f.line)} ${c(colors.yellow, f.warning)}`);
+                    }
+                }
+                if (options.verbose) {
+                    const relPath = path.relative(process.cwd(), filePath);
+                    console.error(`  ${c(colors.cyan, '✓')} ${relPath}: ${applied.length} fix(es) applied`);
+                }
+            }
+            totalSkipped += skipped.length;
+            totalFiles++;
+        }
+        catch (err) {
+            if (options.verbose) {
+                console.error(`⚠️  Error processing ${filePath}:`, err);
+            }
+        }
+    }
+    // Summary
+    console.error('');
+    if (totalApplied > 0) {
+        const action = options.dryRun ? 'Would auto-fix' : 'Auto-fixed';
+        console.error(`${c(colors.bold + colors.cyan, `✓ ${action} ${totalApplied} issue(s)`)} across ${filesFixed} file(s) (${fixedRuleIds.size} rule(s))`);
+    }
+    else {
+        console.error(`${c(colors.dim, 'No auto-fixable issues found.')}`);
+    }
+    // Pro tease: show unfixed counts by tier
+    const remainingGuided = totalGuidedViolations;
+    const remainingFlagOnly = totalFlagOnlyViolations;
+    if (remainingGuided > 0 && !options.guided) {
+        console.error(`${c(colors.yellow, `⚠ ${remainingGuided} issue(s) need guided fixes`)} ${c(colors.dim, '(run with --guided to generate scaffolds)')}`);
+    }
+    if (remainingFlagOnly > 0) {
+        console.error(`${c(colors.blue, `ℹ ${remainingFlagOnly} issue(s) flagged for design review`)} ${c(colors.dim, '(requires manual assessment)')}`);
+    }
+    // Guided fixes: generate scaffold files for Tier 2 violations
+    if (options.guided && totalGuidedViolations > 0) {
+        const { ScaffoldEngine } = require('@runhalo/engine');
+        const scaffoldEngine = new ScaffoldEngine();
+        // Collect all violations with guided fixability
+        const guidedViolations = [];
+        for (const filePath of uniqueFiles) {
+            try {
+                const content = fs.readFileSync(filePath, 'utf-8');
+                const violations = engine.scanFile(filePath, content);
+                for (const v of violations) {
+                    const spec = engine_1.REMEDIATION_MAP[v.ruleId];
+                    if (spec?.fixability === 'guided') {
+                        guidedViolations.push(v);
+                    }
+                }
+            }
+            catch { }
+        }
+        const projectPath = path.resolve(scanRoot);
+        const frameworkOverride = options.framework;
+        const summary = scaffoldEngine.getSummary(guidedViolations, projectPath, frameworkOverride);
+        if (summary.totalScaffolds > 0) {
+            console.error('');
+            console.error(`${c(colors.bold + colors.cyan, '🔧 Guided Fixes')} (${summary.framework}${summary.typescript ? ' + TypeScript' : ''}):`);
+            if (options.dryRun) {
+                // Dry run: just show what would be generated
+                const results = scaffoldEngine.generateScaffolds(guidedViolations, projectPath, frameworkOverride);
+                for (const result of results) {
+                    console.error(`  ${c(colors.cyan, '●')} ${c(colors.bold, result.scaffoldId)} → ${result.ruleId}`);
+                    for (const file of result.files) {
+                        console.error(`    ${c(colors.dim, '→')} ${file.relativePath} — ${file.description}`);
+                    }
+                }
+                console.error('');
+                console.error(`  ${c(colors.dim, 'Run without --dry-run to write scaffold files.')}`);
+            }
+            else {
+                // Write scaffold files
+                const outputDir = options.scaffoldDir || path.join(process.cwd(), 'halo-scaffolds');
+                const results = scaffoldEngine.generateScaffolds(guidedViolations, projectPath, frameworkOverride);
+                let filesWritten = 0;
+                for (const result of results) {
+                    for (const file of result.files) {
+                        const fullPath = path.join(outputDir, file.relativePath);
+                        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+                        fs.writeFileSync(fullPath, file.content, 'utf-8');
+                        filesWritten++;
+                        if (options.verbose) {
+                            console.error(`  ${c(colors.cyan, '✓')} ${path.relative(process.cwd(), fullPath)}`);
+                        }
+                    }
+                }
+                console.error(`${c(colors.bold + colors.cyan, `✓ Generated ${filesWritten} scaffold file(s)`)} in ${path.relative(process.cwd(), outputDir) || outputDir}`);
+            }
+        }
+        // Show unavailable scaffolds (link to docs)
+        if (summary.unavailableIds.length > 0) {
+            console.error('');
+            for (const id of summary.unavailableIds) {
+                console.error(`  ${c(colors.dim, '📖')} ${id} — docs: ${c(colors.blue, `https://runhalo.dev/rules/${id}`)}`);
+            }
+        }
+    }
+    console.error('');
+    // Exit codes: 0 = all good, 1 = partial (some violations remain), 3 = fatal
+    if (totalApplied > 0 && (remainingGuided > 0 || remainingFlagOnly > 0)) {
+        return 1; // Partial — some issues remain
+    }
+    return 0;
+}
 // CLI setup
 program
     .name('runhalo')
-    .description('Halo - Child Safety Compliance Scanner for COPPA 2.0')
+    .description('Halo \u2014 Ethical code scanner for children\u2019s digital safety')
     .version('1.0.0');
 program
     .command('scan')
-    .description('Scan files or directories for COPPA violations')
+    .description('Scan source code for child safety compliance violations')
     .argument('[paths...]', 'Paths to scan (default: current directory)', ['.'])
     .option('-f, --format <format>', 'Output format: json, sarif, text', 'text')
     .option('-i, --include <patterns...>', 'File patterns to include')
@@ -605,9 +2044,37 @@ program
     .option('-s, --severity <levels...>', 'Filter by severity: critical, high, medium, low')
     .option('-o, --output <file>', 'Output file path')
     .option('--ethical-preview', 'Enable experimental ethical design rules (Sprint 5 preview)')
+    .option('--ai-audit', 'Enable AI-generated code audit rules (catch AI coding assistant mistakes)')
+    .option('--sector-au-sbd', 'Enable Australia Safety by Design sector rules (eSafety Commissioner framework)')
+    .option('--pack <packs...>', 'Rule packs to scan against (e.g., coppa ethical ai-audit au-sbd)')
+    .option('--offline', 'Skip API fetch, use cached or bundled rules only')
+    .option('--report [filename]', 'Generate HTML compliance report (default: halo-report.html)')
+    .option('--upload', 'Upload scan results to Halo Dashboard (requires Pro)')
+    .option('--no-prompt', 'Skip first-run email prompt')
     .option('-v, --verbose', 'Verbose output')
     .action(async (paths, options) => {
     try {
+        await firstRunPrompt(options.prompt === false);
+        // Pro feature gating (soft upsell — exit 0, not error)
+        if (options.report && !checkProFeature('HTML Compliance Reports', '--report')) {
+            process.exit(0);
+        }
+        if (options.ethicalPreview && !checkProFeature('Ethical Design Rules', '--ethical-preview')) {
+            process.exit(0);
+        }
+        if (options.aiAudit && !checkProFeature('AI-Generated Code Audit', '--ai-audit')) {
+            process.exit(0);
+        }
+        if (options.sectorAuSbd && !checkProFeature('AU Safety by Design Rules', '--sector-au-sbd')) {
+            process.exit(0);
+        }
+        if (options.upload && !checkProFeature('Dashboard Upload', '--upload')) {
+            process.exit(0);
+        }
+        // Scan limit check (soft — exit 0, not error)
+        if (!checkScanLimit()) {
+            process.exit(0);
+        }
         const exitCode = await scan(paths, {
             format: options.format || 'text',
             include: options.include || [],
@@ -616,8 +2083,66 @@ program
             severity: options.severity || [],
             output: options.output || '',
             verbose: options.verbose || false,
-            ethicalPreview: options.ethicalPreview || false
+            ethicalPreview: options.ethicalPreview || false,
+            aiAudit: options.aiAudit || false,
+            sectorAuSbd: options.sectorAuSbd || false,
+            report: options.report || false,
+            pack: options.pack || [],
+            offline: options.offline || false,
         });
+        // Upload to Halo Dashboard (non-blocking — upload failure doesn't affect exit code)
+        if (options.upload) {
+            try {
+                const config = loadConfig();
+                if (!config.license_key) {
+                    console.error('⚠️  No license key found. Run `halo activate <key>` first.');
+                }
+                else {
+                    console.error('☁️  Uploading scan results to Halo Dashboard...');
+                    // Re-scan in JSON format to get structured data for upload
+                    // Use the scan history to get the latest results
+                    const history = loadHistory();
+                    const lastEntry = history[history.length - 1];
+                    if (lastEntry) {
+                        const projectPath = path.resolve(paths[0] || '.');
+                        // Build minimal scan_json from last scan entry
+                        const scanJsonForUpload = {
+                            repo: projectPath,
+                            scannedAt: lastEntry.scannedAt,
+                            filesScanned: lastEntry.filesScanned,
+                            totalFiles: lastEntry.filesScanned,
+                            violations: [], // Full violations not in history; send metadata only
+                            score: lastEntry.score,
+                            grade: lastEntry.grade,
+                            bySeverity: lastEntry.bySeverity,
+                            rulesTriggered: lastEntry.rulesTriggered,
+                        };
+                        const uploadUrl = 'https://wrfwcmyxxbafcdvxlmug.supabase.co/functions/v1/upload-scan';
+                        const res = await fetch(uploadUrl, {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify({
+                                license_key: config.license_key,
+                                scan_json: scanJsonForUpload,
+                                repo_url: projectPath,
+                            }),
+                        });
+                        if (res.ok) {
+                            const data = await res.json();
+                            console.error(`✅ Uploaded to dashboard: ${data.dashboard_url}`);
+                            console.error(`🔗 Share: ${data.share_url}`);
+                        }
+                        else {
+                            const err = await res.json().catch(() => ({}));
+                            console.error(`⚠️  Upload failed: ${err.error || res.statusText}`);
+                        }
+                    }
+                }
+            }
+            catch (uploadErr) {
+                console.error(`⚠️  Upload failed: ${uploadErr instanceof Error ? uploadErr.message : uploadErr}`);
+            }
+        }
         process.exit(exitCode);
     }
     catch (error) {
@@ -625,6 +2150,358 @@ program
         process.exit(3); // Fatal error
     }
 });
+program
+    .command('fix')
+    .description('Auto-fix COPPA violations (Tier 1 deterministic transforms + Tier 2 scaffolds)')
+    .argument('[paths...]', 'Paths to fix (default: current directory)', ['.'])
+    .option('--dry-run', 'Show diffs without writing changes', false)
+    .option('-r, --rules <ruleIds...>', 'Fix specific rules only')
+    .option('-i, --include <patterns...>', 'File patterns to include')
+    .option('-e, --exclude <patterns...>', 'File patterns to exclude')
+    .option('--guided', 'Generate scaffold files for Tier 2 guided fixes', false)
+    .option('--framework <framework>', 'Override framework detection: react, nextjs, vue, svelte, plain-js')
+    .option('--scaffold-dir <dir>', 'Output directory for scaffold files (default: ./halo-scaffolds)')
+    .option('--no-prompt', 'Skip first-run email prompt')
+    .option('-v, --verbose', 'Detailed output', false)
+    .action(async (paths, options) => {
+    try {
+        await firstRunPrompt(options.prompt === false);
+        // Pro feature gating for guided fixes
+        if (options.guided && !checkProFeature('Guided Scaffold Generation', '--guided')) {
+            process.exit(0);
+        }
+        const exitCode = await fix(paths, {
+            dryRun: options.dryRun || false,
+            rules: options.rules || [],
+            include: options.include || [],
+            exclude: options.exclude || [],
+            verbose: options.verbose || false,
+            guided: options.guided || false,
+            framework: options.framework,
+            scaffoldDir: options.scaffoldDir,
+        });
+        process.exit(exitCode);
+    }
+    catch (error) {
+        console.error('❌ Error:', error instanceof Error ? error.message : error);
+        process.exit(3);
+    }
+});
+// ==================== Activate Command (License Key) ====================
+program
+    .command('activate')
+    .description('Activate a Halo Pro or Enterprise license key')
+    .argument('<key>', 'License key (UUID from your purchase confirmation)')
+    .action(async (key) => {
+    try {
+        const exitCode = await activateLicense(key);
+        process.exit(exitCode);
+    }
+    catch (error) {
+        console.error('❌ Error:', error instanceof Error ? error.message : error);
+        process.exit(3);
+    }
+});
+/**
+ * COPPA compliance rules content for AI coding assistants.
+ * Teaches the assistant to write COPPA-compliant code proactively.
+ */
+function getIDERulesContent() {
+    return `# Halo — COPPA 2.0 Compliance Rules for AI Coding Assistants
+# Generated by: npx runhalo init --ide
+# Docs: https://runhalo.dev/rules
+# Scanner: npx runhalo scan .
+
+You are working on a child-directed application subject to COPPA 2.0 (effective April 22, 2026).
+All code you generate MUST comply with these rules. Violations carry penalties up to $53,088/day.
+
+## CRITICAL Rules (auto-block in CI)
+
+1. **No Social Login Without Age Gate** (coppa-auth-001)
+   Never use signInWithPopup(), passport.authenticate('google'), or OAuth flows
+   without first verifying the user is 13+ via date-of-birth check.
+
+2. **No Ad Trackers** (coppa-tracking-003)
+   Never add Google Analytics (gtag), Facebook Pixel (fbq), or AdSense (adsbygoogle)
+   without setting child_directed_treatment: true.
+
+3. **No Biometric Data Collection** (coppa-bio-012)
+   Never use FaceID, TouchID, face-api.js, or voice print APIs without
+   explicit verifiable parental consent. Voice prints are biometric data under COPPA 2.0.
+
+4. **No Unencrypted PII** (coppa-sec-006)
+   Never use http:// for API endpoints that handle personal information.
+   All PII transmission must use https://.
+
+5. **Default Privacy = Private** (coppa-default-020)
+   Never set isProfileVisible: true, visibility: "public", or defaultPrivacy: "public".
+   All profiles default to private. Privacy by design is required.
+
+## HIGH Rules (flag in PR review)
+
+6. **No PII in URL Parameters** (coppa-data-002)
+   Never pass email, name, DOB, or phone as GET query parameters.
+   Use POST with request body instead.
+
+7. **No Precise Geolocation** (coppa-geo-004)
+   Never use navigator.geolocation.getCurrentPosition() without parental consent.
+   Downgrade accuracy to city-level if needed.
+
+8. **No Passive Audio Recording** (coppa-audio-007)
+   Never call getUserMedia({audio: true}) or MediaRecorder without click handler
+   and parental consent check.
+
+9. **No Unmoderated Chat Widgets** (coppa-ext-011)
+   Never add Intercom, Zendesk, Drift, or Freshdesk without age-gating.
+   Chat widgets allow children to disclose PII freely.
+
+10. **No PII in Analytics** (coppa-analytics-018)
+    Never pass email, name, or phone to analytics.identify(), mixpanel.identify(),
+    or segment.identify(). Hash user IDs instead.
+
+11. **No UGC Without PII Filter** (coppa-ugc-014)
+    Text areas for bio, about-me, or comments must pass through PII scrubbing
+    before database storage.
+
+12. **Parent Email Required for Child Contact** (coppa-flow-009)
+    Forms collecting child_email or student_email must also require parent_email.
+
+## MEDIUM Rules (compliance warnings)
+
+13. **Data Retention Required** (coppa-retention-005)
+    Database schemas must include deleted_at, expiration_date, or TTL index.
+    COPPA requires data retention policies.
+
+14. **Privacy Policy on Registration** (coppa-ui-008)
+    Registration forms must include a visible link to the privacy policy.
+
+15. **Secure Default Passwords** (coppa-sec-010)
+    Never use "password", "123456", or "changeme" as default/initial passwords.
+
+16. **External Link Warnings** (coppa-ext-017)
+    External links opening in _blank should trigger a "You are leaving..." modal.
+
+17. **Push Notification Consent** (coppa-notif-013)
+    Push notifications are "Online Contact Info" under COPPA 2.0.
+    Gate subscriptions behind parental dashboard settings.
+
+18. **Teacher Account Verification** (coppa-edu-019)
+    Teacher sign-ups using @gmail.com bypass the School Official consent exception.
+    Restrict to .edu domains or require manual approval.
+
+19. **XSS Prevention** (coppa-sec-015)
+    Never use dangerouslySetInnerHTML or .innerHTML with user-controlled content.
+    Use DOMPurify or standard JSX rendering.
+
+20. **Cookie Consent** (coppa-cookies-016)
+    Cookies or localStorage storing tracking/PII data require a consent banner.
+
+## AI Code Generation Guidelines
+
+When generating code for this project:
+- Always add age verification before authentication flows
+- Always use HTTPS for API endpoints
+- Always default user profiles to private
+- Always add cookie consent before setting tracking cookies
+- Always use POST (not GET) for forms collecting personal information
+- Always add PII scrubbing middleware before storing user-generated content
+- Always include data retention/deletion utilities in database schemas
+- Never add analytics, tracking, or ad scripts without child_directed_treatment flags
+- Never embed third-party chat/support widgets without age-gating logic
+- Prefer privacy-preserving alternatives (hashed IDs, aggregated analytics, on-device processing)
+
+## Scan Your Code
+
+Run \`npx runhalo scan .\` to check compliance.
+Run \`npx runhalo fix . --guided\` for guided remediation scaffolds.
+Run \`npx runhalo scan . --report\` for an HTML compliance report.
+`;
+}
+/**
+ * Generate .cursor/rules content (Cursor-specific format)
+ */
+function getCursorRulesContent() {
+    return getIDERulesContent();
+}
+/**
+ * Generate .windsurfrules content (Windsurf-specific format)
+ */
+function getWindsurfRulesContent() {
+    return getIDERulesContent();
+}
+/**
+ * Generate .github/copilot-instructions.md (GitHub Copilot)
+ */
+function getCopilotInstructionsContent() {
+    return getIDERulesContent();
+}
+/**
+ * Init command — generate IDE rules files and project configuration.
+ */
+async function init(projectPath, options) {
+    const resolvedPath = path.resolve(projectPath);
+    if (!options.ide) {
+        console.log('🔮 Halo init — project setup');
+        console.log('');
+        console.log('Usage:');
+        console.log('  runhalo init --ide       Generate AI coding assistant rules files');
+        console.log('');
+        console.log('Options:');
+        console.log('  --ide        Generate .cursor/rules, .windsurfrules, .github/copilot-instructions.md');
+        console.log('  --force      Overwrite existing rules files');
+        return 0;
+    }
+    console.log('🔮 Halo init — Generating AI coding assistant rules...\n');
+    const files = [
+        {
+            path: path.join(resolvedPath, '.cursor', 'rules'),
+            content: getCursorRulesContent(),
+            label: 'Cursor'
+        },
+        {
+            path: path.join(resolvedPath, '.windsurfrules'),
+            content: getWindsurfRulesContent(),
+            label: 'Windsurf'
+        },
+        {
+            path: path.join(resolvedPath, '.github', 'copilot-instructions.md'),
+            content: getCopilotInstructionsContent(),
+            label: 'GitHub Copilot'
+        }
+    ];
+    let created = 0;
+    let skipped = 0;
+    for (const file of files) {
+        const dir = path.dirname(file.path);
+        const relativePath = path.relative(resolvedPath, file.path);
+        if (fs.existsSync(file.path) && !options.force) {
+            console.log(`  ⏭  ${relativePath} (exists — use --force to overwrite)`);
+            skipped++;
+            continue;
+        }
+        try {
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(file.path, file.content, 'utf-8');
+            console.log(`  ✅ ${relativePath} — ${file.label} rules`);
+            created++;
+        }
+        catch (err) {
+            console.error(`  ❌ ${relativePath} — ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    console.log('');
+    if (created > 0) {
+        console.log(`Created ${created} rules file${created > 1 ? 's' : ''}. Your AI assistant now knows COPPA 2.0.`);
+    }
+    if (skipped > 0) {
+        console.log(`Skipped ${skipped} existing file${skipped > 1 ? 's' : ''}.`);
+    }
+    console.log('');
+    console.log('What happens next:');
+    console.log('  • Cursor, Windsurf, and Copilot will read these rules automatically');
+    console.log('  • AI-generated code will follow COPPA compliance patterns');
+    console.log('  • Run "npx runhalo scan ." to verify compliance');
+    console.log('');
+    console.log('Full-stack compliance for the AI coding era:');
+    console.log('  CI:        uses: runhalo/action@v1 catches violations in PRs');
+    console.log('  Local:     npx runhalo scan . catches violations on your machine');
+    console.log('  Proactive: AI rules files prevent violations before they\'re written');
+    return 0;
+}
+program
+    .command('packs')
+    .description('List available rule packs')
+    .option('-v, --verbose', 'Show detailed pack information')
+    .action(async (options) => {
+    try {
+        const verbose = options.verbose || false;
+        // Try API first, then cache, then bundled
+        let packData = null;
+        // Try API
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), RULES_FETCH_TIMEOUT_MS);
+            const res = await fetch(`${RULES_API_BASE}/rules-catalog`, { signal: controller.signal });
+            clearTimeout(timeout);
+            if (res.ok) {
+                const data = await res.json();
+                packData = data.packs || [];
+            }
+        }
+        catch {
+            // API failed — try bundled
+        }
+        // Fallback: load from bundled rules.json
+        if (!packData) {
+            try {
+                const rulesJsonPath = require.resolve('@runhalo/engine/rules/rules.json');
+                const data = JSON.parse(fs.readFileSync(rulesJsonPath, 'utf-8'));
+                packData = Object.values(data.packs).map((pack) => {
+                    const ruleCount = (data.rules || []).filter((r) => r.packs.includes(pack.id)).length;
+                    return {
+                        pack_id: pack.id,
+                        name: pack.name,
+                        description: pack.description,
+                        jurisdiction: pack.jurisdiction,
+                        is_free: pack.is_free,
+                        rule_count: ruleCount,
+                    };
+                });
+            }
+            catch {
+                console.error('❌ Could not load pack information');
+                process.exit(1);
+            }
+        }
+        console.log('');
+        console.log('Available Rule Packs:');
+        console.log('');
+        for (const pack of packData) {
+            const tier = pack.is_free ? c(colors.green, 'free') : c(colors.yellow, 'pro');
+            const id = c(colors.bold, pack.pack_id);
+            console.log(`  ${id} (${tier})  — ${pack.name} — ${pack.rule_count} rules`);
+            if (verbose && pack.description) {
+                console.log(`    ${c(colors.dim, pack.description)}`);
+                if (pack.jurisdiction) {
+                    console.log(`    ${c(colors.dim, `Jurisdiction: ${pack.jurisdiction}`)}`);
+                }
+            }
+        }
+        const totalRules = packData.reduce((sum, p) => sum + p.rule_count, 0);
+        console.log('');
+        console.log(`  ${c(colors.dim, `${packData.length} packs, ${totalRules} total rules`)}`);
+        console.log('');
+        console.log('Usage:');
+        console.log('  npx runhalo scan . --pack coppa ethical');
+        console.log('  npx runhalo scan . --pack coppa ai-audit au-sbd');
+        console.log('');
+    }
+    catch (error) {
+        console.error('❌ Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+program
+    .command('init')
+    .description('Initialize Halo in your project (generate IDE rules files)')
+    .argument('[path]', 'Project root path (default: current directory)', '.')
+    .option('--ide', 'Generate AI coding assistant rules files', false)
+    .option('--force', 'Overwrite existing rules files', false)
+    .action(async (projectPath, options) => {
+    try {
+        const exitCode = await init(projectPath, {
+            ide: options.ide || false,
+            force: options.force || false,
+        });
+        process.exit(exitCode);
+    }
+    catch (error) {
+        console.error('❌ Error:', error instanceof Error ? error.message : error);
+        process.exit(3);
+    }
+});
 // Run CLI
 if (require.main === module) {
     program.parse();