aeorank 1.6.0 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # AEORank
 
-Score any website for AI engine visibility across 26 criteria. Pure HTTP + regex - zero API keys required.
+Score any website for AI engine visibility across 28 criteria. Pure HTTP + regex - zero API keys required.
 
 [![npm version](https://img.shields.io/npm/v/aeorank.svg)](https://www.npmjs.com/package/aeorank)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -35,42 +35,96 @@ import { audit } from 'aeorank';
 
 const result = await audit('example.com');
 console.log(result.overallScore);  // 0-100
-console.log(result.scorecard);     // 26 criteria with scores
+console.log(result.scorecard);     // 28 criteria with scores
 console.log(result.opportunities); // Prioritized improvements
 ```
 
 ## What It Checks
 
-AEORank evaluates 26 criteria across 4 categories that determine how AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews) discover, parse, and cite your content:
-
-| # | Criterion | Weight | Category |
-|---|-----------|--------|----------|
-| 1 | llms.txt File | 10% | Discovery |
-| 2 | Schema.org Structured Data | 15% | Structure |
-| 3 | Q&A Content Format | 15% | Content |
-| 4 | Clean, Crawlable HTML | 10% | Structure |
-| 5 | Entity Authority & NAP Consistency | 10% | Authority |
-| 6 | robots.txt for AI Crawlers | 5% | Discovery |
-| 7 | Comprehensive FAQ Section | 10% | Content |
-| 8 | Original Data & Expert Analysis | 10% | Content |
-| 9 | Internal Linking Structure | 10% | Structure |
-| 10 | Semantic HTML5 & Accessibility | 5% | Structure |
-| 11 | Content Freshness Signals | 7% | Content |
-| 12 | Sitemap Completeness | 5% | Discovery |
-| 13 | RSS/Atom Feed | 3% | Discovery |
-| 14 | Table & List Extractability | 7% | Structure |
-| 15 | Definition Patterns | 4% | Content |
-| 16 | Direct Answer Paragraphs | 7% | Content |
-| 17 | Content Licensing & AI Permissions | 4% | Discovery |
-| 18 | Author & Expert Schema | 4% | Authority |
-| 19 | Fact & Data Density | 5% | Content |
-| 20 | Canonical URL Strategy | 4% | Structure |
-| 21 | Content Publishing Velocity | 3% | Content |
-| 22 | Schema Coverage & Depth | 3% | Structure |
-| 23 | Speakable Schema | 3% | Structure |
-| 24 | Query-Answer Alignment | 8% | Content |
-| 25 | Content Cannibalization | 5% | Content |
-| 26 | Visible Date Signal | 4% | Content |
+AEORank evaluates 28 criteria that determine how AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews) discover, parse, and cite your content. Criteria are organized into three tiers by impact on real-world AI citations:
+
+### Scoring Tiers (by importance)
+
+**Content Substance (~55%)** - *Why* an AI engine would cite you:
+
+| Criterion | Weight | What it measures |
+|-----------|--------|------------------|
+| Topic Coherence | 14% | Blog content focus on core expertise vs scattered topics |
+| Original Data & Expert Analysis | 10% | Proprietary research, case studies, unique data points |
+| Content Depth | 7% | Article length, heading structure, deep vs thin pages |
+| Fact & Data Density | 6% | Specific numbers, statistics, data points per page |
+| Direct Answer Paragraphs | 5% | Concise answer paragraphs after question headings |
+| Q&A Content Format | 5% | Question-format headings (What, How, Why) with answers |
+| Query-Answer Alignment | 5% | Every question heading followed by a direct answer |
+| Comprehensive FAQ Section | 4% | Dedicated FAQ with FAQPage schema markup |
+
+**Content Organization (~30%)** - *How* easily AI can extract and trust your content:
+
+| Criterion | Weight | What it measures |
+|-----------|--------|------------------|
+| Entity Authority & NAP Consistency | 5% | Organization schema, consistent name/address/phone |
+| Internal Linking Structure | 4% | Topic clusters, breadcrumbs, reachability from homepage |
+| Content Freshness Signals | 4% | dateModified schema, visible dates, recent content |
+| Schema.org Structured Data | 3% | JSON-LD blocks (Organization, Article, FAQPage, etc.) |
+| Author & Expert Schema | 3% | Person schema with credentials and expertise |
+| Table & List Extractability | 3% | HTML tables with headers, ordered/unordered lists |
+| Definition Patterns | 2% | Clear "X is defined as..." patterns for key terms |
+| Visible Date Signal | 2% | Visible publication dates with `<time>` elements |
+| Semantic HTML5 & Accessibility | 2% | Semantic elements (main, article, nav), ARIA, lang |
+| Clean, Crawlable HTML | 2% | HTTPS, meta tags, proper heading hierarchy |
+
+**Technical Plumbing (~15%)** - *Whether* AI crawlers can find you (table stakes):
+
+| Criterion | Weight | What it measures |
+|-----------|--------|------------------|
+| Content Cannibalization | 2% | Overlapping pages competing for the same topic |
+| llms.txt File | 2% | /llms.txt with site description and key page URLs |
+| robots.txt for AI Crawlers | 2% | GPTBot, ClaudeBot, PerplexityBot access |
+| Content Publishing Velocity | 2% | Regular publishing cadence in sitemap |
+| Content Licensing & AI Permissions | 2% | /ai.txt file, license schema for AI usage |
+| Sitemap Completeness | 1% | sitemap.xml with lastmod dates |
+| Canonical URL Strategy | 1% | Self-referencing canonical tags |
+| RSS/Atom Feed | 1% | RSS feed linked from homepage |
+| Schema Coverage & Depth | 1% | Schema markup on inner pages, not just homepage |
+| Speakable Schema | 1% | SpeakableSpecification for voice assistants |
+
+> **Coherence Gate:** Sites with topic coherence below 6/10 are score-capped regardless of technical perfection. A scattered site with perfect robots.txt, llms.txt, and schema will score lower than a focused site with mediocre technical implementation.
+
+<details>
+<summary>All 28 criteria (numbered list)</summary>
+
+| # | Criterion | Weight | Tier |
+|---|-----------|--------|------|
+| 1 | llms.txt File | 2% | Plumbing |
+| 2 | Schema.org Structured Data | 3% | Organization |
+| 3 | Q&A Content Format | 5% | Substance |
+| 4 | Clean, Crawlable HTML | 2% | Organization |
+| 5 | Entity Authority & NAP Consistency | 5% | Organization |
+| 6 | robots.txt for AI Crawlers | 2% | Plumbing |
+| 7 | Comprehensive FAQ Section | 4% | Substance |
+| 8 | Original Data & Expert Analysis | 10% | Substance |
+| 9 | Internal Linking Structure | 4% | Organization |
+| 10 | Semantic HTML5 & Accessibility | 2% | Organization |
+| 11 | Content Freshness Signals | 4% | Organization |
+| 12 | Sitemap Completeness | 1% | Plumbing |
+| 13 | RSS/Atom Feed | 1% | Plumbing |
+| 14 | Table & List Extractability | 3% | Organization |
+| 15 | Definition Patterns | 2% | Organization |
+| 16 | Direct Answer Paragraphs | 5% | Substance |
+| 17 | Content Licensing & AI Permissions | 2% | Plumbing |
+| 18 | Author & Expert Schema | 3% | Organization |
+| 19 | Fact & Data Density | 6% | Substance |
+| 20 | Canonical URL Strategy | 1% | Plumbing |
+| 21 | Content Publishing Velocity | 2% | Plumbing |
+| 22 | Schema Coverage & Depth | 1% | Plumbing |
+| 23 | Speakable Schema | 1% | Plumbing |
+| 24 | Query-Answer Alignment | 5% | Substance |
+| 25 | Content Cannibalization | 2% | Plumbing |
+| 26 | Visible Date Signal | 2% | Organization |
+| 27 | Topic Coherence | 14% | Substance |
+| 28 | Content Depth | 7% | Substance |
+
+</details>
 
 ## CLI Options
 
@@ -99,7 +153,7 @@ Use the built-in action to gate deployments on AEO score:
 
 ```yaml
 - name: AEO Audit
-  uses: AEO-Content-Inc/aeorank@v1
+  uses: AEO-Content-Inc/aeorank@v2
   with:
     domain: example.com
     threshold: 70
@@ -119,7 +173,7 @@ Or use `npx` directly:
 Run a complete audit. Returns `AuditResult` with:
 
 - `overallScore` - 0-100 weighted score
-- `scorecard` - 26 `ScoreCardItem` entries (criterion, score 0-10, status, key findings)
+- `scorecard` - 28 `ScoreCardItem` entries (criterion, score 0-10, status, key findings)
 - `detailedFindings` - Per-criterion findings with severity
 - `opportunities` - Prioritized improvements with effort/impact
 - `pitchNumbers` - Key metrics (schema types, AI crawler access, etc.)
@@ -257,7 +311,7 @@ Use `--no-headless` to skip SPA rendering (faster but may produce lower scores f
 
 ## Full-Site Crawl
 
-By default, AEORank audits the homepage plus ~20 discovered pages. For deeper analysis, enable `--full-crawl` to BFS-crawl every discoverable page:
+By default, AEORank audits the homepage plus up to 50 blog pages from the sitemap. For deeper analysis, enable `--full-crawl` to BFS-crawl every discoverable page:
 
 ```bash
 npx aeorank example.com --full-crawl                    # Up to 200 pages
@@ -294,9 +348,26 @@ console.log(crawlResult.discoveredUrls.length); // Total URLs found
 
 AEORank scores each individual page (0-100) against the 14 criteria that apply at page level. Instead of only seeing "your site scores 62," you get "your /about page scores 45, your /blog/guide scores 78."
 
-The 14 per-page criteria: Schema.org Structured Data, Q&A Content Format, Clean Crawlable HTML, FAQ Section Content, Original Data & Expert Content, Query-Answer Alignment, Content Freshness Signals, Table & List Extractability, Direct Answer Paragraphs, Semantic HTML5 & Accessibility, Fact & Data Density, Definition Patterns, Canonical URL Strategy, Visible Date Signal.
-
-The remaining 12 criteria (llms.txt, robots.txt, sitemap, RSS, entity consistency, internal linking, content licensing, author schema, content velocity, schema coverage, speakable schema, content cannibalization) are site-level only.
+The 14 per-page criteria follow the same substance-first weighting as the site-level score:
+
+| Tier | Per-Page Criteria | Weight |
+|------|-------------------|--------|
+| **Substance** | Original Data & Expert Content | 10% |
+| | Fact & Data Density | 6% |
+| | Direct Answer Paragraphs | 5% |
+| | Q&A Content Format | 5% |
+| | Query-Answer Alignment | 5% |
+| | FAQ Section Content | 4% |
+| **Organization** | Content Freshness Signals | 4% |
+| | Schema.org Structured Data | 3% |
+| | Table & List Extractability | 3% |
+| | Definition Patterns | 2% |
+| | Visible Date Signal | 2% |
+| | Semantic HTML5 & Accessibility | 2% |
+| | Clean, Crawlable HTML | 2% |
+| **Plumbing** | Canonical URL Strategy | 1% |
+
+The remaining 14 criteria are site-level only: llms.txt, robots.txt, sitemap, RSS, entity consistency, internal linking, content licensing, author schema, content velocity, schema coverage, speakable schema, content cannibalization, topic coherence, and content depth.
 
 ### CLI Output
 
@@ -449,7 +520,7 @@ console.log(result.comparison.tied);              // Criteria with equal scores
 
 ## Benchmark Dataset
 
-The `data/` directory contains the largest open dataset of AI visibility scores - **13,619 domains** scored across 26 criteria, including **4,328 Y Combinator startups** across 48 batches (W06-W26):
+The `data/` directory contains the largest open dataset of AI visibility scores - **13,619 domains** scored across 28 criteria, including **4,328 Y Combinator startups** across 48 batches (W06-W26):
 
 | File | Contents |
 |------|----------|

package/dist/browser.d.ts

@@ -173,7 +173,7 @@ interface SiteData {
     redirectedTo: string | null;
     /** Set when homepage is a parked/for-sale/lost domain */
     parkedReason: string | null;
-    /** Sampled blog/content pages from sitemap (up to 5) */
+    /** Sampled blog/content pages from sitemap (up to 50) */
     blogSample?: FetchResult[];
     /** Full-crawl statistics (set when --full-crawl is used) */
     crawlStats?: {
@@ -376,7 +376,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.
  */