seo-intel 1.1.10 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 1.2.0 (2026-03-28)
+
+### AEO — AI Citability Audit (new feature)
+- **New command: `seo-intel aeo <project>`** (alias: `citability`) — score every page for how well AI assistants can cite it
+- Per-page citability score (0-100) computed from 6 signals: entity authority, structured claims, answer density, Q&A proximity, freshness, schema coverage
+- AI Query Intent classification per page: synthesis, decision support, implementation, exploration, validation
+- Tier breakdown: excellent (75+), good (55-74), needs work (35-54), poor (<35)
+- Signal strength analysis — identifies your weakest citability signals site-wide
+- Compares target vs competitor citability scores with delta
+- Low-scoring pages automatically feed into Intelligence Ledger as `citability_gap` insights
+- Dashboard: new "AI Citability Audit" card with stat bar, signal strength bars, and page score table
+- Runs on existing crawl data — zero new network calls, zero Ollama required
+- `--target-only` flag to skip competitor scoring
+- `--save` flag to export `.md` report
+
+## 1.1.12 (2026-03-28)
+
+### Intelligence Ledger
+- Analysis insights now **accumulate across runs** instead of showing only the latest
+- New `insights` table with fingerprint-based dedup — re-running `analyze` adds new ideas without losing old ones
+- Dashboard shows all active insights: 65 long-tails, 36 keyword gaps, 23 content gaps (vs 4 from latest-only)
+- Done/dismiss buttons on every insight card — mark fixes as done, dismiss irrelevant suggestions
+- `POST /api/insights/:id/status` endpoint for status toggling (active/done/dismissed)
+- Keywords Inventor also persists to Intelligence Ledger via `keywords --save`
+
+### Improvements
+- Prompt and raw output files now save as `.md` with YAML frontmatter (Obsidian-compatible)
+- Long-tail Opportunities moved to Research section where it belongs
+- Migrated all existing prompt `.txt` files to `.md` with frontmatter
+
+## 1.1.11 (2026-03-27)
+
+### Fixes
+- Extraction now preflights Ollama hosts at run start and only uses live hosts during crawl/extract
+- Dead fallback hosts no longer poison the run or trigger noisy repeated circuit-breaker fallback spam
+- Degraded mode messaging is clearer and only activates when no live extraction host remains
+- Extractor timeout errors now include host/model/timeout context
+
 ## 1.1.10 (2026-03-27)
 
 ### Security
@@ -64,4 +102,4 @@
 
 - Update checker, job stop API, background analyze
 - LAN Ollama host support with fallback
-- `html` CLI command, wizard UX improvements
+- `html` CLI command, wizard UX improvements

package/cli.js

@@ -38,7 +38,8 @@ import {
   insertKeywords, insertHeadings, insertLinks, insertPageSchemas,
   upsertTechnical, pruneStaleDomains,
   getCompetitorSummary, getKeywordMatrix, getHeadingStructure,
-  getPageHash, getSchemasByProject
+  getPageHash, getSchemasByProject,
+  upsertInsightsFromAnalysis, upsertInsightsFromKeywords,
 } from './db/db.js';
 import { generateMultiDashboard } from './reports/generate-html.js';
 import { buildTechnicalActions } from './exports/technical.js';
@@ -66,44 +67,78 @@ function defaultSiteUrl(domain) {
   return `${protocol}://${host}`;
 }
 
+function resolveExtractionRuntime(config) {
+  const primaryUrl = config?.crawl?.ollamaHost || process.env.OLLAMA_URL || 'http://localhost:11434';
+  const primaryModel = config?.crawl?.extractionModel || process.env.OLLAMA_MODEL || 'qwen3:4b';
+  const fallbackUrl = process.env.OLLAMA_FALLBACK_URL || '';
+  const fallbackModel = process.env.OLLAMA_FALLBACK_MODEL || primaryModel;
+  const localhost = 'http://localhost:11434';
+
+  const candidates = [
+    { host: String(primaryUrl).trim().replace(/\/+$/, ''), model: String(primaryModel).trim() || 'qwen3:4b' },
+  ];
+
+  if (fallbackUrl) {
+    candidates.push({
+      host: String(fallbackUrl).trim().replace(/\/+$/, ''),
+      model: String(fallbackModel).trim() || String(primaryModel).trim() || 'qwen3:4b',
+    });
+  }
+
+  if (!candidates.some(candidate => candidate.host === localhost)) {
+    candidates.push({ host: localhost, model: String(primaryModel).trim() || 'qwen3:4b' });
+  }
+
+  const seen = new Set();
+  return candidates.filter(candidate => {
+    if (!candidate.host) return false;
+    const key = `${candidate.host}::${candidate.model}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function applyExtractionRuntimeConfig(config) {
+  if (!config?.crawl) return;
+  if (config.crawl.ollamaHost) process.env.OLLAMA_URL = config.crawl.ollamaHost;
+  if (config.crawl.extractionModel) process.env.OLLAMA_MODEL = config.crawl.extractionModel;
+}
+
 // ── AI AVAILABILITY PREFLIGHT ────────────────────────────────────────────
 /**
  * Check if any AI extraction backend is reachable.
  * Tries: primary Ollama → fallback Ollama → returns false.
  * Fast: 2s timeout per host, runs sequentially.
  */
-async function checkOllamaAvailability() {
-  // Build host chain: primary → fallback → always try localhost as last resort
-  const configured = [
-    process.env.OLLAMA_URL,
-    process.env.OLLAMA_FALLBACK_URL,
-  ].filter(Boolean);
-  const localhost = 'http://localhost:11434';
-  const hosts = [...new Set([...configured, localhost])];
+async function checkOllamaAvailability(config) {
+  const candidates = resolveExtractionRuntime(config);
+  let sawReachableHost = false;
 
-  for (const host of hosts) {
+  for (const candidate of candidates) {
     try {
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), 2000);
-      const res = await fetch(`${host}/api/tags`, { signal: controller.signal });
+      const res = await fetch(`${candidate.host}/api/tags`, { signal: controller.signal });
       clearTimeout(timeout);
       if (res.ok) {
         const data = await res.json();
         const models = (data.models || []).map(m => m.name);
-        const targetModel = process.env.OLLAMA_MODEL || 'qwen3:4b';
-        const hasModel = models.some(m => m.startsWith(targetModel.split(':')[0]));
+        sawReachableHost = true;
+        const hasModel = models.some(m => m && m.split(':')[0] === candidate.model.split(':')[0]);
         if (hasModel) {
           return true; // Ollama reachable + model available
         }
-        // Ollama reachable but model missing — warn but allow degraded extraction
-        console.log(chalk.yellow(`  ⚠️  Ollama at ${host} is reachable but model "${targetModel}" not found`));
-        console.log(chalk.dim(`  Available models: ${models.join(', ') || 'none'}`));
-        console.log(chalk.dim(`  Run: ollama pull ${targetModel}`));
-        return false;
       }
     } catch { /* host unreachable, try next */ }
   }
 
+  if (sawReachableHost) {
+    const primary = candidates[0];
+    console.log(chalk.yellow(`  ⚠️  Ollama is reachable but model "${primary?.model || 'qwen3:4b'}" was not found on any live host`));
+    console.log(chalk.dim(`  Run: ollama pull ${primary?.model || 'qwen3:4b'}`));
+  }
+
   return false;
 }
 
@@ -362,6 +397,7 @@ program
   .action(async (project, opts) => {
     const config = loadConfig(project);
     const db = getDb();
+    applyExtractionRuntimeConfig(config);
 
     // ── Auto-discover subdomains for target domain ──────────────────────
     if (opts.discover !== false && config.target?.domain) {
@@ -435,7 +471,7 @@ program
 
     // ── BUG-003/009: AI preflight — check Ollama availability before crawl ──
     if (opts.extract !== false) {
-      const ollamaAvailable = await checkOllamaAvailability();
+      const ollamaAvailable = await checkOllamaAvailability(config);
       if (!ollamaAvailable) {
         console.log(chalk.yellow('\n  ⚠️  No AI extraction available (Ollama unreachable, no API keys configured)'));
         console.log(chalk.white('  → Switching to ') + chalk.bold.green('crawl-only mode') + chalk.white(' — raw data will be collected without AI extraction'));
@@ -687,9 +723,11 @@ program
     console.log(chalk.yellow(`Prompt length: ~${Math.round(prompt.length / 4)} tokens`));
     console.log(chalk.yellow('Sending to Gemini...\n'));
 
-    // Save prompt for debugging
-    const promptPath = join(__dirname, `reports/${project}-prompt-${Date.now()}.txt`);
-    writeFileSync(promptPath, prompt, 'utf8');
+    // Save prompt for debugging (markdown for Obsidian/agent compatibility)
+    const promptTs = Date.now();
+    const promptPath = join(__dirname, `reports/${project}-prompt-${promptTs}.md`);
+    const promptFrontmatter = `---\nproject: ${project}\ngenerated: ${new Date(promptTs).toISOString()}\ntype: analysis-prompt\nmodel: gemini\n---\n\n`;
+    writeFileSync(promptPath, promptFrontmatter + prompt, 'utf8');
     console.log(chalk.gray(`Prompt saved: ${promptPath}`));
 
     // Call Gemini via gemini CLI (reuse existing auth)
@@ -708,7 +746,7 @@ program
       analysis = JSON.parse(jsonMatch[0]);
     } catch {
       console.error(chalk.red('Could not parse JSON from response. Saving raw output.'));
-      const rawPath = join(__dirname, `reports/${project}-raw-${Date.now()}.txt`);
+      const rawPath = join(__dirname, `reports/${project}-raw-${Date.now()}.md`);
       writeFileSync(rawPath, result, 'utf8');
       process.exit(1);
     }
@@ -718,11 +756,12 @@ program
     writeFileSync(outPath, JSON.stringify(analysis, null, 2), 'utf8');
 
     // Save to DB (so HTML dashboard picks it up)
+    const analysisTs = Date.now();
     db.prepare(`
       INSERT INTO analyses (project, generated_at, model, keyword_gaps, long_tails, quick_wins, new_pages, content_gaps, positioning, technical_gaps, raw)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
-      project, Date.now(), 'gemini',
+      project, analysisTs, 'gemini',
       JSON.stringify(analysis.keyword_gaps || []),
       JSON.stringify(analysis.long_tails || []),
       JSON.stringify(analysis.quick_wins || []),
@@ -733,6 +772,10 @@ program
       result,
     );
 
+    // Upsert individual insights (Intelligence Ledger — accumulates across runs)
+    const analysisRowId = db.prepare('SELECT last_insert_rowid() as id').get().id;
+    upsertInsightsFromAnalysis(db, project, analysisRowId, analysis, analysisTs);
+
     // Print summary
     printAnalysisSummary(analysis, project);
 
@@ -869,7 +912,7 @@ Respond ONLY with a single valid JSON object matching this exact schema. No expl
       data = JSON.parse(jsonMatch[0]);
     } catch {
       console.error(chalk.red('Could not parse JSON from Gemini response.'));
-      const rawPath = join(__dirname, `reports/${project}-keywords-raw-${Date.now()}.txt`);
+      const rawPath = join(__dirname, `reports/${project}-keywords-raw-${Date.now()}.md`);
       writeFileSync(rawPath, result, 'utf8');
       console.error(chalk.gray(`Raw output saved: ${rawPath}`));
       process.exit(1);
@@ -933,6 +976,10 @@ Respond ONLY with a single valid JSON object matching this exact schema. No expl
       const outPath = join(__dirname, `reports/${project}-keywords-${Date.now()}.json`);
       writeFileSync(outPath, JSON.stringify(data, null, 2), 'utf8');
       console.log(chalk.bold.green(`✅ Report saved: ${outPath}\n`));
+
+      // Persist keyword inventor insights to Intelligence Ledger
+      const db = getDb();
+      upsertInsightsFromKeywords(db, project, data);
     }
   });
 
@@ -1183,6 +1230,7 @@ program
     }
 
     console.log(chalk.bold.cyan(`\n🔍 Cron run: crawling ${next.domain} [${next.role}] (project: ${next.project})\n`));
+    applyExtractionRuntimeConfig(loadConfig(next.project));
 
     const runStart = Date.now();
 
@@ -1683,7 +1731,9 @@ async function runAnalysis(project, db) {
     headingStructure: headings, context: config.context,
   });
 
-  writeFileSync(join(__dirname, `reports/${project}-prompt-${Date.now()}.txt`), prompt, 'utf8');
+  const promptTs2 = Date.now();
+  const promptFm2 = `---\nproject: ${project}\ngenerated: ${new Date(promptTs2).toISOString()}\ntype: analysis-prompt\nmodel: gemini\n---\n\n`;
+  writeFileSync(join(__dirname, `reports/${project}-prompt-${promptTs2}.md`), promptFm2 + prompt, 'utf8');
 
   const result = await callGemini(prompt);
   if (!result) { console.error(chalk.red('Gemini returned no response.')); process.exit(1); }
@@ -1695,11 +1745,12 @@ async function runAnalysis(project, db) {
     writeFileSync(outPath, JSON.stringify(analysis, null, 2), 'utf8');
 
     // Save to DB
+    const analysisTs2 = Date.now();
     db.prepare(`
       INSERT INTO analyses (project, generated_at, model, keyword_gaps, long_tails, quick_wins, new_pages, content_gaps, positioning, technical_gaps, raw)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
-      project, Date.now(), 'gemini',
+      project, analysisTs2, 'gemini',
       JSON.stringify(analysis.keyword_gaps || []),
       JSON.stringify(analysis.long_tails || []),
       JSON.stringify(analysis.quick_wins || []),
@@ -1710,6 +1761,10 @@ async function runAnalysis(project, db) {
       result,
     );
 
+    // Upsert individual insights (Intelligence Ledger)
+    const analysisRowId2 = db.prepare('SELECT last_insert_rowid() as id').get().id;
+    upsertInsightsFromAnalysis(db, project, analysisRowId2, analysis, analysisTs2);
+
     printAnalysisSummary(analysis, project);
     console.log(chalk.green(`\n✅ Analysis saved: ${outPath}`));
   } catch (err) {
@@ -1724,6 +1779,7 @@ program
   .description('Run AI extraction on all crawled-but-not-yet-extracted pages (requires Solo/Agency)')
   .action(async (project) => {
     if (!requirePro('extract')) return;
+    applyExtractionRuntimeConfig(loadConfig(project));
     const db = getDb();
 
     // Query pages that have body_text stored (from crawl) but no extraction yet
@@ -3808,6 +3864,145 @@ program
     writeOrPrintActionOutput(output, opts.output);
   });
 
+// ── AEO / AI CITABILITY AUDIT ────────────────────────────────────────────
+program
+  .command('aeo <project>')
+  .alias('citability')
+  .description('AI Citability Audit — score every page for how well AI assistants can cite it')
+  .option('--target-only', 'Only score target domain (skip competitors)')
+  .option('--save', 'Save report to reports/')
+  .action(async (project, opts) => {
+    if (!requirePro('aeo')) return;
+    const db = getDb();
+    const config = loadConfig(project);
+
+    printAttackHeader('🤖 AEO — AI Citability Audit', project);
+
+    const { runAeoAnalysis, persistAeoScores, upsertCitabilityInsights } = await import('./analyses/aeo/index.js');
+
+    const results = runAeoAnalysis(db, project, {
+      includeCompetitors: !opts.targetOnly,
+      log: (msg) => console.log(chalk.gray(msg)),
+    });
+
+    if (!results.target.length && !results.competitors.size) {
+      console.log(chalk.yellow('\n  ⚠️  No pages with body_text found.'));
+      console.log(chalk.gray('   Run: seo-intel crawl ' + project + '  (crawl stores body text since v1.1.6)\n'));
+      return;
+    }
+
+    // Persist scores
+    persistAeoScores(db, results);
+    upsertCitabilityInsights(db, project, results.target);
+
+    const { summary } = results;
+
+    // ── Summary ──
+    console.log('');
+    console.log(chalk.bold('  📊 Citability Summary'));
+    console.log('');
+
+    const scoreFmt = (s) => {
+      if (s >= 75) return chalk.bold.green(s + '/100');
+      if (s >= 55) return chalk.bold.yellow(s + '/100');
+      if (s >= 35) return chalk.hex('#ff8c00')(s + '/100');
+      return chalk.bold.red(s + '/100');
+    };
+
+    console.log(`    Target average:     ${scoreFmt(summary.avgTargetScore)}`);
+    if (summary.competitorPages > 0) {
+      console.log(`    Competitor average:  ${scoreFmt(summary.avgCompetitorScore)}`);
+      const delta = summary.scoreDelta;
+      const deltaStr = delta > 0 ? chalk.green(`+${delta}`) : delta < 0 ? chalk.red(`${delta}`) : chalk.gray('0');
+      console.log(`    Delta:              ${deltaStr}`);
+    }
+    console.log('');
+
+    // ── Tier breakdown ──
+    const { tierCounts } = summary;
+    console.log(`    ${chalk.green('●')} Excellent (75+):  ${tierCounts.excellent}`);
+    console.log(`    ${chalk.yellow('●')} Good (55-74):     ${tierCounts.good}`);
+    console.log(`    ${chalk.hex('#ff8c00')('●')} Needs work (35-54): ${tierCounts.needs_work}`);
+    console.log(`    ${chalk.red('●')} Poor (<35):        ${tierCounts.poor}`);
+    console.log('');
+
+    // ── Weakest signals ──
+    if (summary.weakestSignals.length) {
+      console.log(chalk.bold('  🔍 Weakest Signals (target average)'));
+      console.log('');
+      for (const s of summary.weakestSignals) {
+        const bar = '█'.repeat(Math.round(s.avg / 5)) + chalk.gray('░'.repeat(20 - Math.round(s.avg / 5)));
+        console.log(`    ${s.signal.padEnd(20)} ${bar} ${s.avg}/100`);
+      }
+      console.log('');
+    }
+
+    // ── Worst pages (actionable) ──
+    const worst = results.target.filter(r => r.score < 55).slice(0, 10);
+    if (worst.length) {
+      console.log(chalk.bold.red('  ⚡ Pages Needing Work'));
+      console.log('');
+      for (const p of worst) {
+        const path = p.url.replace(/https?:\/\/[^/]+/, '') || '/';
+        const weakest = Object.entries(p.breakdown)
+          .sort(([, a], [, b]) => a - b)
+          .slice(0, 2)
+          .map(([k]) => k.replace(/_/g, ' '));
+        console.log(`    ${scoreFmt(p.score)}  ${chalk.bold(path.slice(0, 50))}`);
+        console.log(chalk.gray(`           Weak: ${weakest.join(', ')}`));
+      }
+      console.log('');
+    }
+
+    // ── Best pages ──
+    const best = results.target.filter(r => r.score >= 55).slice(-5).reverse();
+    if (best.length) {
+      console.log(chalk.bold.green('  ✨ Top Citable Pages'));
+      console.log('');
+      for (const p of best) {
+        const path = p.url.replace(/https?:\/\/[^/]+/, '') || '/';
+        console.log(`    ${scoreFmt(p.score)}  ${chalk.bold(path.slice(0, 50))}  ${chalk.gray(p.aiIntents.join(', '))}`);
+      }
+      console.log('');
+    }
+
+    // ── Actions ──
+    console.log(chalk.bold.green('  💡 Actions:'));
+    if (tierCounts.poor > 0) {
+      console.log(chalk.green(`     1. Fix ${tierCounts.poor} poor-scoring pages — add structured headings, Q&A format, entity depth`));
+    }
+    if (summary.weakestSignals.length && summary.weakestSignals[0].avg < 40) {
+      console.log(chalk.green(`     2. Site-wide weakness: "${summary.weakestSignals[0].signal}" — systematically improve across all pages`));
+    }
+    if (summary.scoreDelta < 0) {
+      console.log(chalk.green(`     3. Competitors are ${Math.abs(summary.scoreDelta)} points ahead — prioritise top-traffic pages first`));
+    }
+    console.log('');
+
+    // ── Regenerate dashboard ──
+    try {
+      const configs = loadAllConfigs();
+      generateMultiDashboard(db, configs);
+      console.log(chalk.green('  ✅ Dashboard updated with AI Citability card\n'));
+    } catch (e) {
+      console.log(chalk.gray(`  (Dashboard not updated: ${e.message})\n`));
+    }
+
+    // ── Save report ──
+    if (opts.save) {
+      let md = `---\ntype: aeo-report\nproject: ${project}\ndate: ${new Date().toISOString()}\n---\n# AEO Citability Report — ${config.target.domain}\n\n`;
+      md += `## Summary\n- Target avg: ${summary.avgTargetScore}/100\n- Competitor avg: ${summary.avgCompetitorScore}/100\n- Delta: ${summary.scoreDelta}\n\n`;
+      md += `## Tier Breakdown\n- Excellent: ${tierCounts.excellent}\n- Good: ${tierCounts.good}\n- Needs work: ${tierCounts.needs_work}\n- Poor: ${tierCounts.poor}\n\n`;
+      md += `## Pages Needing Work\n`;
+      for (const p of worst) {
+        md += `- **${p.url}** — ${p.score}/100 (${p.tier})\n`;
+      }
+      const outPath = join(__dirname, `reports/${project}-aeo-${Date.now()}.md`);
+      writeFileSync(outPath, md, 'utf8');
+      console.log(chalk.bold.green(`  ✅ Report saved: ${outPath}\n`));
+    }
+  });
+
 // ── GUIDE (Coach-style chapter map) ──────────────────────────────────────
 program
   .command('guide')

package/db/db.js

@@ -24,15 +24,191 @@ export function getDb(dbPath = './seo-intel.db') {
   try { _db.exec('ALTER TABLE pages ADD COLUMN title TEXT'); } catch { /* already exists */ }
   try { _db.exec('ALTER TABLE pages ADD COLUMN meta_desc TEXT'); } catch { /* already exists */ }
   try { _db.exec('ALTER TABLE pages ADD COLUMN body_text TEXT'); } catch { /* already exists */ }
+  try { _db.exec('ALTER TABLE analyses ADD COLUMN technical_gaps TEXT'); } catch { /* already exists */ }
 
   // Backfill first_seen_at from crawled_at for existing rows
   _db.exec('UPDATE pages SET first_seen_at = crawled_at WHERE first_seen_at IS NULL');
 
-  // page_schemas table is created by schema.sql — no migration needed (new table)
+  // Migrate existing analyses → insights (one-time)
+  _migrateAnalysesToInsights(_db);
 
   return _db;
 }
 
+// ── Insight fingerprinting ──────────────────────────────────────────────────
+
+function _insightFingerprint(type, item) {
+  let raw;
+  switch (type) {
+    case 'keyword_gap':       raw = item.keyword || ''; break;
+    case 'long_tail':         raw = item.phrase || ''; break;
+    case 'quick_win':         raw = `${item.page || ''}::${item.issue || ''}`; break;
+    case 'new_page':          raw = item.target_keyword || item.title || ''; break;
+    case 'content_gap':       raw = item.topic || ''; break;
+    case 'technical_gap':     raw = item.gap || ''; break;
+    case 'positioning':       raw = 'positioning'; break;
+    case 'keyword_inventor':  raw = item.phrase || ''; break;
+    case 'citability_gap':    raw = item.url || ''; break;
+    default:                  raw = JSON.stringify(item);
+  }
+  return raw.toLowerCase().replace(/[^a-z0-9\s]/g, '').replace(/\s+/g, ' ').trim();
+}
+
+// ── Migrate all historical analyses into insights ───────────────────────────
+
+function _migrateAnalysesToInsights(db) {
+  const count = db.prepare('SELECT COUNT(*) as n FROM insights').get().n;
+  if (count > 0) return; // already migrated
+
+  const rows = db.prepare('SELECT * FROM analyses ORDER BY generated_at ASC').all();
+  if (!rows.length) return;
+
+  const safeJsonParse = (s) => { try { return JSON.parse(s); } catch { return null; } };
+
+  const upsertStmt = db.prepare(`
+    INSERT INTO insights (project, type, status, fingerprint, first_seen, last_seen, source_analysis_id, data)
+    VALUES (?, ?, 'active', ?, ?, ?, ?, ?)
+    ON CONFLICT(project, type, fingerprint) DO UPDATE SET
+      last_seen = excluded.last_seen,
+      data = excluded.data
+  `);
+
+  db.exec('BEGIN');
+  try {
+    for (const row of rows) {
+      const ts = row.generated_at;
+      const fields = [
+        ['keyword_gap',   safeJsonParse(row.keyword_gaps)],
+        ['long_tail',     safeJsonParse(row.long_tails)],
+        ['quick_win',     safeJsonParse(row.quick_wins)],
+        ['new_page',      safeJsonParse(row.new_pages)],
+        ['content_gap',   safeJsonParse(row.content_gaps)],
+        ['technical_gap', safeJsonParse(row.technical_gaps)],
+      ];
+      for (const [type, items] of fields) {
+        if (!Array.isArray(items)) continue;
+        for (const item of items) {
+          const fp = _insightFingerprint(type, item);
+          if (!fp) continue;
+          upsertStmt.run(row.project, type, fp, ts, ts, row.id, JSON.stringify(item));
+        }
+      }
+      // positioning is a singleton object, not an array
+      const pos = safeJsonParse(row.positioning);
+      if (pos && typeof pos === 'object' && Object.keys(pos).length) {
+        const fp = _insightFingerprint('positioning', pos);
+        upsertStmt.run(row.project, 'positioning', fp, ts, ts, row.id, JSON.stringify(pos));
+      }
+    }
+    db.exec('COMMIT');
+  } catch (e) {
+    db.exec('ROLLBACK');
+    console.error('[db] insights migration failed:', e.message);
+  }
+}
+
+// ── Insight upsert (called after each analyze/keywords run) ─────────────────
+
+export function upsertInsightsFromAnalysis(db, project, analysisId, analysis, timestamp) {
+  const upsertStmt = db.prepare(`
+    INSERT INTO insights (project, type, status, fingerprint, first_seen, last_seen, source_analysis_id, data)
+    VALUES (?, ?, 'active', ?, ?, ?, ?, ?)
+    ON CONFLICT(project, type, fingerprint) DO UPDATE SET
+      last_seen = excluded.last_seen,
+      data = excluded.data
+  `);
+
+  const ts = timestamp || Date.now();
+  db.exec('BEGIN');
+  try {
+    const fields = [
+      ['keyword_gap',   analysis.keyword_gaps],
+      ['long_tail',     analysis.long_tails],
+      ['quick_win',     analysis.quick_wins],
+      ['new_page',      analysis.new_pages],
+      ['content_gap',   analysis.content_gaps],
+      ['technical_gap', analysis.technical_gaps],
+    ];
+    for (const [type, items] of fields) {
+      if (!Array.isArray(items)) continue;
+      for (const item of items) {
+        const fp = _insightFingerprint(type, item);
+        if (!fp) continue;
+        upsertStmt.run(project, type, fp, ts, ts, analysisId, JSON.stringify(item));
+      }
+    }
+    if (analysis.positioning && typeof analysis.positioning === 'object') {
+      const fp = _insightFingerprint('positioning', analysis.positioning);
+      upsertStmt.run(project, 'positioning', fp, ts, ts, analysisId, JSON.stringify(analysis.positioning));
+    }
+    db.exec('COMMIT');
+  } catch (e) {
+    db.exec('ROLLBACK');
+    console.error('[db] insight upsert failed:', e.message);
+  }
+}
+
+export function upsertInsightsFromKeywords(db, project, keywordsReport) {
+  const upsertStmt = db.prepare(`
+    INSERT INTO insights (project, type, status, fingerprint, first_seen, last_seen, source_analysis_id, data)
+    VALUES (?, 'keyword_inventor', 'active', ?, ?, ?, NULL, ?)
+    ON CONFLICT(project, type, fingerprint) DO UPDATE SET
+      last_seen = excluded.last_seen,
+      data = excluded.data
+  `);
+
+  const ts = Date.now();
+  const allClusters = keywordsReport.keyword_clusters || [];
+  const allKws = allClusters.flatMap(c => (c.keywords || []).map(k => ({ ...k, cluster: c.topic })));
+
+  db.exec('BEGIN');
+  try {
+    for (const kw of allKws) {
+      const fp = _insightFingerprint('keyword_inventor', kw);
+      if (!fp) continue;
+      upsertStmt.run(project, fp, ts, ts, JSON.stringify(kw));
+    }
+    db.exec('COMMIT');
+  } catch (e) {
+    db.exec('ROLLBACK');
+    console.error('[db] keyword insight upsert failed:', e.message);
+  }
+}
+
+// ── Read active insights (accumulated across all runs) ──────────────────────
+
+export function getActiveInsights(db, project) {
+  const rows = db.prepare(
+    `SELECT * FROM insights WHERE project = ? AND status = 'active' ORDER BY type, last_seen DESC`
+  ).all(project);
+
+  const grouped = {};
+  for (const row of rows) {
+    if (!grouped[row.type]) grouped[row.type] = [];
+    const parsed = JSON.parse(row.data);
+    parsed._insight_id = row.id;
+    parsed._first_seen = row.first_seen;
+    parsed._last_seen = row.last_seen;
+    grouped[row.type].push(parsed);
+  }
+
+  return {
+    keyword_gaps: grouped.keyword_gap || [],
+    long_tails: grouped.long_tail || [],
+    quick_wins: grouped.quick_win || [],
+    new_pages: grouped.new_page || [],
+    content_gaps: grouped.content_gap || [],
+    technical_gaps: grouped.technical_gap || [],
+    positioning: grouped.positioning?.[0] || null,
+    keyword_inventor: grouped.keyword_inventor || [],
+    generated_at: rows.length ? Math.max(...rows.map(r => r.last_seen)) : null,
+  };
+}
+
+export function updateInsightStatus(db, id, status) {
+  db.prepare('UPDATE insights SET status = ? WHERE id = ?').run(status, id);
+}
+
 export function upsertDomain(db, { domain, project, role }) {
   const now = Date.now();
   return db.prepare(`
@@ -337,6 +513,7 @@ export function pruneStaleDomains(db, project, configDomains) {
         db.prepare(`DELETE FROM page_schemas WHERE page_id IN (${placeholders})`).run(...pageIds);
         db.prepare(`DELETE FROM extractions WHERE page_id IN (${placeholders})`).run(...pageIds);
         db.prepare(`DELETE FROM keywords WHERE page_id IN (${placeholders})`).run(...pageIds);
+        try { db.prepare(`DELETE FROM citability_scores WHERE page_id IN (${placeholders})`).run(...pageIds); } catch { /* table may not exist */ }
         db.prepare(`DELETE FROM pages WHERE domain_id = ?`).run(id);
       }
 

package/db/schema.sql

@@ -82,19 +82,37 @@ CREATE TABLE IF NOT EXISTS technical (
 );
 
 CREATE TABLE IF NOT EXISTS analyses (
-  id            INTEGER PRIMARY KEY AUTOINCREMENT,
-  project       TEXT NOT NULL,
-  generated_at  INTEGER NOT NULL,
-  model         TEXT NOT NULL,
-  keyword_gaps  TEXT,  -- JSON array
-  long_tails    TEXT,  -- JSON array
-  quick_wins    TEXT,  -- JSON array
-  new_pages     TEXT,  -- JSON array
-  content_gaps  TEXT,  -- JSON array
-  positioning   TEXT,
-  raw           TEXT   -- full model response
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  project         TEXT NOT NULL,
+  generated_at    INTEGER NOT NULL,
+  model           TEXT NOT NULL,
+  keyword_gaps    TEXT,  -- JSON array
+  long_tails      TEXT,  -- JSON array
+  quick_wins      TEXT,  -- JSON array
+  new_pages       TEXT,  -- JSON array
+  content_gaps    TEXT,  -- JSON array
+  positioning     TEXT,
+  technical_gaps  TEXT,  -- JSON array
+  raw             TEXT   -- full model response
+);
+
+-- Intelligence Ledger: individual insights accumulated across analysis runs
+CREATE TABLE IF NOT EXISTS insights (
+  id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+  project             TEXT NOT NULL,
+  type                TEXT NOT NULL,   -- keyword_gap | long_tail | quick_win | new_page | content_gap | technical_gap | positioning | keyword_inventor
+  status              TEXT NOT NULL DEFAULT 'active',  -- active | done | dismissed
+  fingerprint         TEXT NOT NULL,   -- normalised dedup key
+  first_seen          INTEGER NOT NULL, -- epoch ms
+  last_seen           INTEGER NOT NULL, -- epoch ms
+  source_analysis_id  INTEGER,         -- FK to analyses.id (NULL for keyword_inventor)
+  data                TEXT NOT NULL,   -- JSON blob for the individual item
+  UNIQUE(project, type, fingerprint)
 );
 
+CREATE INDEX IF NOT EXISTS idx_insights_project_status ON insights(project, status);
+CREATE INDEX IF NOT EXISTS idx_insights_project_type ON insights(project, type);
+
 CREATE TABLE IF NOT EXISTS page_schemas (
   id          INTEGER PRIMARY KEY AUTOINCREMENT,
   page_id     INTEGER NOT NULL REFERENCES pages(id),
@@ -158,6 +176,24 @@ CREATE TABLE IF NOT EXISTS template_samples (
 CREATE INDEX IF NOT EXISTS idx_template_groups_project ON template_groups(project);
 CREATE INDEX IF NOT EXISTS idx_template_samples_group ON template_samples(group_id);
 
+-- AEO / AI Citability scores (one per page, re-scorable)
+CREATE TABLE IF NOT EXISTS citability_scores (
+  id                INTEGER PRIMARY KEY AUTOINCREMENT,
+  page_id           INTEGER UNIQUE NOT NULL REFERENCES pages(id),
+  score             INTEGER NOT NULL,           -- composite 0-100
+  entity_authority  INTEGER NOT NULL DEFAULT 0,
+  structured_claims INTEGER NOT NULL DEFAULT 0,
+  answer_density    INTEGER NOT NULL DEFAULT 0,
+  qa_proximity      INTEGER NOT NULL DEFAULT 0,
+  freshness         INTEGER NOT NULL DEFAULT 0,
+  schema_coverage   INTEGER NOT NULL DEFAULT 0,
+  ai_intents        TEXT,                       -- JSON array: synthesis, decision_support, etc.
+  tier              TEXT NOT NULL DEFAULT 'poor', -- excellent | good | needs_work | poor
+  scored_at         INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_citability_page ON citability_scores(page_id);
+
 -- Indexes
 CREATE INDEX IF NOT EXISTS idx_pages_domain ON pages(domain_id);
 CREATE INDEX IF NOT EXISTS idx_keywords_page ON keywords(page_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seo-intel",
-  "version": "1.1.10",
+  "version": "1.2.0",
   "description": "Local Ahrefs-style SEO competitor intelligence. Crawl → SQLite → cloud analysis.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/reports/generate-html.js

@@ -18,6 +18,8 @@ import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { loadGscData } from './gsc-loader.js';
 import { isPro } from '../lib/license.js';
+import { getActiveInsights } from '../db/db.js';
+import { getCitabilityScores } from '../analyses/aeo/index.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -69,7 +71,7 @@ function gatherProjectData(db, project, config) {
   const domains = getDomainStats(db, project, config);
   const keywords = getTopKeywords(db, project);
   const keywordGaps = getKeywordGaps(db, project);
-  const latestAnalysis = getLatestAnalysis(db, project);
+  const latestAnalysis = getActiveInsights(db, project);
   const keywordHeatmap = getKeywordHeatmapData(db, project, allDomains, latestAnalysis);
   const technicalScores = getTechnicalScores(db, project, config);
   const internalLinks = getInternalLinkStats(db, project);
@@ -102,6 +104,10 @@ function gatherProjectData(db, project, config) {
   // Keyword Inventor data
   const keywordsReport = getLatestKeywordsReport(project);
 
+  // AEO / AI Citability scores
+  let citabilityData = null;
+  try { citabilityData = getCitabilityScores(db, project); } catch { /* table may not exist yet */ }
+
   // Extraction status
   const extractionStatus = getExtractionStatus(db, project, config);
 
@@ -125,7 +131,7 @@ function gatherProjectData(db, project, config) {
     ctaLandscape, entityTopicMap, schemaBreakdown,
     gravityMap, contentTerrain, keywordVenn, performanceBubbles,
     headingFlow, territoryTreemap, topicClusters, linkDna, linkRadarPulse,
-    keywordsReport, extractionStatus, gscData, domainArch, gscInsights,
+    keywordsReport, extractionStatus, gscData, domainArch, gscInsights, citabilityData,
   };
 
   // Rollback the owned→target merge so the actual DB is unchanged
@@ -188,7 +194,7 @@ function buildHtmlTemplate(data, opts = {}) {
     ctaLandscape, entityTopicMap, schemaBreakdown,
     gravityMap, contentTerrain, keywordVenn, performanceBubbles,
     headingFlow, territoryTreemap, topicClusters, linkDna, linkRadarPulse,
-    keywordsReport, extractionStatus, gscData, domainArch, gscInsights,
+    keywordsReport, extractionStatus, gscData, domainArch, gscInsights, citabilityData,
   } = data;
 
   const totalPages = domains.reduce((sum, d) => sum + d.page_count, 0);
@@ -622,6 +628,21 @@ function buildHtmlTemplate(data, opts = {}) {
     .badge-target { background: rgba(232,213,163,0.15); color: var(--accent-gold); }
     .badge-competitor { background: rgba(124,109,235,0.15); color: var(--accent-purple); }
 
+    /* ─── Insight Actions (Intelligence Ledger) ──────────────────────────── */
+    .insight-action { display: flex; gap: 4px; }
+    .insight-btn {
+      width: 22px; height: 22px; border-radius: 50%; border: 1px solid var(--border-card);
+      background: transparent; color: var(--text-muted); cursor: pointer;
+      display: flex; align-items: center; justify-content: center; font-size: 0.6rem;
+      transition: all 0.2s ease; padding: 0;
+    }
+    .insight-btn:hover { border-color: var(--accent-gold); color: var(--accent-gold); }
+    .insight-btn.btn-done:hover { border-color: var(--color-success); color: var(--color-success); }
+    .insight-btn.btn-dismiss:hover { border-color: var(--color-danger); color: var(--color-danger); }
+    tr.insight-done { opacity: 0.3; text-decoration: line-through; }
+    .new-page-card.insight-done, .positioning-card.insight-done { opacity: 0.3; }
+    .insight-age { font-size: 0.65rem; color: var(--text-muted); white-space: nowrap; }
+
     /* ─── Heatmap Dots ───────────────────────────────────────────────────── */
     .dot {
       display: inline-block;
@@ -2722,13 +2743,14 @@ function buildHtmlTemplate(data, opts = {}) {
       <h2><span class="icon"><i class="fa-solid fa-wrench"></i></span> Technical SEO Gaps</h2>
       <div class="analysis-table-wrap">
         <table class="analysis-table">
-          <thead><tr><th>Gap</th><th>Competitors with it</th><th>Fix</th></tr></thead>
+          <thead><tr><th>Gap</th><th>Competitors with it</th><th>Fix</th><th></th></tr></thead>
           <tbody>
             ${(latestAnalysis.technical_gaps).map(tg => `
-            <tr>
+            <tr data-insight-id="${tg._insight_id || ''}">
               <td><strong>${escapeHtml(tg.gap || '—')}</strong></td>
               <td>${(tg.competitors_with_it || []).map(d => `<span class="comp-tag">${escapeHtml(d)}</span>`).join(' ') || '—'}</td>
               <td>${escapeHtml(tg.fix || '—')}</td>
+              <td class="insight-action">${tg._insight_id ? `<button class="insight-btn btn-done" onclick="insightAction(this,'done')" title="Mark done"><i class="fa-solid fa-check"></i></button><button class="insight-btn btn-dismiss" onclick="insightAction(this,'dismissed')" title="Dismiss"><i class="fa-solid fa-xmark"></i></button>` : ''}</td>
             </tr>`).join('')}
           </tbody>
         </table>
@@ -2749,14 +2771,15 @@ function buildHtmlTemplate(data, opts = {}) {
       <h2><span class="icon"><i class="fa-solid fa-bolt"></i></span> Quick Wins</h2>
       <div class="analysis-table-wrap">
         <table class="analysis-table">
-          <thead><tr><th>Page</th><th>Issue</th><th>Fix</th><th>Impact</th></tr></thead>
+          <thead><tr><th>Page</th><th>Issue</th><th>Fix</th><th>Impact</th><th></th></tr></thead>
           <tbody>
             ${(latestAnalysis.quick_wins).map(w => `
-            <tr>
+            <tr data-insight-id="${w._insight_id || ''}">
               <td class="mono">${escapeHtml(w.page || '—')}</td>
               <td>${escapeHtml(w.issue || '—')}</td>
               <td>${escapeHtml(w.fix || '—')}</td>
               <td><span class="badge badge-${w.impact || 'medium'}">${w.impact || '—'}</span></td>
+              <td class="insight-action">${w._insight_id ? `<button class="insight-btn btn-done" onclick="insightAction(this,'done')" title="Mark done"><i class="fa-solid fa-check"></i></button><button class="insight-btn btn-dismiss" onclick="insightAction(this,'dismissed')" title="Dismiss"><i class="fa-solid fa-xmark"></i></button>` : ''}</td>
             </tr>`).join('')}
           </tbody>
         </table>
@@ -2770,10 +2793,11 @@ function buildHtmlTemplate(data, opts = {}) {
       <h2><span class="icon"><i class="fa-solid fa-file-circle-plus"></i></span> New Pages to Create</h2>
       <div class="new-pages-grid" style="grid-template-columns: 1fr;">
         ${(latestAnalysis.new_pages).map(np => `
-        <div class="new-page-card priority-${np.priority || 'medium'}">
+        <div class="new-page-card priority-${np.priority || 'medium'}" data-insight-id="${np._insight_id || ''}">
           <div class="new-page-header">
             <span class="new-page-title">${escapeHtml(np.title || np.slug || 'Untitled')}</span>
             <span class="badge badge-${np.priority || 'medium'}">${np.priority || '—'}</span>
+            ${np._insight_id ? `<span class="insight-action" style="margin-left:auto;"><button class="insight-btn btn-done" onclick="insightAction(this,'done')" title="Mark done"><i class="fa-solid fa-check"></i></button><button class="insight-btn btn-dismiss" onclick="insightAction(this,'dismissed')" title="Dismiss"><i class="fa-solid fa-xmark"></i></button></span>` : ''}
           </div>
           <div class="new-page-keyword"><i class="fa-solid fa-key" style="font-size:0.7rem;opacity:0.5;margin-right:4px;"></i>${escapeHtml(np.target_keyword || '—')}</div>
           <div class="new-page-angle">${escapeHtml(np.content_angle || np.why || '—')}</div>
@@ -2821,11 +2845,12 @@ function buildHtmlTemplate(data, opts = {}) {
       <h2><span class="icon"><i class="fa-solid fa-magnifying-glass-minus"></i></span> Content Gaps</h2>
       <div class="insights-grid">
         ${(latestAnalysis.content_gaps).map(gap => `
-        <div class="insight-card medium">
+        <div class="insight-card medium" data-insight-id="${gap._insight_id || ''}">
           <div class="insight-header">
             <span class="insight-icon"><i class="fa-solid fa-clipboard" style="font-size:0.8rem;"></i></span>
             <span class="insight-title">${escapeHtml(gap.topic || gap.suggested_title || 'Gap')}</span>
             <span class="badge badge-medium">${gap.format || 'content'}</span>
+            ${gap._insight_id ? `<span class="insight-action" style="margin-left:auto;"><button class="insight-btn btn-done" onclick="insightAction(this,'done')" title="Done"><i class="fa-solid fa-check"></i></button><button class="insight-btn btn-dismiss" onclick="insightAction(this,'dismissed')" title="Dismiss"><i class="fa-solid fa-xmark"></i></button></span>` : ''}
           </div>
           <div class="insight-desc">${escapeHtml(gap.why_it_matters || '')}</div>
           ${gap.covered_by?.length ? `<div class="covered-by">Covered by: ${gap.covered_by.map(d => `<span class="comp-tag">${escapeHtml(d)}</span>`).join(' ')}</div>` : ''}
@@ -2864,33 +2889,6 @@ function buildHtmlTemplate(data, opts = {}) {
     </div>
     ` : ''}
 
-    <!-- ═══ LONG-TAIL OPPORTUNITIES ═══ -->
-    ${pro && latestAnalysis?.long_tails?.length ? `
-    <div class="card full-width" id="long-tails">
-      <h2><span class="icon"><i class="fa-solid fa-binoculars"></i></span> Long-tail Opportunities</h2>
-      <div class="analysis-table-wrap">
-        <table class="analysis-table">
-          <thead><tr><th>Phrase</th><th>Intent</th><th>Type</th><th>Best Placement</th><th>2nd</th><th>Priority</th></tr></thead>
-          <tbody>
-            ${(latestAnalysis.long_tails).map(lt => {
-              const p1 = lt.placement?.[0];
-              const p2 = lt.placement?.[1];
-              return `
-            <tr>
-              <td class="phrase-cell">"${escapeHtml(lt.phrase || '—')}"</td>
-              <td>${escapeHtml(lt.intent || '—')}</td>
-              <td><span class="type-tag">${escapeHtml(lt.page_type || '—')}</span></td>
-              <td class="placement-cell">${p1 ? `<span class="prop-tag prop-${p1.property}">${escapeHtml(p1.property)}</span> <span class="placement-url">${escapeHtml(p1.url || '')}</span>` : '—'}</td>
-              <td class="placement-cell">${p2 ? `<span class="prop-tag prop-${p2.property}">${escapeHtml(p2.property)}</span>` : '—'}</td>
-              <td><span class="badge badge-${lt.priority || 'medium'}">${lt.priority || '—'}</span></td>
-            </tr>`;
-            }).join('')}
-          </tbody>
-        </table>
-      </div>
-    </div>
-    ` : ''}
-
     <!-- ═══ SHALLOW CHAMPIONS ═══ -->
     ${pro ? `
     <div class="card" id="shallow-champions">
@@ -3150,6 +3148,37 @@ function buildHtmlTemplate(data, opts = {}) {
       <div class="section-divider-line"></div>
     </div>` : ''}
 
+    <!-- ═══ AEO / AI CITABILITY AUDIT ═══ -->
+    ${pro && citabilityData?.length ? buildAeoCard(citabilityData, escapeHtml) : ''}
+
+    <!-- ═══ LONG-TAIL OPPORTUNITIES ═══ -->
+    ${pro && latestAnalysis?.long_tails?.length ? `
+    <div class="card full-width" id="long-tails">
+      <h2><span class="icon"><i class="fa-solid fa-binoculars"></i></span> Long-tail Opportunities</h2>
+      <div class="analysis-table-wrap">
+        <table class="analysis-table">
+          <thead><tr><th>Phrase</th><th>Intent</th><th>Type</th><th>Best Placement</th><th>2nd</th><th>Priority</th><th></th></tr></thead>
+          <tbody>
+            ${(latestAnalysis.long_tails).map(lt => {
+              const p1 = lt.placement?.[0];
+              const p2 = lt.placement?.[1];
+              return `
+            <tr data-insight-id="${lt._insight_id || ''}">
+              <td class="phrase-cell">"${escapeHtml(lt.phrase || '—')}"</td>
+              <td>${escapeHtml(lt.intent || '—')}</td>
+              <td><span class="type-tag">${escapeHtml(lt.page_type || '—')}</span></td>
+              <td class="placement-cell">${p1 ? `<span class="prop-tag prop-${p1.property}">${escapeHtml(p1.property)}</span> <span class="placement-url">${escapeHtml(p1.url || '')}</span>` : '—'}</td>
+              <td class="placement-cell">${p2 ? `<span class="prop-tag prop-${p2.property}">${escapeHtml(p2.property)}</span>` : '—'}</td>
+              <td><span class="badge badge-${lt.priority || 'medium'}">${lt.priority || '—'}</span></td>
+              <td class="insight-action">${lt._insight_id ? `<button class="insight-btn btn-done" onclick="insightAction(this,'done')" title="Mark done"><i class="fa-solid fa-check"></i></button><button class="insight-btn btn-dismiss" onclick="insightAction(this,'dismissed')" title="Dismiss"><i class="fa-solid fa-xmark"></i></button>` : ''}</td>
+            </tr>`;
+            }).join('')}
+          </tbody>
+        </table>
+      </div>
+    </div>
+    ` : ''}
+
     <!-- ═══ KEYWORD INVENTOR ═══ -->
     ${pro && keywordsReport ? (() => {
       const allClusters = keywordsReport.keyword_clusters || [];
@@ -3243,6 +3272,24 @@ function buildHtmlTemplate(data, opts = {}) {
   </div>
 
   <div class="timestamp">Generated: ${new Date().toISOString()} | SEO Intel Dashboard v3</div>
+  <script>
+    async function insightAction(btn, status) {
+      const row = btn.closest('[data-insight-id]');
+      const id = row?.dataset?.insightId;
+      if (!id) return;
+      try {
+        const res = await fetch('/api/insights/' + id + '/status', {
+          method: 'POST',
+          headers: {'Content-Type': 'application/json'},
+          body: JSON.stringify({ status })
+        });
+        if (res.ok) {
+          row.classList.add('insight-done');
+          setTimeout(() => { row.style.display = 'none'; }, 600);
+        }
+      } catch(e) { console.warn('Insight update failed:', e); }
+    }
+  </script>
   </div><!-- /.project-panel -->`;
 
   // ── panelOnly mode: return just the project panel (for multi-project) ──
@@ -4925,6 +4972,103 @@ function buildMultiHtmlTemplate(allProjectData) {
 </html>`;
 }
 
+// ─── AEO Card Builder ────────────────────────────────────────────────────────
+
+function buildAeoCard(citabilityData, escapeHtml) {
+  const targetScores = citabilityData.filter(s => s.role === 'target' || s.role === 'owned');
+  const compScores = citabilityData.filter(s => s.role === 'competitor');
+  if (!targetScores.length) return '';
+
+  const avgTarget = Math.round(targetScores.reduce((a, s) => a + s.score, 0) / targetScores.length);
+  const avgComp = compScores.length ? Math.round(compScores.reduce((a, s) => a + s.score, 0) / compScores.length) : null;
+  const delta = avgComp !== null ? avgTarget - avgComp : null;
+
+  const tierCounts = { excellent: 0, good: 0, needs_work: 0, poor: 0 };
+  for (const s of targetScores) tierCounts[s.tier]++;
+
+  const signals = ['entity_authority', 'structured_claims', 'answer_density', 'qa_proximity', 'freshness', 'schema_coverage'];
+  const signalAvgs = signals.map(sig => ({
+    label: sig.replace(/_/g, ' '),
+    avg: Math.round(targetScores.reduce((a, s) => a + (s[sig] || 0), 0) / targetScores.length),
+  }));
+
+  const scoreColor = (s) => s >= 75 ? '#4ade80' : s >= 55 ? '#facc15' : s >= 35 ? '#ff8c00' : '#ef4444';
+
+  // Page rows (worst first, limit 25)
+  const pageRows = targetScores
+    .sort((a, b) => a.score - b.score)
+    .slice(0, 25)
+    .map(s => {
+      let path;
+      try { path = new URL(s.url).pathname; } catch { path = s.url; }
+      let intents = [];
+      try { intents = JSON.parse(s.ai_intents || '[]'); } catch { /* ok */ }
+      const weakest = signals
+        .map(sig => ({ sig: sig.replace(/_/g, ' '), val: s[sig] || 0 }))
+        .sort((a, b) => a.val - b.val)
+        .slice(0, 2);
+      const tierBadge = s.tier === 'excellent' ? 'high' : s.tier === 'poor' ? 'low' : 'medium';
+      return `
+          <tr>
+            <td><span style="display:inline-block;width:8px;height:8px;border-radius:50%;background:${scoreColor(s.score)};margin-right:6px;"></span><strong>${s.score}</strong></td>
+            <td class="phrase-cell" title="${escapeHtml(s.url)}">${escapeHtml(path.slice(0, 55))}</td>
+            <td>${escapeHtml((s.title || '').slice(0, 40) || '—')}</td>
+            <td><span class="badge badge-${tierBadge}">${s.tier.replace('_', ' ')}</span></td>
+            <td style="font-size:0.75rem;color:var(--text-muted)">${intents.map(i => i.replace('_', ' ')).join(', ')}</td>
+            <td style="font-size:0.75rem;color:var(--text-muted)">${weakest.map(w => w.sig).join(', ')}</td>
+          </tr>`;
+    }).join('');
+
+  const signalBars = signalAvgs.map(s => `
+          <div style="display:flex;align-items:center;gap:8px;margin-bottom:6px;">
+            <span style="width:130px;font-size:0.78rem;color:var(--text-secondary);text-transform:capitalize;">${s.label}</span>
+            <div style="flex:1;background:var(--card-bg);border-radius:4px;height:14px;overflow:hidden;">
+              <div style="width:${s.avg}%;height:100%;background:${scoreColor(s.avg)};border-radius:4px;transition:width .5s;"></div>
+            </div>
+            <span style="font-size:0.75rem;color:var(--text-muted);width:35px;text-align:right;">${s.avg}</span>
+          </div>`).join('');
+
+  let compStatHtml = '';
+  if (avgComp !== null) {
+    compStatHtml += `<div class="ki-stat"><span class="ki-stat-number" style="color:${scoreColor(avgComp)}">${avgComp}</span><span class="ki-stat-label">Competitor Avg</span></div>`;
+  }
+  if (delta !== null) {
+    compStatHtml += `<div class="ki-stat"><span class="ki-stat-number" style="color:${delta >= 0 ? '#4ade80' : '#ef4444'}">${delta > 0 ? '+' : ''}${delta}</span><span class="ki-stat-label">Delta</span></div>`;
+  }
+
+  return `
+    <div class="card full-width" id="aeo-citability">
+      <h2><span class="icon"><i class="fa-solid fa-robot"></i></span> AI Citability Audit</h2>
+      <div class="ki-stat-bar">
+        <div class="ki-stat"><span class="ki-stat-number" style="color:${scoreColor(avgTarget)}">${avgTarget}</span><span class="ki-stat-label">Target Avg</span></div>
+        ${compStatHtml}
+        <div class="ki-stat"><span class="ki-stat-number" style="color:#4ade80">${tierCounts.excellent}</span><span class="ki-stat-label">Excellent</span></div>
+        <div class="ki-stat"><span class="ki-stat-number" style="color:#facc15">${tierCounts.good}</span><span class="ki-stat-label">Good</span></div>
+        <div class="ki-stat"><span class="ki-stat-number" style="color:#ff8c00">${tierCounts.needs_work}</span><span class="ki-stat-label">Needs Work</span></div>
+        <div class="ki-stat"><span class="ki-stat-number" style="color:#ef4444">${tierCounts.poor}</span><span class="ki-stat-label">Poor</span></div>
+      </div>
+
+      <div style="display:flex;gap:2rem;margin:1.5rem 0;flex-wrap:wrap;">
+        <div style="flex:1;min-width:300px;">
+          <h3 style="font-size:0.85rem;color:var(--text-muted);text-transform:uppercase;letter-spacing:.06em;margin-bottom:.8rem;">
+            <i class="fa-solid fa-signal" style="font-size:0.7rem;margin-right:3px;"></i> Signal Strength
+          </h3>
+          ${signalBars}
+        </div>
+      </div>
+
+      <h3 style="font-size:0.85rem;color:var(--text-muted);text-transform:uppercase;letter-spacing:.06em;margin-bottom:.6rem;margin-top:1rem;">
+        <i class="fa-solid fa-list-ol" style="font-size:0.7rem;margin-right:3px;"></i> Page Scores (worst first)
+      </h3>
+      <div class="analysis-table-wrap">
+        <table class="analysis-table">
+          <thead><tr><th>Score</th><th>Page</th><th>Title</th><th>Tier</th><th>AI Intent</th><th>Weakest</th></tr></thead>
+          <tbody>${pageRows}</tbody>
+        </table>
+      </div>
+    </div>`;
+}
+
 // ─── Data Gathering Functions ────────────────────────────────────────────────
 
 function getLatestKeywordsReport(project) {

package/server.js

@@ -530,6 +530,27 @@ async function handleRequest(req, res) {
     return;
   }
 
+  // ─── API: Update insight status (Intelligence Ledger) ───
+  const insightMatch = path.match(/^\/api\/insights\/(\d+)\/status$/);
+  if (req.method === 'POST' && insightMatch) {
+    try {
+      const id = parseInt(insightMatch[1]);
+      const body = await readBody(req);
+      const status = body.status;
+      if (!['active', 'done', 'dismissed'].includes(status)) {
+        json(res, 400, { error: 'Invalid status. Use: active, done, dismissed' });
+        return;
+      }
+      const { getDb, updateInsightStatus } = await import('./db/db.js');
+      const db = getDb();
+      updateInsightStatus(db, id, status);
+      json(res, 200, { success: true, id, status });
+    } catch (e) {
+      json(res, 500, { error: e.message });
+    }
+    return;
+  }
+
   // ─── API: Analyze (spawn background) ───
   if (req.method === 'POST' && path === '/api/analyze') {
     try {