@nebulacomponents/citable 1.17.0 → 1.18.1

package/src/analysis/iceMatrix.js

@@ -0,0 +1,205 @@
+/**
+ * Impact / Effort / Confidence (ICE) scoring matrix for Citable findings and initiatives.
+ *
+ * All factors are explicitly scored on a transparent 1-10 scale.
+ * Formula: ICE Score = (Impact × Confidence) / Effort
+ * Quadrants:
+ * - Quick Wins: High Impact (>=6), Low Effort (<=4), High Confidence (>=6)
+ * - Strategic Bets: High Impact (>=6), High Effort (>=5)
+ * - Low-Hanging Fruit: Low Impact (<6), Low Effort (<=4)
+ * - Deprioritize: Low Impact (<6), High Effort (>=5) or Low Confidence (<5)
+ */
+
+const SEVERITY_IMPACT_MAP = {
+  critical: 10,
+  high: 8,
+  medium: 5,
+  low: 2,
+  informational: 1,
+  experimental: 2,
+};
+
+const DETECTOR_EFFORT_MAP = {
+  TECH: 4,
+  CRAWL: 3,
+  CWV: 5,
+  ARCH: 6,
+  PAGE: 3,
+  ANS: 4,
+  GEO: 5,
+  RECO: 6,
+  SCHEMA: 3,
+  LINK: 4,
+  ENTITY: 4,
+  CLAIM: 5,
+  EVD: 6,
+  SEC: 4,
+  MOBILE: 3,
+  CRO: 4,
+};
+
+const CONFIDENCE_MAP = {
+  deterministic: 10,
+  verified: 9,
+  validated: 8,
+  proxy: 6,
+  modeled: 6,
+  anecdote: 4,
+  assumption: 3,
+};
+
+/**
+ * Score an audit finding for the ICE matrix
+ */
+export function scoreFinding(finding) {
+  const severity = finding.classification?.severity || 'medium';
+  const impact = SEVERITY_IMPACT_MAP[severity] ?? 5;
+
+  const ns = (finding.detector_id || '').split('-')[0];
+  let effort = DETECTOR_EFFORT_MAP[ns] ?? 4;
+  if (finding.remediation?.review_required) effort += 2;
+  effort = Math.min(10, Math.max(1, effort));
+
+  let confidence = 8;
+  if (finding.classification?.deterministic) {
+    confidence = 10;
+  } else if (finding.fact_status === 'observed_telemetry') {
+    confidence = 9;
+  } else if (finding.fact_status === 'modeled_rubric_evaluation') {
+    confidence = 6;
+  }
+
+  const iceScore = Math.round(((impact * confidence) / effort) * 10) / 10;
+
+  let quadrant = 'low_hanging_fruit';
+  if (impact >= 6 && effort <= 4 && confidence >= 6) {
+    quadrant = 'quick_wins';
+  } else if (impact >= 6 && effort >= 5) {
+    quadrant = 'strategic_bets';
+  } else if (impact < 6 && effort <= 4) {
+    quadrant = 'low_hanging_fruit';
+  } else {
+    quadrant = 'deprioritize';
+  }
+
+  return {
+    id: finding.detector_id || finding.finding_id,
+    finding_id: finding.finding_id,
+    detector_id: finding.detector_id,
+    title: finding.observation?.summary || finding.name || finding.detector_id,
+    subject: finding.subject?.identifier || finding.subject?.url || 'global',
+    severity,
+    impact,
+    effort,
+    confidence,
+    ice_score: iceScore,
+    quadrant,
+  };
+}
+
+/**
+ * Score an initiative from initiatives.yaml for the ICE matrix
+ */
+export function scoreInitiative(initiative) {
+  const SCALE = { none: 0, low: 2, medium: 5, high: 8, critical: 10, validated: 9, transformative: 10, trivial: 1, very_high: 9, negligible: 1 };
+
+  const demand = SCALE[initiative.customer_demand] ?? 5;
+  const rev = SCALE[initiative.revenue_potential] ?? 5;
+  const diff = SCALE[initiative.strategic_differentiation] ?? 5;
+  const impact = Math.min(10, Math.max(1, Math.round((demand + rev + diff) / 3)));
+
+  const engCost = SCALE[initiative.engineering_cost] ?? 5;
+  const opCost = SCALE[initiative.operating_cost || 'none'] ?? 0;
+  const effort = Math.min(10, Math.max(1, Math.round(engCost + opCost * 0.3)));
+
+  const confidence = CONFIDENCE_MAP[initiative.evidence_strength] ?? 5;
+  const iceScore = Math.round(((impact * confidence) / effort) * 10) / 10;
+
+  let quadrant = 'low_hanging_fruit';
+  if (impact >= 6 && effort <= 4 && confidence >= 6) {
+    quadrant = 'quick_wins';
+  } else if (impact >= 6 && effort >= 5) {
+    quadrant = 'strategic_bets';
+  } else if (impact < 6 && effort <= 4) {
+    quadrant = 'low_hanging_fruit';
+  } else {
+    quadrant = 'deprioritize';
+  }
+
+  return {
+    id: initiative.initiative_id,
+    title: initiative.title,
+    owner: initiative.owner || 'unassigned',
+    status: initiative.status,
+    impact,
+    effort,
+    confidence,
+    ice_score: iceScore,
+    quadrant,
+  };
+}
+
+/**
+ * Build the full ICE Scoring Matrix from a list of findings or initiatives
+ */
+export function buildIceMatrix(items = [], { type = 'findings' } = {}) {
+  const scored = items.map((item) => (type === 'initiatives' ? scoreInitiative(item) : scoreFinding(item)));
+  scored.sort((a, b) => b.ice_score - a.ice_score || b.impact - a.impact);
+
+  const quadrants = {
+    quick_wins: scored.filter((i) => i.quadrant === 'quick_wins'),
+    strategic_bets: scored.filter((i) => i.quadrant === 'strategic_bets'),
+    low_hanging_fruit: scored.filter((i) => i.quadrant === 'low_hanging_fruit'),
+    deprioritize: scored.filter((i) => i.quadrant === 'deprioritize'),
+  };
+
+  return {
+    fact_status: 'transparent_prioritization_matrix',
+    scoring_method: 'ICE: (Impact [1-10] × Confidence [1-10]) / Effort [1-10]',
+    total_items: scored.length,
+    summary: {
+      quick_wins_count: quadrants.quick_wins.length,
+      strategic_bets_count: quadrants.strategic_bets.length,
+      low_hanging_fruit_count: quadrants.low_hanging_fruit.length,
+      deprioritize_count: quadrants.deprioritize.length,
+    },
+    quadrants,
+    ranked_items: scored,
+  };
+}
+
+/**
+ * Format ICE Matrix as human-readable terminal table / markdown
+ */
+export function formatIceMatrixOutput(matrix) {
+  const lines = [
+    `Impact / Effort / Confidence (ICE) Prioritization Matrix`,
+    `=======================================================`,
+    `Methodology: ${matrix.scoring_method}`,
+    `Total Items Scored: ${matrix.total_items}`,
+    ``,
+    `QUADRANT SUMMARY:`,
+    `  Quadrant I   [Quick Wins]:          ${matrix.summary.quick_wins_count} item(s) (High Impact, Low Effort, High Confidence)`,
+    `  Quadrant II  [Strategic Bets]:      ${matrix.summary.strategic_bets_count} item(s) (High Impact, High Effort)`,
+    `  Quadrant III [Low-Hanging Fruit]:   ${matrix.summary.low_hanging_fruit_count} item(s) (Low Impact, Low Effort)`,
+    `  Quadrant IV  [Deprioritize]:        ${matrix.summary.deprioritize_count} item(s) (Low Impact or Low Confidence)`,
+    ``,
+    `RANKED ACTION MATRIX:`,
+    `  ${'Rank'.padEnd(6)} | ${'ID'.padEnd(16)} | ${'Impact'.padEnd(8)} | ${'Effort'.padEnd(8)} | ${'Conf'.padEnd(6)} | ${'ICE Score'.padEnd(10)} | Quadrant`,
+    `  ${'-'.repeat(80)}`,
+  ];
+
+  matrix.ranked_items.forEach((item, idx) => {
+    const rank = `#${idx + 1}`.padEnd(6);
+    const id = (item.id || '').slice(0, 16).padEnd(16);
+    const impact = `${item.impact}/10`.padEnd(8);
+    const effort = `${item.effort}/10`.padEnd(8);
+    const conf = `${item.confidence}/10`.padEnd(6);
+    const score = `${item.ice_score}`.padEnd(10);
+    const q = item.quadrant.toUpperCase();
+    lines.push(`  ${rank} | ${id} | ${impact} | ${effort} | ${conf} | ${score} | ${q}`);
+    lines.push(`         ${item.title.slice(0, 70)}`);
+  });
+
+  return lines.join('\n');
+}

package/src/analysis/offpage.js

@@ -0,0 +1,228 @@
+import { URL } from 'node:url';
+
+const SPAM_TLDS = new Set([
+  'top', 'work', 'gdn', 'click', 'monster', 'buzz', 'cfd', 'sbs',
+  'rest', 'cam', 'fit', 'surf', 'stream', 'tk', 'ml', 'ga', 'cf',
+]);
+
+const COMMERCIAL_SPAM_KEYWORDS = /\b(casino|viagra|cialis|payday\s*loans?|replica|cheap\s*essay|free\s*download|warez|crack|hack|gambling|betting|slots|crypto\s*airdrop)\b/i;
+
+function extractHostname(urlString) {
+  try {
+    return new URL(urlString).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function extractRootDomain(hostname) {
+  if (!hostname) return null;
+  const parts = hostname.split('.');
+  if (parts.length <= 2) return hostname;
+  return parts.slice(-2).join('.');
+}
+
+function extractTld(hostname) {
+  if (!hostname) return null;
+  const parts = hostname.split('.');
+  return parts.at(-1) || null;
+}
+
+/**
+ * Audit an inbound backlink profile for authority distribution and toxic domain risks.
+ */
+export function auditBacklinkProfile(backlinks, { targetDomain = null } = {}) {
+  const links = Array.isArray(backlinks) ? backlinks : (backlinks?.backlinks || []);
+  const normalizedTarget = targetDomain ? targetDomain.toLowerCase().replace(/^www\./, '') : null;
+
+  const referringDomains = new Map();
+  const cClassClusters = new Map();
+  let dofollowCount = 0;
+  let nofollowCount = 0;
+  let ugcCount = 0;
+  let sponsoredCount = 0;
+  let homepageLinksCount = 0;
+  let deepLinksCount = 0;
+
+  const anchorTypes = {
+    branded: 0,
+    naked_url: 0,
+    generic: 0,
+    exact_match_commercial: 0,
+    other: 0,
+  };
+
+  const toxicDomains = [];
+  const GENERIC_ANCHORS = /^(?:click here|here|website|link|read more|learn more|source|this site|visit|more info)$/i;
+
+  // 1. Process each backlink
+  for (const link of links) {
+    const srcHost = extractHostname(link.source_url);
+    if (!srcHost) continue;
+    const rootDomain = extractRootDomain(srcHost) || srcHost;
+    const tld = extractTld(srcHost);
+    const anchor = (link.anchor_text || '').trim();
+    const rel = (link.rel || '').toLowerCase();
+    const isNofollow = rel.includes('nofollow');
+    const isUgc = rel.includes('ugc');
+    const isSponsored = rel.includes('sponsored');
+
+    if (isNofollow) nofollowCount++;
+    else if (isUgc) ugcCount++;
+    else if (isSponsored) sponsoredCount++;
+    else dofollowCount++;
+
+    // Deep link vs homepage
+    const targetPath = link.target_url ? (() => { try { return new URL(link.target_url).pathname; } catch { return '/'; } })() : '/';
+    if (targetPath === '/' || targetPath === '') homepageLinksCount++;
+    else deepLinksCount++;
+
+    // Anchor categorization
+    if (normalizedTarget && (anchor.toLowerCase().includes(normalizedTarget) || normalizedTarget.includes(anchor.toLowerCase()))) {
+      anchorTypes.branded++;
+    } else if (/^https?:\/\//i.test(anchor) || anchor.includes('www.') || anchor.includes('.com') || anchor.includes('.org')) {
+      anchorTypes.naked_url++;
+    } else if (GENERIC_ANCHORS.test(anchor)) {
+      anchorTypes.generic++;
+    } else if (COMMERCIAL_SPAM_KEYWORDS.test(anchor) || /\b(buy|best|cheap|discount|order)\b/i.test(anchor)) {
+      anchorTypes.exact_match_commercial++;
+    } else {
+      anchorTypes.other++;
+    }
+
+    // C-class IP clustering
+    if (link.source_ip) {
+      const parts = link.source_ip.split('.');
+      if (parts.length === 4) {
+        const cClass = parts.slice(0, 3).join('.');
+        const cluster = cClassClusters.get(cClass) || new Set();
+        cluster.add(rootDomain);
+        cClassClusters.set(cClass, cluster);
+      }
+    }
+
+    // Domain tracking
+    const domainData = referringDomains.get(rootDomain) || {
+      domain: rootDomain,
+      sample_source_url: link.source_url,
+      total_links: 0,
+      anchors: [],
+      tld,
+      ip: link.source_ip || null,
+      dofollow: false,
+    };
+    domainData.total_links++;
+    if (!isNofollow && !isSponsored) domainData.dofollow = true;
+    if (anchor && !domainData.anchors.includes(anchor)) domainData.anchors.push(anchor);
+    referringDomains.set(rootDomain, domainData);
+  }
+
+  // 2. Toxic domain risk analysis per domain
+  for (const [domain, data] of referringDomains.entries()) {
+    const reasons = [];
+    let riskTier = 'clean';
+
+    // Spam TLD rule
+    if (data.tld && SPAM_TLDS.has(data.tld)) {
+      reasons.push(`Known high-abuse spam TLD (.${data.tld})`);
+      riskTier = 'high';
+    }
+
+    // Spam anchor rule
+    const hasSpamAnchor = data.anchors.some((a) => COMMERCIAL_SPAM_KEYWORDS.test(a));
+    if (hasSpamAnchor) {
+      reasons.push('Anchor text matches known high-risk commercial spam patterns');
+      riskTier = 'critical';
+    }
+
+    // PBN IP clustering rule (3+ distinct domains on the exact same /24 C-block)
+    if (data.ip) {
+      const parts = data.ip.split('.');
+      if (parts.length === 4) {
+        const cClass = parts.slice(0, 3).join('.');
+        const cluster = cClassClusters.get(cClass);
+        if (cluster && cluster.size >= 3) {
+          reasons.push(`Part of hosting cluster on ${cClass}.0/24 with ${cluster.size} domains (PBN footprint)`);
+          riskTier = 'critical';
+        }
+      }
+    }
+
+    // Excessive sitewide link density without nofollow
+    if (data.total_links > 50 && data.dofollow && (data.tld && SPAM_TLDS.has(data.tld))) {
+      reasons.push(`Sitewide link farm pattern (${data.total_links} links without rel="nofollow")`);
+      riskTier = 'critical';
+    }
+
+    if (riskTier !== 'clean') {
+      toxicDomains.push({
+        domain,
+        risk_tier: riskTier,
+        reasons,
+        sample_url: data.sample_source_url,
+        anchors: data.anchors.slice(0, 5),
+        total_links: data.total_links,
+      });
+    }
+  }
+
+  // Sort toxic domains by severity (critical first)
+  toxicDomains.sort((a, b) => (a.risk_tier === 'critical' ? -1 : 1));
+
+  const totalLinks = links.length;
+  const totalDomains = referringDomains.size;
+  const commercialAnchorPct = totalLinks > 0 ? Math.round((anchorTypes.exact_match_commercial / totalLinks) * 100) : 0;
+  const brandedAnchorPct = totalLinks > 0 ? Math.round((anchorTypes.branded / totalLinks) * 100) : 0;
+  const deepLinkPct = totalLinks > 0 ? Math.round((deepLinksCount / totalLinks) * 100) : 0;
+
+  // Authority health assessment
+  let profileHealth = 'natural';
+  if (toxicDomains.some((d) => d.risk_tier === 'critical') || commercialAnchorPct > 30) {
+    profileHealth = 'high_risk_footprint';
+  } else if (toxicDomains.length > 0 || commercialAnchorPct > 15) {
+    profileHealth = 'moderate_risk';
+  }
+
+  // Generate GSC-compatible disavow lines
+  const disavowLines = [
+    `# Citable Google Disavow Candidate Export`,
+    `# Generated at: ${new Date().toISOString()}`,
+    `# Flagged domains: ${toxicDomains.length} (critical: ${toxicDomains.filter((d) => d.risk_tier === 'critical').length})`,
+    ``,
+  ];
+  for (const td of toxicDomains) {
+    disavowLines.push(`# Risk: ${td.risk_tier.toUpperCase()} — ${td.reasons.join('; ')}`);
+    disavowLines.push(`domain:${td.domain}`);
+  }
+
+  return {
+    fact_status: 'observable_risk_indicators',
+    target_domain: targetDomain,
+    profile_health: profileHealth,
+    summary: {
+      total_backlinks: totalLinks,
+      total_referring_domains: totalDomains,
+      toxic_domains_count: toxicDomains.length,
+      critical_risk_domains: toxicDomains.filter((d) => d.risk_tier === 'critical').length,
+      high_risk_domains: toxicDomains.filter((d) => d.risk_tier === 'high').length,
+      dofollow_count: dofollowCount,
+      nofollow_count: nofollowCount,
+      ugc_count: ugcCount,
+      sponsored_count: sponsoredCount,
+      deep_link_ratio_pct: deepLinkPct,
+    },
+    anchor_profile: {
+      branded_pct: brandedAnchorPct,
+      commercial_exact_match_pct: commercialAnchorPct,
+      naked_url_count: anchorTypes.naked_url,
+      generic_count: anchorTypes.generic,
+      over_optimization_risk: commercialAnchorPct > 25 ? 'elevated' : 'normal',
+    },
+    toxic_domains: toxicDomains,
+    disavow_export: disavowLines.join('\n'),
+    limitations: [
+      'Search engines do not disclose algorithmic penalty thresholds; toxic classifications reflect observable risk patterns.',
+      'Manual verification is required before submitting disavow files to Google Search Console.',
+    ],
+  };
+}

package/src/analysis/readiness.js

@@ -0,0 +1,253 @@
+import { parse as parseHtml } from 'node-html-parser';
+import { registryPageFor, safePath } from '../detectors/framework.js';
+
+const QUESTION_RX = /^(?:how|what|why|when|where|who|can|is|does|which|should)\b|\?$/i;
+const COPULA_RX = /\b(?:is|are|refers\s+to|denotes|represents|means|provides|enables)\b/i;
+
+/**
+ * Evaluates a page's extraction, retrieval, and citation readiness across
+ * Perplexity, Bing Copilot, and ChatGPT / SearchGPT.
+ */
+export function evaluateAnswerEngineReadiness(page, ctx = {}) {
+  const html = page.html || '';
+  const root = parseHtml(html);
+  const text = (page.text || root.textContent || '').replace(/\s+/g, ' ').trim();
+  const headings = page.headings || [];
+  const paragraphs = page.paragraphs || root.querySelectorAll('p').map((p) => p.text.trim()).filter(Boolean);
+  const jsonLd = page.jsonLd || [];
+  const tablesCount = (page.tables ?? root.querySelectorAll('table').length);
+  const listsCount = (page.orderedLists ?? root.querySelectorAll('ol').length) + root.querySelectorAll('ul').length;
+  const wordCount = page.rawVisibleWordCount || page.wordCount || text.split(/\s+/).filter(Boolean).length;
+
+  // Crawler directives check (from robots Directives or headers)
+  const robotsDirectives = Array.from(page.robotsDirectives || []);
+  const isNoindex = robotsDirectives.some((d) => d.includes('noindex'));
+
+  // -----------------------------------------------------------------
+  // 1. PERPLEXITY READINESS
+  // -----------------------------------------------------------------
+  const perplexityChecks = [];
+  let perplexityScore = 0;
+
+  // Check 1: Crawler policy (PerplexityBot)
+  const perplexityBotBlocked = robotsDirectives.some((d) => d.includes('perplexitybot: noindex') || d.includes('perplexitybot: none'));
+  if (!perplexityBotBlocked && !isNoindex) {
+    perplexityScore += 25;
+    perplexityChecks.push({ name: 'Crawler Policy', passed: true, note: 'PerplexityBot allowed' });
+  } else {
+    perplexityChecks.push({ name: 'Crawler Policy', passed: false, note: 'Blocked by robots directive' });
+  }
+
+  // Check 2: Direct Definitional Lead (Copula in first paragraph)
+  const firstParagraph = paragraphs[0] || '';
+  const hasCopularLead = COPULA_RX.test(firstParagraph.slice(0, 160));
+  if (hasCopularLead) {
+    perplexityScore += 25;
+    perplexityChecks.push({ name: 'Definitional Lead', passed: true, note: 'Concise copular definition in opening passage' });
+  } else {
+    perplexityChecks.push({ name: 'Definitional Lead', passed: false, note: 'Opening passage lacks concise definitional copula ("X is Y")' });
+  }
+
+  // Check 3: Structured question headings
+  const questionHeadings = headings.filter((h) => QUESTION_RX.test(h.text.trim()));
+  if (questionHeadings.length >= 2) {
+    perplexityScore += 25;
+    perplexityChecks.push({ name: 'Question Density', passed: true, note: `${questionHeadings.length} interrogative headings found` });
+  } else if (questionHeadings.length === 1) {
+    perplexityScore += 15;
+    perplexityChecks.push({ name: 'Question Density', passed: true, note: '1 interrogative heading found' });
+  } else {
+    perplexityChecks.push({ name: 'Question Density', passed: false, note: 'No interrogative headings found (Q&A format optimizes extraction)' });
+  }
+
+  // Check 4: Structured data & tables for citation synthesis
+  if (tablesCount >= 1 || listsCount >= 2) {
+    perplexityScore += 25;
+    perplexityChecks.push({ name: 'Tabular / List Data', passed: true, note: `${tablesCount} table(s), ${listsCount} list(s) for direct citation` });
+  } else {
+    perplexityScore += 10;
+    perplexityChecks.push({ name: 'Tabular / List Data', passed: false, note: 'Limited tables or structured lists for bulleted answers' });
+  }
+
+  // -----------------------------------------------------------------
+  // 2. BING COPILOT READINESS
+  // -----------------------------------------------------------------
+  const bingChecks = [];
+  let bingScore = 0;
+
+  // Check 1: Bingbot allowed
+  const bingbotBlocked = robotsDirectives.some((d) => d.includes('bingbot: noindex'));
+  if (!bingbotBlocked && !isNoindex) {
+    bingScore += 25;
+    bingChecks.push({ name: 'Crawler Policy', passed: true, note: 'Bingbot allowed' });
+  } else {
+    bingChecks.push({ name: 'Crawler Policy', passed: false, note: 'Bingbot blocked' });
+  }
+
+  // Check 2: IndexNow protocol support / fast-indexing
+  const hasIndexNow = Boolean(
+    ctx.registries?.connections?.entries?.some((c) => c.provider === 'indexnow') ||
+    root.querySelector('link[rel="indexnow"]') ||
+    ctx.config?.indexnow
+  );
+  if (hasIndexNow) {
+    bingScore += 25;
+    bingChecks.push({ name: 'IndexNow Protocol', passed: true, note: 'IndexNow instant discovery integration detected' });
+  } else {
+    bingScore += 10;
+    bingChecks.push({ name: 'IndexNow Protocol', passed: false, note: 'IndexNow not configured; submission relies on standard crawl schedule' });
+  }
+
+  // Check 3: Schema.org JSON-LD completeness
+  const validSchemaBlocks = jsonLd.flatMap((j) => j.blocks || []).filter((b) => b['@type']);
+  const schemaTypes = validSchemaBlocks.map((b) => [].concat(b['@type']).join(',')).join('; ');
+  if (validSchemaBlocks.length >= 2) {
+    bingScore += 25;
+    bingChecks.push({ name: 'Structured Data', passed: true, note: `Rich schema graphs (${schemaTypes})` });
+  } else if (validSchemaBlocks.length === 1) {
+    bingScore += 15;
+    bingChecks.push({ name: 'Structured Data', passed: true, note: `Basic schema present (${schemaTypes})` });
+  } else {
+    bingChecks.push({ name: 'Structured Data', passed: false, note: 'No valid JSON-LD schema detected; Bing Copilot cards hindered' });
+  }
+
+  // Check 4: Deep page internal linking and canonical clarity
+  const canonicals = page.canonicals || [];
+  if (canonicals.length === 1) {
+    bingScore += 25;
+    bingChecks.push({ name: 'Canonical Authority', passed: true, note: `Canonical unambiguously specified (${canonicals[0]})` });
+  } else {
+    bingChecks.push({ name: 'Canonical Authority', passed: false, note: canonicals.length === 0 ? 'Missing canonical URL' : 'Multiple contradictory canonical tags' });
+  }
+
+  // -----------------------------------------------------------------
+  // 3. CHATGPT / SEARCHGPT READINESS
+  // -----------------------------------------------------------------
+  const chatGptChecks = [];
+  let chatGptScore = 0;
+
+  // Check 1: OAI-SearchBot / ChatGPT-User allowed
+  const oaiBlocked = robotsDirectives.some((d) => d.includes('oai-searchbot: noindex') || d.includes('chatgpt-user: noindex'));
+  if (!oaiBlocked && !isNoindex) {
+    chatGptScore += 25;
+    chatGptScore = Math.min(100, chatGptScore);
+    chatGptChecks.push({ name: 'SearchBot Policy', passed: true, note: 'OAI-SearchBot and ChatGPT-User allowed for search retrieval' });
+  } else {
+    chatGptChecks.push({ name: 'SearchBot Policy', passed: false, note: 'OAI-SearchBot / ChatGPT-User blocked by robots directives' });
+  }
+
+  // Check 2: RAG Chunkability (H2/H3 headers under 350 words per chunk)
+  const estimatedChunks = Math.max(1, Math.ceil(wordCount / 300));
+  const wordsPerHeading = headings.length > 0 ? Math.round(wordCount / headings.length) : wordCount;
+  if (headings.length >= 2 && wordsPerHeading >= 80 && wordsPerHeading <= 400) {
+    chatGptScore += 25;
+    chatGptChecks.push({ name: 'RAG Chunkability', passed: true, note: `Optimal chunk sizes (${wordsPerHeading} words/heading across ${headings.length} headings)` });
+  } else if (headings.length >= 1) {
+    chatGptScore += 15;
+    chatGptChecks.push({ name: 'RAG Chunkability', passed: true, note: `Sub-optimal chunking (${wordsPerHeading} words/heading)` });
+  } else {
+    chatGptChecks.push({ name: 'RAG Chunkability', passed: false, note: 'Monolithic content without H2/H3 hierarchy risks retrieval severance' });
+  }
+
+  // Check 3: Direct answer lead in first 100 words of section
+  const SUMMARY_RX = /\b(?:executive\s+summary|key\s+takeaways?|summary|overview|quick\s+facts|highlights?)\b/i;
+  const hasSummary = headings.some((h) => SUMMARY_RX.test(h.text));
+  if (hasSummary || hasCopularLead) {
+    chatGptScore += 25;
+    chatGptChecks.push({ name: 'Direct Answer Synthesis', passed: true, note: hasSummary ? 'Executive summary / key takeaways section present' : 'Immediate answer thesis in opening paragraph' });
+  } else {
+    chatGptChecks.push({ name: 'Direct Answer Synthesis', passed: false, note: 'Missing executive summary or lead key takeaways section' });
+  }
+
+  // Check 4: Quantitative claim grounding
+  const hasQuantitativeData = /(?:\b\d+(?:\.\d+)?%|\b\d+\s*ms\b|\b\d+\s*s\b|\$\d+(?:,\d{3})*)/.test(text);
+  if (hasQuantitativeData && wordCount >= 300) {
+    chatGptScore += 25;
+    chatGptChecks.push({ name: 'Claim Grounding', passed: true, note: 'Specific numerical metrics and quantitative facts present' });
+  } else if (wordCount >= 300) {
+    chatGptScore += 15;
+    chatGptChecks.push({ name: 'Claim Grounding', passed: false, note: 'Qualitative assertions without empirical statistics' });
+  } else {
+    chatGptChecks.push({ name: 'Claim Grounding', passed: false, note: 'Thin content lacks verifiable data' });
+  }
+
+  // Posture per engine
+  const posture = (s) => (s >= 80 ? 'optimal' : s >= 50 ? 'needs_optimization' : 'obstructed');
+  const perplexityStatus = posture(perplexityScore);
+  const bingStatus = posture(bingScore);
+  const chatGptStatus = posture(chatGptScore);
+
+  const compositeScore = Math.round((perplexityScore + bingScore + chatGptScore) / 3);
+
+  // Cross-engine prioritized recommendations
+  const recommendations = [];
+  if (!hasCopularLead) {
+    recommendations.push({
+      priority: 'high',
+      engine: 'all',
+      action: 'Add a concise definitional sentence ("X is Y") within the first 140 characters of the page',
+    });
+  }
+  if (!hasSummary) {
+    recommendations.push({
+      priority: 'medium',
+      engine: 'chatgpt',
+      action: 'Include a "Key Takeaways" or "Executive Summary" section at the top of long-form content',
+    });
+  }
+  if (questionHeadings.length < 2) {
+    recommendations.push({
+      priority: 'medium',
+      engine: 'perplexity',
+      action: 'Rephrase section headings as explicit user questions (e.g. "How does X work?", "What are the benefits of Y?")',
+    });
+  }
+  if (validSchemaBlocks.length < 2) {
+    recommendations.push({
+      priority: 'medium',
+      engine: 'bing_copilot',
+      action: 'Deploy structured JSON-LD schema (FAQPage, Article, or Product) to power Copilot card extraction',
+    });
+  }
+  if (!hasIndexNow) {
+    recommendations.push({
+      priority: 'low',
+      engine: 'bing_copilot',
+      action: 'Configure IndexNow protocol to notify Bing immediately of content updates',
+    });
+  }
+
+  return {
+    url: page.url,
+    fact_status: 'deterministic_engine_readiness_audit',
+    composite_readiness_score: compositeScore,
+    engines: {
+      perplexity: {
+        score: perplexityScore,
+        status: perplexityStatus,
+        primary_bot: 'PerplexityBot',
+        checks: perplexityChecks,
+      },
+      bing_copilot: {
+        score: bingScore,
+        status: bingStatus,
+        primary_bot: 'Bingbot',
+        checks: bingChecks,
+      },
+      chatgpt: {
+        score: chatGptScore,
+        status: chatGptStatus,
+        primary_bot: 'OAI-SearchBot',
+        checks: chatGptChecks,
+      },
+    },
+    comparison_matrix: [
+      { capability: 'Direct Definitional Lead', perplexity: hasCopularLead ? 'SUPPORTED' : 'MISSING', bing_copilot: hasCopularLead ? 'SUPPORTED' : 'OPTIONAL', chatgpt: hasCopularLead ? 'SUPPORTED' : 'MISSING' },
+      { capability: 'Q&A Heading Structure', perplexity: questionHeadings.length >= 2 ? 'HIGH' : 'LOW', bing_copilot: questionHeadings.length >= 2 ? 'SUPPORTED' : 'OPTIONAL', chatgpt: questionHeadings.length >= 2 ? 'OPTIMAL' : 'MODERATE' },
+      { capability: 'Structured Data (JSON-LD)', perplexity: validSchemaBlocks.length ? 'PARSED' : 'FALLBACK', bing_copilot: validSchemaBlocks.length ? 'REQUIRED_CARD' : 'OBSTRUCTED', chatgpt: validSchemaBlocks.length ? 'GROUNDED' : 'PLAIN_TEXT' },
+      { capability: 'RAG Section Chunkability', perplexity: wordsPerHeading <= 400 ? 'OPTIMAL' : 'LONG', bing_copilot: 'STANDARD', chatgpt: wordsPerHeading <= 400 ? 'OPTIMAL' : 'SEVERED' },
+      { capability: 'Crawler Directives', perplexity: perplexityBotBlocked ? 'BLOCKED' : 'ALLOWED', bing_copilot: bingbotBlocked ? 'BLOCKED' : 'ALLOWED', chatgpt: oaiBlocked ? 'BLOCKED' : 'ALLOWED' },
+    ],
+    recommendations,
+  };
+}