aeorank 2.0.0 → 2.1.0

package/dist/index.d.cts

@@ -362,7 +362,7 @@ declare function analyzeAllPages(siteData: SiteData): PageReview[];
 
 /**
  * Per-page AEO scoring.
- * Evaluates 14 of 26 criteria that apply at individual page level.
+ * Evaluates 14 of 28 criteria that apply at individual page level.
  * Produces a 0-100 AEO score per page.
  */
 

package/dist/index.d.ts

@@ -362,7 +362,7 @@ declare function analyzeAllPages(siteData: SiteData): PageReview[];
 
 /**
  * Per-page AEO scoring.
- * Evaluates 14 of 26 criteria that apply at individual page level.
+ * Evaluates 14 of 28 criteria that apply at individual page level.
  * Produces a 0-100 AEO score per page.
  */
 

package/dist/index.js

@@ -2069,40 +2069,58 @@ function auditSiteFromData(data) {
 
 // src/scoring.ts
 var WEIGHTS = {
-  // ─── Core Content (high weight - these determine real AI citation quality) ──
-  qa_content_format: 0.12,
-  original_data: 0.12,
+  // ─── Content Substance (~55%) ─────────────────────────────────────────────
+  // WHY an AI engine would cite you. These drive citation quality directly.
   topic_coherence: 0.14,
-  // NEW v2.0: biggest predictor of AI citation quality
-  fact_density: 0.08,
-  direct_answer_density: 0.07,
-  content_depth: 0.06,
-  // NEW v2.0: substantive content vs thin pages
-  // ─── Structure & Discovery (medium weight - technical readiness) ────────────
-  schema_markup: 0.08,
-  llms_txt: 0.08,
-  clean_html: 0.08,
-  entity_consistency: 0.08,
-  faq_section: 0.08,
-  internal_linking: 0.08,
-  // ─── Content Signals (moderate weight) ──────────────────────────────────────
-  content_freshness: 0.06,
-  table_list_extractability: 0.05,
-  query_answer_alignment: 0.06,
-  definition_patterns: 0.04,
-  author_schema_depth: 0.04,
-  content_cannibalization: 0.05,
-  visible_date_signal: 0.04,
-  semantic_html: 0.04,
-  // ─── Plumbing (low weight - nice to have but not what drives citations) ─────
-  robots_txt: 0.03,
-  sitemap_completeness: 0.03,
-  content_velocity: 0.03,
-  rss_feed: 0.02,
-  content_licensing: 0.03,
-  canonical_url: 0.02,
-  schema_coverage: 0.02,
-  speakable_schema: 0.02
+  // Topical authority - THE gating signal
+  original_data: 0.1,
+  // Unique value AI can't find elsewhere
+  content_depth: 0.07,
+  // Comprehensive vs thin coverage
+  fact_density: 0.06,
+  // Information density per page
+  direct_answer_density: 0.05,
+  // Direct answers to queries
+  qa_content_format: 0.05,
+  // Answer-shaped content structure
+  query_answer_alignment: 0.05,
+  // Relevance to actual AI queries
+  faq_section: 0.04,
+  // Structured Q&A pairs
+  // ─── Content Organization (~30%) ──────────────────────────────────────────
+  // HOW easily AI engines can extract and trust your content.
+  entity_consistency: 0.05,
+  // Brand authority and E-E-A-T
+  internal_linking: 0.04,
+  // Site structure and topic clusters
+  content_freshness: 0.04,
+  // Recency signals
+  schema_markup: 0.03,
+  // Structured data for discovery
+  author_schema_depth: 0.03,
+  // Expert attribution
+  table_list_extractability: 0.03,
+  // Extractable structured data
+  definition_patterns: 0.02,
+  // Clear definitions
+  visible_date_signal: 0.02,
+  // Publication date trust
+  semantic_html: 0.02,
+  // Clean semantic structure
+  clean_html: 0.02,
+  // Parseable markup
+  // ─── Technical Plumbing (~15%) ────────────────────────────────────────────
+  // WHETHER AI crawlers can find you. Table stakes with diminishing returns.
+  content_cannibalization: 0.02,
+  llms_txt: 0.02,
+  robots_txt: 0.02,
+  content_velocity: 0.02,
+  content_licensing: 0.02,
+  sitemap_completeness: 0.01,
+  canonical_url: 0.01,
+  rss_feed: 0.01,
+  schema_coverage: 0.01,
+  speakable_schema: 0.01
 };
 function calculateOverallScore(criteria) {
   let totalWeight = 0;
@@ -2113,7 +2131,13 @@ function calculateOverallScore(criteria) {
     totalWeight += weight;
   }
   if (totalWeight === 0) return 0;
-  return Math.round(weightedSum / totalWeight);
+  let score = Math.round(weightedSum / totalWeight);
+  const coherence = criteria.find((c) => c.criterion === "topic_coherence");
+  if (coherence && coherence.score < 6) {
+    const cap2 = 35 + coherence.score * 5;
+    score = Math.min(score, cap2);
+  }
+  return score;
 }
 
 // src/headless-fetch.ts
@@ -2332,32 +2356,37 @@ function buildDetailedFindings(results) {
 
 // src/narrative-generator.ts
 var CRITERION_WEIGHTS = {
-  llms_txt: 0.1,
-  schema_markup: 0.15,
-  qa_content_format: 0.15,
-  clean_html: 0.1,
-  entity_consistency: 0.1,
-  robots_txt: 0.05,
-  faq_section: 0.1,
+  // Content Substance (~55%)
+  topic_coherence: 0.14,
   original_data: 0.1,
-  internal_linking: 0.1,
-  semantic_html: 0.05,
-  content_freshness: 0.07,
-  sitemap_completeness: 0.05,
-  rss_feed: 0.03,
-  table_list_extractability: 0.07,
-  definition_patterns: 0.04,
-  direct_answer_density: 0.07,
-  content_licensing: 0.04,
-  author_schema_depth: 0.04,
-  fact_density: 0.05,
-  canonical_url: 0.04,
-  content_velocity: 0.03,
-  schema_coverage: 0.03,
-  speakable_schema: 0.03,
-  query_answer_alignment: 0.08,
-  content_cannibalization: 0.05,
-  visible_date_signal: 0.04
+  content_depth: 0.07,
+  fact_density: 0.06,
+  direct_answer_density: 0.05,
+  qa_content_format: 0.05,
+  query_answer_alignment: 0.05,
+  faq_section: 0.04,
+  // Content Organization (~30%)
+  entity_consistency: 0.05,
+  internal_linking: 0.04,
+  content_freshness: 0.04,
+  schema_markup: 0.03,
+  author_schema_depth: 0.03,
+  table_list_extractability: 0.03,
+  definition_patterns: 0.02,
+  visible_date_signal: 0.02,
+  semantic_html: 0.02,
+  clean_html: 0.02,
+  // Technical Plumbing (~15%)
+  content_cannibalization: 0.02,
+  llms_txt: 0.02,
+  robots_txt: 0.02,
+  content_velocity: 0.02,
+  content_licensing: 0.02,
+  sitemap_completeness: 0.01,
+  canonical_url: 0.01,
+  rss_feed: 0.01,
+  schema_coverage: 0.01,
+  speakable_schema: 0.01
 };
 var OPPORTUNITY_TEMPLATES = {
   llms_txt: {
@@ -2489,6 +2518,16 @@ var OPPORTUNITY_TEMPLATES = {
     name: "Add Visible Date Signals",
     effort: "Low",
     description: "Display publication/modification dates visibly using <time> elements and add datePublished/dateModified to JSON-LD schema."
+  },
+  topic_coherence: {
+    name: "Focus Content on Core Topics",
+    effort: "High",
+    description: 'Ensure blog content consistently covers your core expertise areas rather than scattering across unrelated topics. AI engines build authority models - a site about "Medicare coverage" that also publishes about humidifiers and groceries dilutes its topical authority.'
+  },
+  content_depth: {
+    name: "Increase Content Depth",
+    effort: "Medium",
+    description: "Expand articles to 1000+ words with structured H2/H3 sections, comparison tables, and expert analysis. Thin content (under 300 words) is rarely cited by AI engines. Deep, well-structured articles demonstrate expertise."
   }
 };
 function calculateImpact(score, weight, effort) {
@@ -2610,7 +2649,7 @@ function generatePitchNumbers(score, rawData, scorecard) {
   const passing = scorecard.filter((s) => s.score >= 7).length;
   metrics.push({
     metric: "Criteria Passing",
-    value: `${passing}/26`,
+    value: `${passing}/28`,
     significance: passing >= 18 ? "Excellent coverage across AEO dimensions" : passing >= 12 ? "Good foundation with room to improve remaining criteria" : `${26 - passing} criteria need attention for full AI visibility`
   });
   return metrics;
@@ -2802,20 +2841,23 @@ async function fetchMultiPageData(siteData, options) {
 
 // src/page-scorer.ts
 var PAGE_CRITERIA = {
-  schema_markup: { weight: 0.15, label: "Schema.org Structured Data" },
-  qa_content_format: { weight: 0.15, label: "Q&A Content Format" },
-  clean_html: { weight: 0.1, label: "Clean, Crawlable HTML" },
-  faq_section: { weight: 0.1, label: "FAQ Section Content" },
+  // Content Substance
   original_data: { weight: 0.1, label: "Original Data & Expert Content" },
-  query_answer_alignment: { weight: 0.08, label: "Query-Answer Alignment" },
-  content_freshness: { weight: 0.07, label: "Content Freshness Signals" },
-  table_list_extractability: { weight: 0.07, label: "Table & List Extractability" },
-  direct_answer_density: { weight: 0.07, label: "Direct Answer Paragraphs" },
-  semantic_html: { weight: 0.05, label: "Semantic HTML5 & Accessibility" },
-  fact_density: { weight: 0.05, label: "Fact & Data Density" },
-  definition_patterns: { weight: 0.04, label: "Definition Patterns" },
-  canonical_url: { weight: 0.04, label: "Canonical URL Strategy" },
-  visible_date_signal: { weight: 0.04, label: "Visible Date Signal" }
+  fact_density: { weight: 0.06, label: "Fact & Data Density" },
+  direct_answer_density: { weight: 0.05, label: "Direct Answer Paragraphs" },
+  qa_content_format: { weight: 0.05, label: "Q&A Content Format" },
+  query_answer_alignment: { weight: 0.05, label: "Query-Answer Alignment" },
+  faq_section: { weight: 0.04, label: "FAQ Section Content" },
+  // Content Organization
+  content_freshness: { weight: 0.04, label: "Content Freshness Signals" },
+  schema_markup: { weight: 0.03, label: "Schema.org Structured Data" },
+  table_list_extractability: { weight: 0.03, label: "Table & List Extractability" },
+  definition_patterns: { weight: 0.02, label: "Definition Patterns" },
+  visible_date_signal: { weight: 0.02, label: "Visible Date Signal" },
+  semantic_html: { weight: 0.02, label: "Semantic HTML5 & Accessibility" },
+  clean_html: { weight: 0.02, label: "Clean, Crawlable HTML" },
+  // Technical Plumbing
+  canonical_url: { weight: 0.01, label: "Canonical URL Strategy" }
 };
 function extractJsonLdBlocks(html) {
   const blocks = [];
@@ -3667,32 +3709,37 @@ function buildLinkGraph(pages, domain, homepageUrl) {
 
 // src/fix-engine.ts
 var CRITERION_WEIGHTS2 = {
-  llms_txt: 0.1,
-  schema_markup: 0.15,
-  qa_content_format: 0.15,
-  clean_html: 0.1,
-  entity_consistency: 0.1,
-  robots_txt: 0.05,
-  faq_section: 0.1,
+  // Content Substance (~55%)
+  topic_coherence: 0.14,
   original_data: 0.1,
-  internal_linking: 0.1,
-  semantic_html: 0.05,
-  content_freshness: 0.07,
-  sitemap_completeness: 0.05,
-  rss_feed: 0.03,
-  table_list_extractability: 0.07,
-  definition_patterns: 0.04,
-  direct_answer_density: 0.07,
-  content_licensing: 0.04,
-  author_schema_depth: 0.04,
-  fact_density: 0.05,
-  canonical_url: 0.04,
-  content_velocity: 0.03,
-  schema_coverage: 0.03,
-  speakable_schema: 0.03,
-  query_answer_alignment: 0.08,
-  content_cannibalization: 0.05,
-  visible_date_signal: 0.04
+  content_depth: 0.07,
+  fact_density: 0.06,
+  direct_answer_density: 0.05,
+  qa_content_format: 0.05,
+  query_answer_alignment: 0.05,
+  faq_section: 0.04,
+  // Content Organization (~30%)
+  entity_consistency: 0.05,
+  internal_linking: 0.04,
+  content_freshness: 0.04,
+  schema_markup: 0.03,
+  author_schema_depth: 0.03,
+  table_list_extractability: 0.03,
+  definition_patterns: 0.02,
+  visible_date_signal: 0.02,
+  semantic_html: 0.02,
+  clean_html: 0.02,
+  // Technical Plumbing (~15%)
+  content_cannibalization: 0.02,
+  llms_txt: 0.02,
+  robots_txt: 0.02,
+  content_velocity: 0.02,
+  content_licensing: 0.02,
+  sitemap_completeness: 0.01,
+  canonical_url: 0.01,
+  rss_feed: 0.01,
+  schema_coverage: 0.01,
+  speakable_schema: 0.01
 };
 var PHASE_CONFIG = [
   {
@@ -3715,7 +3762,9 @@ var PHASE_CONFIG = [
       "content_freshness",
       "table_list_extractability",
       "query_answer_alignment",
-      "visible_date_signal"
+      "visible_date_signal",
+      "topic_coherence",
+      "content_depth"
     ]
   },
   {
@@ -4619,6 +4668,55 @@ Summarization: yes`,
       affectedPages: affected,
       pageCount: affected?.length
     }];
+  },
+  topic_coherence: (c) => {
+    if (c.score >= 10) return [];
+    const impact = impactFromScore(c.score);
+    const effort = effortForCriterion("topic_coherence", c.score);
+    return [{
+      id: "fix-topic-coherence",
+      criterion: c.criterion_label,
+      criterionId: c.criterion,
+      title: "Focus blog content on core expertise",
+      description: "Ensure blog content consistently covers your core topic areas. Scattered content across unrelated topics weakens AI engine authority signals.",
+      impact,
+      effort: effort === "trivial" ? "low" : effort,
+      impactScore: 0,
+      category: "content",
+      steps: [
+        "Identify 2-3 core expertise areas your brand is known for",
+        "Audit existing blog posts and remove or consolidate off-topic content",
+        "Create a content calendar focused on core topics",
+        "Use topic clusters: pillar pages linking to supporting articles within the same niche"
+      ],
+      successCriteria: "80%+ of blog content covers core expertise areas with consistent topic focus"
+    }];
+  },
+  content_depth: (c, pages) => {
+    if (c.score >= 10) return [];
+    const impact = impactFromScore(c.score);
+    const effort = effortForCriterion("content_depth", c.score);
+    const affected = getAffectedPages("content_depth", pages);
+    return [{
+      id: "fix-content-depth",
+      criterion: c.criterion_label,
+      criterionId: c.criterion,
+      title: "Increase content depth and structure",
+      description: "Expand thin content with more detail, examples, and structured sections. AI engines prefer comprehensive articles with clear heading hierarchies.",
+      impact,
+      effort: effort === "trivial" ? "low" : effort,
+      impactScore: 0,
+      category: "content",
+      steps: [
+        "Aim for 1000+ words per article with expert analysis and examples",
+        "Use H2/H3 subheadings every 200-300 words for clear structure",
+        "Add comparison tables, numbered steps, and data points",
+        "Remove or expand thin pages (under 300 words) that dilute site quality"
+      ],
+      successCriteria: "Average article length exceeds 1000 words with 5+ subheadings per page",
+      affectedPages: affected,
+      pageCount: affected?.length
+    }];
   }
 };
 function generateFixPlan(domain, overallScore, criteria, pagesReviewed, linkGraph) {