seo-intel 1.1.12 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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

package/cli.js

@@ -3864,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

@@ -48,6 +48,7 @@ function _insightFingerprint(type, item) {
     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();
@@ -512,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

@@ -176,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.12",
+  "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

@@ -19,6 +19,7 @@ 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));
 
@@ -103,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);
 
@@ -126,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
@@ -189,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);
@@ -3143,6 +3148,9 @@ 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">
@@ -4964,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) {