seo-intel 1.5.46 → 1.5.52

package/cli.js

@@ -16,11 +16,10 @@ import { program } from 'commander';
 import { spawnSync } from 'child_process';
 import { readFileSync, writeFileSync, readdirSync, unlinkSync, existsSync, mkdirSync } from 'fs';
 import { dirname, join } from 'path';
-import { totalmem } from 'os';
+import { totalmem, homedir } from 'os';
 import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 
-import { crawlDomain } from './crawler/index.js';
 // Paid modules — loaded lazily inside gated commands only.
 let _extractPage, _buildAnalysisPrompt;
 async function getExtractPage() {
@@ -54,9 +53,34 @@ import { getCurrentVersion, checkForUpdates, printUpdateNotice, forceUpdateCheck
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+// Self-register where this checkout/install lives, in ~/.seo-intel/install.json.
+// Any local agent harness (Hermes, a future Claude Code plugin, anything) can
+// read this one file to find SEO Intel — no env vars, no hardcoded paths, no
+// per-harness wiring. Cheap to refresh on every run; last run to execute wins,
+// which is the right default for the common one-checkout-per-machine case.
+function registerInstallLocation() {
+  try {
+    const dir = join(homedir(), '.seo-intel');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'install.json'), JSON.stringify({
+      root: __dirname,
+      version: getCurrentVersion(),
+      updatedAt: new Date().toISOString(),
+    }, null, 2));
+  } catch { /* non-fatal — harnesses fall back to PATH resolution */ }
+}
+registerInstallLocation();
+
 // Start background update check (non-blocking, never slows startup)
 checkForUpdates();
 
+// Long-running commands (serve, setup-web) intentionally keep the process alive.
+// Everything else is one-shot: once the action resolves we force-exit so a
+// hung background fetch (update check / license phone-home) can't hold the
+// shell — an aborted fetch's socket lingers until the OS connect timeout, so
+// AbortController alone is not enough to make the process exit promptly.
+let _keepProcessAlive = false;
+
 // Ensure reports/ and config/ directories exist
 try { mkdirSync(join(__dirname, 'reports'), { recursive: true }); } catch { /* ok */ }
 try { mkdirSync(join(__dirname, 'config'), { recursive: true }); } catch { /* ok */ }
@@ -575,6 +599,8 @@ program
         },
       };
 
+      // Lazy: crawler/index.js pulls Playwright + turndown — keep them off CLI startup
+      const { crawlDomain } = await import('./crawler/index.js');
       for await (const page of crawlDomain(site.url, crawlOpts)) {
         if (page._blocked) {
           totalBlocked++;
@@ -1323,6 +1349,7 @@ program
     let pageCount = 0;
     let skipped = 0;
     let blocked = false;
+    const { crawlDomain } = await import('./crawler/index.js');
     for await (const page of crawlDomain(next.url, {
       onSitemapDiscovered: (urls) => {
         try { upsertSitemapUrls(db, domainId, urls.map(u => u.url), `${next.url}/sitemap.xml`); }
@@ -1547,6 +1574,84 @@ program
     }
   });
 
+// ── MODELS ─────────────────────────────────────────────────────────────────
+program
+  .command('models')
+  .description('Suggest local extraction models for your hardware (Gemma / Qwen) — local is strongly recommended over cloud')
+  .option('--format <type>', 'Output format: brief or json', 'brief')
+  .action(async (opts) => {
+    const isJson = opts.format === 'json';
+    const { suggestExtractionModels, CLOUD_EXTRACTION_DISCLAIMER, detectVRAM } = await import('./setup/engine.js');
+
+    // Detect hardware (best-effort) + installed Ollama models (quick, short timeout).
+    let vram = { available: false, vramMB: 0, gpuName: null };
+    try { vram = detectVRAM(); } catch { /* keep default */ }
+    let installed = [];
+    try {
+      const controller = new AbortController();
+      const t = setTimeout(() => controller.abort(), 1500);
+      const res = await fetch('http://localhost:11434/api/tags', { signal: controller.signal });
+      clearTimeout(t);
+      if (res.ok) {
+        const data = await res.json();
+        installed = (data.models || []).map(m => m.name);
+      }
+    } catch { /* Ollama not reachable — fine */ }
+
+    const { suggestions, recommendedId } = suggestExtractionModels(vram.vramMB || 0, installed);
+
+    if (isJson) {
+      console.log(JSON.stringify({
+        command: 'models',
+        hardware: { gpu: vram.gpuName || null, vramMB: vram.vramMB || 0 },
+        recommended: recommendedId,
+        suggestions,
+        cloud_disclaimer: CLOUD_EXTRACTION_DISCLAIMER,
+      }, null, 2));
+      return;
+    }
+
+    console.log('');
+    console.log(chalk.bold('  🧠 Local extraction models'));
+    console.log('');
+    if (vram.available && vram.vramMB) {
+      console.log(chalk.gray(`  Detected: ${vram.gpuName || 'GPU'} · ~${(vram.vramMB / 1024).toFixed(1)} GB VRAM`));
+    } else {
+      console.log(chalk.gray('  GPU/VRAM not detected — showing the full range. Pick by your machine.'));
+    }
+    console.log('');
+
+    const qFmt = (q) => q === 'excellent' ? chalk.green(q) : q === 'great' || q === 'better' ? chalk.cyan(q) : chalk.gray(q);
+    for (const s of suggestions) {
+      const star = s.id === recommendedId ? chalk.bold.green(' ◀ recommended') : '';
+      const fit = vram.vramMB && !s.fitsVram ? chalk.red(' (needs more VRAM)') : '';
+      const got = s.installed ? chalk.green(' ✓ installed') : chalk.gray(` ollama pull ${s.id}`);
+      console.log(`  ${chalk.bold(s.name.padEnd(16))} ${chalk.gray(s.vram.padEnd(8))} ${s.speed.padEnd(11)} ${qFmt(s.quality)}${star}${fit}`);
+      console.log(`  ${' '.repeat(16)} ${got}`);
+    }
+    console.log('');
+
+    // The MUST: extraction-should-be-local disclaimer, every time.
+    console.log(chalk.bold.yellow('  ⚠  Extraction should be done with a LOCAL model'));
+    const wrap = (text, width) => {
+      const out = []; let line = '';
+      for (const word of text.split(/\s+/)) {
+        if ((line + ' ' + word).trim().length > width) { out.push(line.trim()); line = word; }
+        else line += ' ' + word;
+      }
+      if (line.trim()) out.push(line.trim());
+      return out;
+    };
+    for (const line of wrap(CLOUD_EXTRACTION_DISCLAIMER, 78)) {
+      console.log(chalk.yellow('     ' + line));
+    }
+    console.log('');
+    if (recommendedId && !suggestions.find(s => s.id === recommendedId)?.installed) {
+      console.log(chalk.gray(`  Get started:  `) + chalk.white(`ollama pull ${recommendedId}`) + chalk.gray(`  then  `) + chalk.white(`seo-intel setup`));
+      console.log('');
+    }
+  });
+
 // ── STATUS ─────────────────────────────────────────────────────────────────
 program
   .command('status')
@@ -2357,6 +2462,7 @@ program
   .option('--open', 'Open browser automatically', true)
   .option('--no-open', 'Do not open browser')
   .action(async (opts) => {
+    _keepProcessAlive = true;
     const port = parseInt(opts.port, 10);
     process.env.PORT = String(port);
     if (opts.open) process.env.SEO_INTEL_AUTO_OPEN = '1';
@@ -2369,6 +2475,7 @@ program
   .description('Open the web-based setup wizard in your browser')
   .option('--port <n>', 'Server port', '3000')
   .action(async (opts) => {
+    _keepProcessAlive = true;
     const port = parseInt(opts.port, 10);
     process.env.PORT = String(port);
     await import('./server.js');
@@ -4326,9 +4433,24 @@ program
     }
 
     const { runAeoAnalysis, persistAeoScores, upsertCitabilityInsights } = await import('./analyses/aeo/index.js');
+    const { fetchAiAccessForDomains } = await import('./analyses/aeo/ai-access.js');
+
+    // AI-crawler access (robots.txt) — domain-level signal. Network, but cheap
+    // (one robots.txt per target/owned domain) and best-effort.
+    const targetDomains = db
+      .prepare("SELECT DISTINCT domain FROM domains WHERE project = ? AND role IN ('target','owned')")
+      .all(project)
+      .map(r => r.domain);
+    let aiAccessByDomain = null;
+    if (targetDomains.length) {
+      if (isBrief) console.log(chalk.gray(`  Checking AI-crawler access (robots.txt) for ${targetDomains.length} domain(s)…`));
+      try { aiAccessByDomain = await fetchAiAccessForDomains(targetDomains); }
+      catch { aiAccessByDomain = null; }
+    }
 
     const results = runAeoAnalysis(db, project, {
       includeCompetitors: !opts.targetOnly,
+      aiAccessByDomain,
       log: (msg) => isBrief ? console.log(chalk.gray(msg)) : null,
     });
 
@@ -4340,7 +4462,7 @@ program
 
     // Persist scores
     persistAeoScores(db, results);
-    upsertCitabilityInsights(db, project, results.target);
+    upsertCitabilityInsights(db, project, results.target, results.summary.aiAccess);
 
     const { summary } = results;
     const { tierCounts } = summary;
@@ -4439,6 +4561,21 @@ program
       console.log(`    ${chalk.red('●')} Poor (<35):        ${tierCounts.poor}`);
       console.log('');
 
+      if (summary.aiAccess && summary.aiAccess.length) {
+        console.log(chalk.bold('  🤖 AI Crawler Access (robots.txt)'));
+        console.log('');
+        for (const a of summary.aiAccess) {
+          const icon = a.verdict === 'blocked' ? chalk.red('✗') : a.verdict === 'partial' ? chalk.yellow('⚠') : chalk.green('✓');
+          const label = a.verdict === 'blocked' ? chalk.red('BLOCKED') : a.verdict === 'partial' ? chalk.yellow('PARTIAL') : chalk.green('OPEN');
+          console.log(`    ${icon} ${chalk.bold(a.domain)}  ${label}  ${chalk.gray(a.score + '/100')}`);
+          if (a.verdict !== 'open') console.log(chalk.gray(`         ${a.detail}`));
+        }
+        if (summary.gatedPages > 0) {
+          console.log(chalk.red(`    ⛔ ${summary.gatedPages} page(s) capped at 30/100 — AI assistants can't read them, so on-page quality can't help.`));
+        }
+        console.log('');
+      }
+
       if (summary.weakestSignals.length) {
         console.log(chalk.bold('  🔍 Weakest Signals (target average)'));
         console.log('');
@@ -4488,12 +4625,16 @@ program
     }
 
     // ── 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`));
+    // Skip in JSON mode: generateMultiDashboard logs progress to stdout, which
+    // would corrupt the JSON object that machine/agent consumers parse.
+    if (isBrief) {
+      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 ──
@@ -4511,6 +4652,39 @@ program
     }
   });
 
+// ── RESCORE (single-URL re-check, closes the agent loop) ──────────────────
+program
+  .command('rescore <project> <url>')
+  .description("Re-check one URL's AI citability after a fix — read-only, raw-HTML (bot's-eye) score + delta vs baseline")
+  .option('--format <type>', 'Output format: brief or json', 'brief')
+  .action(async (project, url, opts) => {
+    const isJson = opts.format === 'json';
+    const { getDb } = await import('./db/db.js');
+    const { rescorePage } = await import('./analyses/aeo/rescore.js');
+    const db = getDb();
+    const res = await rescorePage(db, project, url, {
+      log: isJson ? undefined : (m) => console.log(chalk.gray('  ' + m)),
+    });
+    if (isJson) {
+      console.log(JSON.stringify(res, null, 2));
+      return;
+    }
+    const tone = (s) => (s == null ? chalk.gray : s >= 60 ? chalk.green : s >= 35 ? chalk.yellow : chalk.red);
+    console.log('');
+    console.log(chalk.bold(`  🔁 Re-score — ${url}`));
+    console.log(chalk.gray(`     lens: raw HTML (what bots see) · HTTP ${res.status_code ?? '—'}`));
+    if (res.after == null) {
+      console.log(chalk.red(`     ✗ ${res.note || 'could not score'}`));
+    } else {
+      const b = res.before == null ? chalk.gray('—') : tone(res.before)(String(res.before));
+      const a = tone(res.after)(String(res.after));
+      const arrow =
+        res.delta == null ? '' : res.delta > 0 ? chalk.green(`  ▲ +${res.delta}`) : res.delta < 0 ? chalk.red(`  ▼ ${res.delta}`) : chalk.gray('  ±0');
+      console.log(`     citability  ${b} → ${a}${arrow}   (${res.status_before ?? '—'} → ${res.status_after ?? '—'})`);
+    }
+    console.log('');
+  });
+
 // ── SITE WATCH ──────────────────────────────────────────────────────────
 program
   .command('watch <project>')
@@ -4674,11 +4848,14 @@ program
       console.log(chalk.green(`\n  ✅ Report saved: ${opts.out}\n`));
     }
 
-    // Regenerate dashboard
-    try {
-      const configs = loadAllConfigs();
-      generateMultiDashboard(db, configs);
-    } catch {}
+    // Regenerate dashboard — skip in JSON mode so generateMultiDashboard's
+    // stdout progress logs don't corrupt the JSON output.
+    if (opts.format !== 'json') {
+      try {
+        const configs = loadAllConfigs();
+        generateMultiDashboard(db, configs);
+      } catch {}
+    }
   });
 
 // ── AEO BLOG DRAFT GENERATOR ─────────────────────────────────────────────
@@ -5057,10 +5234,20 @@ program
   });
 
 // ── License activation hook — phone-home if cache is stale/missing ──────────
+// Hard cap so a slow/unreachable license server can never block the command.
+// If activation doesn't finish in time we proceed on cached/offline behavior;
+// the in-flight request is abandoned when the process exits (see bottom of file).
+const LICENSE_ACTIVATION_BUDGET_MS = 2500;
 program.hook('preAction', async () => {
   const license = loadLicense();
   if (license.needsActivation || license.stale) {
-    await activateLicense().catch(() => {});
+    await Promise.race([
+      activateLicense().catch(() => {}),
+      new Promise((resolve) => {
+        const t = setTimeout(resolve, LICENSE_ACTIVATION_BUDGET_MS);
+        if (typeof t.unref === 'function') t.unref();
+      }),
+    ]);
   }
 });
 
@@ -5164,6 +5351,7 @@ program
     const tag = chalk.cyan(`[${domain.split('.')[0]}]`);
 
     try {
+      const { crawlDomain } = await import('./crawler/index.js');
       for await (const page of crawlDomain(siteUrl, {
         maxPages, stealth: useStealth, tiered: true,
         onSitemapDiscovered: (urls) => {
@@ -5516,7 +5704,27 @@ program
   });
 
 // Global error handler — ensures uncaught errors in async actions exit non-zero (BUG-004)
-program.parseAsync().catch(err => {
-  console.error(chalk.red(`\n✗ ${err.message}\n`));
-  process.exit(1);
-});
+program.parseAsync()
+  .then(() => {
+    // One-shot command finished — exit now instead of waiting on the event loop
+    // to drain. A hung background fetch (update check / license phone-home) would
+    // otherwise keep the process alive until the OS connect timeout (~10s).
+    if (!_keepProcessAlive) flushThenExit(process.exitCode ?? 0);
+  })
+  .catch(err => {
+    console.error(chalk.red(`\n✗ ${err.message}\n`));
+    process.exit(1);
+  });
+
+// Drain any buffered stdout/stderr before exiting. process.exit() truncates
+// async pipe writes (large `--format json` output piped to another process),
+// so we wait for both streams to flush, with a short safety net so a stalled
+// pipe can never hang the process.
+function flushThenExit(code) {
+  let pending = 2;
+  const done = () => { if (--pending === 0) process.exit(code); };
+  process.stdout.write('', done);
+  process.stderr.write('', done);
+  const t = setTimeout(() => process.exit(code), 2000);
+  if (typeof t.unref === 'function') t.unref();
+}

package/config/example.json

@@ -1,5 +1,6 @@
 {
   "project": "myproject",
+  "sourcePath": "/absolute/path/to/the/site/source — a repo or a plain folder, both work. Omit if you don't want agent dispatch to know where the code lives.",
   "context": {
     "siteName": "My Project",
     "url": "https://example.com",

package/extractor/qwen.js

@@ -24,14 +24,17 @@ function modelMatches(available, target) {
 // ── LM Studio support (OpenAI-compatible API) ──────────────────────────────
 
 /**
- * Ping an LM Studio host. Uses GET /api/v1/models instead of Ollama's /api/tags.
+ * Ping an LM Studio host. Uses the OpenAI-compatible GET /v1/models (returns
+ * { data: [{ id }] } and lists models that are actually loaded/servable) —
+ * NOT the native /api/v1/models, which returns a different shape ({ models:
+ * [{ key }] }) and lists every downloaded model regardless of load state.
  */
 export async function pingLmStudioHost(host, model, timeoutMs = OLLAMA_PREFLIGHT_TIMEOUT_MS) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
 
   try {
-    const res = await fetch(`${host}/api/v1/models`, { signal: controller.signal });
+    const res = await fetch(`${host}/v1/models`, { signal: controller.signal });
     if (!res.ok) {
       return { host, model, reachable: false, modelAvailable: false, type: 'lmstudio',
         error: `HTTP ${res.status} ${res.statusText}`.trim() };
@@ -62,14 +65,17 @@ async function callLmStudio(route, prompt) {
   const timeout = setTimeout(() => controller.abort(), OLLAMA_TIMEOUT_MS);
 
   try {
-    const res = await fetch(`${route.host}/api/v1/chat`, {
+    const res = await fetch(`${route.host}/v1/chat/completions`, {
       signal: controller.signal,
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
         model: route.model,
         messages: [{ role: 'user', content: prompt }],
-        response_format: { type: 'json_object' },
+        // LM Studio rejects OpenAI's 'json_object'; it accepts only 'json_schema'
+        // or 'text'. The prompt already demands JSON and the response is run
+        // through extractLastJsonObject/repairJson, so 'text' is the portable choice.
+        response_format: { type: 'text' },
         temperature: 0,
         max_tokens: 1200,
         stream: false,
@@ -427,10 +433,20 @@ JSON output:`;
       console.log(`[extractor] used ${route.label} for ${url}`);
       break;
     } catch (err) {
-      route.failures = (route.failures || 0) + 1;
       console.warn(`[extractor] ${route.label} failed for ${url}: ${describeOllamaError(err, route)}`);
-      if (route.failures >= OLLAMA_HOST_FAILURE_LIMIT) {
-        removeRouteFromActivePool(runtimeState, route);
+      // Only TRANSPORT failures (host down/unreachable) should retire a host for
+      // the run. CONTENT failures (a small model returns unparseable JSON for one
+      // long page) must NOT disable the host — that page degrades on its own; the
+      // next page may extract fine. Conflating the two killed local extraction
+      // after a couple of hard pages.
+      const msg = String(err?.message || '');
+      const transportFail = err?.name === 'AbortError'
+        || /fetch failed|ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|socket hang up|network|timeout|HTTP 5\d\d/i.test(msg);
+      if (transportFail) {
+        route.failures = (route.failures || 0) + 1;
+        if (route.failures >= OLLAMA_HOST_FAILURE_LIMIT) {
+          removeRouteFromActivePool(runtimeState, route);
+        }
       }
     }
   }

package/lib/intel.js

@@ -108,11 +108,112 @@ function collectRaw(db, project) {
   };
 }
 
+// Map a page's weakest citability signal to a concrete on-page fix.
+const SIGNAL_FIX = {
+  'schema coverage': 'Add JSON-LD schema (FAQPage / Product / Organization)',
+  'qa proximity': 'Add a Q&A / FAQ section answering real questions',
+  'entity authority': 'Add author + credentials and sameAs entity grounding',
+  'structured claims': 'Add extractable, standalone factual claims',
+  'answer density': 'Lead each section with a direct one-line answer',
+  'freshness': 'Add visible published / updated dates',
+};
+const scoreBucket = (s) => (s >= 75 ? 'good' : s >= 55 ? 'needs-work' : s >= 35 ? 'weak' : 'poor');
+
+/**
+ * Ranked, role-attributed opportunities from citability scores. Each row is
+ * dashboard-ready: real value/status/confidence + a concrete suggested fix.
+ * side='fix' = your own pages to improve; side='attack' = thin competitor pages.
+ */
+function buildOpportunities(db, project) {
+  let rows = [];
+  try {
+    rows = db.prepare(`
+      SELECT p.url, p.title, d.domain, d.role,
+             c.score, c.entity_authority, c.structured_claims, c.answer_density,
+             c.qa_proximity, c.freshness, c.schema_coverage, c.ai_intents
+      FROM citability_scores c
+      JOIN pages p ON p.id = c.page_id
+      JOIN domains d ON d.id = p.domain_id
+      WHERE d.project = ?
+      ORDER BY c.score ASC
+    `).all(project);
+  } catch { return { opportunities: [], summary: null }; }
+
+  const opportunities = rows.map((r, i) => {
+    const own = r.role === 'target' || r.role === 'owned';
+    const signals = {
+      'entity authority': r.entity_authority, 'structured claims': r.structured_claims,
+      'answer density': r.answer_density, 'qa proximity': r.qa_proximity,
+      'freshness': r.freshness, 'schema coverage': r.schema_coverage,
+    };
+    const ranked = Object.entries(signals).filter(([, v]) => v != null).sort((a, b) => a[1] - b[1]);
+    const weak = ranked.slice(0, 2).map(([k]) => k);
+    let intent = null;
+    try { intent = (JSON.parse(r.ai_intents || '[]') || [])[0] || null; } catch { /* ignore */ }
+    let label = r.title || r.url;
+    try { const u = new URL(r.url); label = u.hostname + (u.pathname === '/' ? '' : u.pathname); } catch { /* keep label */ }
+    return {
+      id: `cit:${i}`,
+      side: own ? 'fix' : 'attack',
+      role: r.role,
+      domain: r.domain,
+      url: r.url,
+      title: r.title || null,
+      finding: label,
+      kind: 'citability',
+      score: r.score,
+      status: scoreBucket(r.score),
+      value: Math.round((100 - r.score) * (own ? 1 : 0.6)),   // your low pages rank highest
+      confidence: +(ranked.length / 6).toFixed(2),            // signal completeness
+      intent,
+      weak_signals: weak,
+      suggested_action: own ? (SIGNAL_FIX[weak[0]] || 'Improve on-page citability') : 'Outrank — thin competitor page',
+      proof: r.url,
+    };
+  }).sort((a, b) => b.value - a.value);
+
+  const owned = opportunities.filter((o) => o.side === 'fix');
+  const attack = opportunities.filter((o) => o.side === 'attack');
+  const avg = (arr) => (arr.length ? Math.round((arr.reduce((s, o) => s + o.score, 0) / arr.length) * 10) / 10 : null);
+
+  // Per-signal averages across YOUR pages — the AEO citability breakdown.
+  const ownedRows = rows.filter((r) => r.role === 'target' || r.role === 'owned');
+  const signalAvg = (key) => {
+    const vals = ownedRows.map((r) => r[key]).filter((v) => v != null);
+    return vals.length ? Math.round(vals.reduce((a, b) => a + b, 0) / vals.length) : null;
+  };
+  const signals = {
+    entity_authority: signalAvg('entity_authority'),
+    structured_claims: signalAvg('structured_claims'),
+    answer_density: signalAvg('answer_density'),
+    qa_proximity: signalAvg('qa_proximity'),
+    freshness: signalAvg('freshness'),
+    schema_coverage: signalAvg('schema_coverage'),
+  };
+
+  return {
+    opportunities,
+    summary: {
+      pages_scored: rows.length,
+      owned_pages: owned.length,
+      competitor_pages: attack.length,
+      avg_citability_owned: avg(owned),
+      avg_citability_all: avg(opportunities),
+      fix_opportunities: owned.length,
+      attack_targets: attack.length,
+      signals,
+    },
+  };
+}
+
 function collectAudit(db, project) {
   const insights = getActiveInsights(db, project);
   let citability = null;
   try { citability = getCitabilityScores(db, project); } catch { /* citability_scores table may not exist if AEO never run */ }
+  const { opportunities, summary } = buildOpportunities(db, project);
   return {
+    summary,
+    opportunities,
     citability,
     insights: {
       keyword_gaps: insights.keyword_gaps,

package/lib/license.js

@@ -36,6 +36,23 @@ const CACHE_PATH = join(CACHE_DIR, 'license-cache.json');
 const LS_CACHE_TTL = 24 * 60 * 60 * 1000;        // 24h fresh
 const LS_STALE_LIMIT = 7 * 24 * 60 * 60 * 1000;   // 7 days stale max
 
+// Lemon Squeezy License API base — overridable for testing (e.g. point at an
+// unreachable host to verify graceful degradation).
+const LS_API_BASE = (process.env.SEO_INTEL_LICENSE_API || 'https://api.lemonsqueezy.com').replace(/\/+$/, '');
+
+// Per-request network budget. A reachable server answers well under this; a
+// slow/unreachable one aborts here instead of hanging. The CLI also caps the
+// total activation wait in its preAction hook, so this is a backstop.
+const NETWORK_TIMEOUT_MS = 6000;
+
+/** AbortController whose timeout won't keep the event loop alive on its own. */
+function abortAfter(ms) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  if (typeof timer.unref === 'function') timer.unref();
+  return { controller, timer };
+}
+
 // ── Tiers ──────────────────────────────────────────────────────────────────
 
 export const TIERS = {
@@ -132,23 +149,21 @@ function checkCache(key) {
  * Returns instance_id on success.
  */
 async function activateWithLS(key) {
+  const { controller, timer } = abortAfter(NETWORK_TIMEOUT_MS);
   try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 8000);
-
     const body = new URLSearchParams({
       license_key: key,
       instance_name: `seo-intel-${getMachineId()}`,
     });
 
-    const res = await fetch('https://api.lemonsqueezy.com/v1/licenses/activate', {
+    const res = await fetch(`${LS_API_BASE}/v1/licenses/activate`, {
       signal: controller.signal,
       method: 'POST',
       headers: { 'Accept': 'application/json' },
       body,
     });
 
-    clearTimeout(timeout);
+    clearTimeout(timer);
     const data = await res.json();
 
     if (data.activated) {
@@ -179,22 +194,20 @@ async function activateWithLS(key) {
  * Params: license_key, instance_id (optional)
  */
 async function validateWithLS(key, instanceId) {
+  const { controller, timer } = abortAfter(NETWORK_TIMEOUT_MS);
   try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 8000);
-
     const params = { license_key: key };
     if (instanceId) params.instance_id = instanceId;
     const body = new URLSearchParams(params);
 
-    const res = await fetch('https://api.lemonsqueezy.com/v1/licenses/validate', {
+    const res = await fetch(`${LS_API_BASE}/v1/licenses/validate`, {
       signal: controller.signal,
       method: 'POST',
       headers: { 'Accept': 'application/json' },
       body,
     });
 
-    clearTimeout(timeout);
+    clearTimeout(timer);
     const data = await res.json();
 
     if (data.valid) {
@@ -228,23 +241,21 @@ export async function deactivateLicense() {
   const instanceId = cache?.instanceId;
   if (!instanceId) return { deactivated: false, error: 'No active instance to deactivate' };
 
+  const { controller, timer } = abortAfter(NETWORK_TIMEOUT_MS);
   try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 8000);
-
     const body = new URLSearchParams({
       license_key: keyInfo.value,
       instance_id: instanceId,
     });
 
-    const res = await fetch('https://api.lemonsqueezy.com/v1/licenses/deactivate', {
+    const res = await fetch(`${LS_API_BASE}/v1/licenses/deactivate`, {
       signal: controller.signal,
       method: 'POST',
       headers: { 'Accept': 'application/json' },
       body,
     });
 
-    clearTimeout(timeout);
+    clearTimeout(timer);
     const data = await res.json();
 
     if (data.deactivated) {