aeorank 3.1.0 → 3.2.0

package/README.md

@@ -1,6 +1,6 @@
 # AEORank
 
-Score any website for AI engine visibility across 36 criteria in a 5-pillar framework. Pure HTTP + regex - zero API keys, under 10 seconds.
+Score any website for AI engine visibility across 40 criteria in a 5-pillar framework. Pure HTTP + regex - zero API keys, under 10 seconds.
 
 [![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,7 +35,7 @@ import { audit } from 'aeorank';
 
 const result = await audit('example.com');
 console.log(result.overallScore);  // 0-100
-console.log(result.scorecard);     // 36 criteria with scores, pillars, weights
+console.log(result.scorecard);     // 40 criteria with scores, pillars, weights
 console.log(result.pillarScores);  // { answerReadiness, contentStructure, ... }
 console.log(result.topFixes);      // Top 3 highest-impact fixes
 console.log(result.opportunities); // Prioritized improvements
@@ -43,7 +43,7 @@ console.log(result.opportunities); // Prioritized improvements
 
 ## What It Checks
 
-AEORank evaluates 36 criteria that determine how AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews) discover, parse, and cite your content. Criteria are organized into five pillars:
+AEORank evaluates 40 criteria that determine how AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews) discover, parse, and cite your content. Criteria are organized into five pillars:
 
 ### 5-Pillar Framework
 
@@ -60,6 +60,8 @@ AEORank evaluates 36 criteria that determine how AI engines (ChatGPT, Claude, Pe
 | Cross-Page Duplicate Content | 3% | Same paragraphs copy-pasted across multiple pages |
 | Answer-First Placement | 3% | Answer block in first 300 words, no throat-clearing openers |
 | Evidence Packaging | 3% | Inline citations, attribution phrases, sources sections |
+| Helpful Purpose Alignment | 3% | Whether pages solve the promised visitor task vs reading like search-first filler |
+| First-Hand Experience Signals | 3% | Concrete evidence of direct use, testing, implementation, or lived experience |
 
 **Pillar 2: Content Structure (~25%)** - *How* AI extracts your answers:
 
@@ -82,6 +84,8 @@ AEORank evaluates 36 criteria that determine how AI engines (ChatGPT, Claude, Pe
 | Content Freshness Signals | 4% | dateModified schema, visible dates, recent content |
 | Author & Expert Schema | 3% | Person schema with credentials and expertise |
 | Schema.org Structured Data | 3% | JSON-LD blocks (Organization, Article, FAQPage, etc.) |
+| Creator Transparency | 2% | Visible bylines, author pages, and reviewer attribution where expected |
+| Methodology Transparency | 2% | Whether pages explain how they were tested, researched, reviewed, or updated |
 
 **Pillar 4: Technical Foundation (~10%)** - *How* easily AI parses your pages:
 
@@ -89,70 +93,74 @@ AEORank evaluates 36 criteria that determine how AI engines (ChatGPT, Claude, Pe
 |-----------|--------|------------------|
 | Semantic HTML5 & Accessibility | 2% | Semantic elements (main, article, nav), ARIA, lang |
 | Clean, Crawlable HTML | 2% | HTTPS, meta tags, proper heading hierarchy |
-| Visible Date Signal | 2% | Visible publication dates with `<time>` elements |
+| Visible Date Signal | 1.5% | Visible publication dates with `<time>` elements |
 | Extraction Friction | 2% | Sentence length, voice-friendly leads, jargon density |
-| Image Context for AI | 1% | Figure/figcaption, descriptive alt text, contextual placement |
-| Schema Coverage & Depth | 1% | Schema markup on inner pages, not just homepage |
-| Speakable Schema | 1% | SpeakableSpecification for voice assistants |
+| Image Context for AI | 0.5% | Figure/figcaption, descriptive alt text, contextual placement |
+| Schema Coverage & Depth | 0% | Schema markup on inner pages, not just homepage |
+| Speakable Schema | 0% | SpeakableSpecification for voice assistants |
 
 **Pillar 5: AI Discovery (~10%)** - *Whether* AI crawlers can find you:
 
 | 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 |
+| llms.txt File | 1% | /llms.txt with site description and key page URLs |
+| robots.txt for AI Crawlers | 1% | 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 |
+| Content Licensing & AI Permissions | 1% | /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 |
+| Canonical URL Strategy | 0.5% | Self-referencing canonical tags |
+| RSS/Atom Feed | 0% | RSS feed linked from homepage |
 
 > **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.
 >
 > **Duplication Gate:** Per-page scores are capped when duplicate content blocks are detected. A page with 3+ identical copy-pasted paragraphs cannot score above 35/75 regardless of other signals — LLMs will flag it as low-quality content.
 
 <details>
-<summary>All 36 criteria (numbered list)</summary>
+<summary>All 40 criteria (numbered list)</summary>
 
 | # | Criterion | Weight | Pillar |
 |---|-----------|--------|--------|
-| 1 | llms.txt File | 2% | AI Discovery |
+| 1 | llms.txt File | 1% | AI Discovery |
 | 2 | Schema.org Structured Data | 3% | Trust & Authority |
 | 3 | Q&A Content Format | 4% | Content Structure |
 | 4 | Clean, Crawlable HTML | 2% | Technical Foundation |
 | 5 | Entity Authority & NAP Consistency | 5% | Trust & Authority |
-| 6 | robots.txt for AI Crawlers | 2% | AI Discovery |
+| 6 | robots.txt for AI Crawlers | 1% | AI Discovery |
 | 7 | Comprehensive FAQ Section | 3% | Content Structure |
 | 8 | Original Data & Expert Analysis | 10% | Answer Readiness |
 | 9 | Internal Linking Structure | 4% | Trust & Authority |
 | 10 | Semantic HTML5 & Accessibility | 2% | Technical Foundation |
 | 11 | Content Freshness Signals | 4% | Trust & Authority |
 | 12 | Sitemap Completeness | 1% | AI Discovery |
-| 13 | RSS/Atom Feed | 1% | AI Discovery |
+| 13 | RSS/Atom Feed | 0% | AI Discovery |
 | 14 | Table & List Extractability | 3% | Content Structure |
-| 15 | Definition Patterns | 2% | Content Structure |
+| 15 | Definition Patterns | 1.5% | Content Structure |
 | 16 | Direct Answer Paragraphs | 5% | Content Structure |
-| 17 | Content Licensing & AI Permissions | 2% | AI Discovery |
+| 17 | Content Licensing & AI Permissions | 1% | AI Discovery |
 | 18 | Author & Expert Schema | 3% | Trust & Authority |
 | 19 | Fact & Data Density | 6% | Answer Readiness |
-| 20 | Canonical URL Strategy | 1% | AI Discovery |
+| 20 | Canonical URL Strategy | 0.5% | AI Discovery |
 | 21 | Content Publishing Velocity | 2% | AI Discovery |
-| 22 | Schema Coverage & Depth | 1% | Technical Foundation |
-| 23 | Speakable Schema | 1% | Technical Foundation |
+| 22 | Schema Coverage & Depth | 0% | Technical Foundation |
+| 23 | Speakable Schema | 0% | Technical Foundation |
 | 24 | Query-Answer Alignment | 4% | Content Structure |
 | 25 | Content Cannibalization | 2% | AI Discovery |
-| 26 | Visible Date Signal | 2% | Technical Foundation |
+| 26 | Visible Date Signal | 1.5% | Technical Foundation |
 | 27 | Topic Coherence | 14% | Answer Readiness |
 | 28 | Content Depth | 7% | Answer Readiness |
-| 29 | Citation-Ready Writing | 4% | Answer Readiness |
-| 30 | Answer-First Placement | 3% | Answer Readiness |
-| 31 | Evidence Packaging | 3% | Answer Readiness |
-| 32 | Entity Disambiguation | 2% | Content Structure |
-| 33 | Extraction Friction | 2% | Technical Foundation |
-| 34 | Image Context for AI | 1% | Technical Foundation |
-| 35 | Duplicate Content Blocks | 5% | Answer Readiness |
-| 36 | Cross-Page Duplicate Content | 3% | Answer Readiness |
+| 29 | Helpful Purpose Alignment | 3% | Answer Readiness |
+| 30 | First-Hand Experience Signals | 3% | Answer Readiness |
+| 31 | Creator Transparency | 2% | Trust & Authority |
+| 32 | Methodology Transparency | 2% | Trust & Authority |
+| 33 | Citation-Ready Writing | 4% | Answer Readiness |
+| 34 | Answer-First Placement | 3% | Answer Readiness |
+| 35 | Evidence Packaging | 3% | Answer Readiness |
+| 36 | Entity Disambiguation | 2% | Content Structure |
+| 37 | Extraction Friction | 2% | Technical Foundation |
+| 38 | Image Context for AI | 0.5% | Technical Foundation |
+| 39 | Duplicate Content Blocks | 5% | Answer Readiness |
+| 40 | Cross-Page Duplicate Content | 3% | Answer Readiness |
 
 </details>
 
@@ -183,7 +191,7 @@ Use the built-in action to gate deployments on AEO score:
 
 ```yaml
 - name: AEO Audit
-  uses: AEO-Content-Inc/aeorank@v2
+  uses: AEO-Content-Inc/aeorank@v3
   with:
     domain: example.com
     threshold: 70
@@ -203,7 +211,7 @@ Or use `npx` directly:
 Run a complete audit. Returns `AuditResult` with:
 
 - `overallScore` - 0-100 weighted score
-- `scorecard` - 36 `ScoreCardItem` entries (criterion, score 0-10, status, key findings)
+- `scorecard` - 40 `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.)
@@ -225,10 +233,10 @@ Run a complete audit. Returns `AuditResult` with:
 
 ### `scorePage(html, url?)`
 
-Score a single HTML page against 21 per-page AEO criteria. Returns `PageScoreResult` with:
+Score a single HTML page against 25 per-page AEO criteria. Returns `PageScoreResult` with:
 
 - `aeoScore` - 0-75 weighted score (capped; duplication gate may lower further)
-- `criterionScores` - 21 `PageCriterionScore` entries (criterion, score 0-10, weight)
+- `criterionScores` - 25 `PageCriterionScore` entries (criterion, score 0-10, weight)
 
 ### `scoreAllPages(siteData)`
 
@@ -388,9 +396,9 @@ console.log(crawlResult.discoveredUrls.length); // Total URLs found
 
 ## Per-Page Scoring
 
-AEORank scores each individual page (0-75) against the 21 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 72."
+AEORank scores each individual page (0-75) against the 25 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 72."
 
-The 21 per-page criteria follow the same pillar-first weighting as the site-level score:
+The 25 per-page criteria follow the same pillar-first weighting as the site-level score:
 
 | Pillar | Per-Page Criteria | Weight |
 |--------|-------------------|--------|
@@ -400,21 +408,25 @@ The 21 per-page criteria follow the same pillar-first weighting as the site-leve
 | | Citation-Ready Writing | 4% |
 | | Answer-First Placement | 3% |
 | | Evidence Packaging | 3% |
+| | Helpful Purpose Alignment | 3% |
+| | First-Hand Experience Signals | 3% |
 | **Content Structure** | Direct Answer Paragraphs | 5% |
 | | Q&A Content Format | 4% |
 | | Query-Answer Alignment | 4% |
 | | FAQ Section Content | 3% |
 | | Table & List Extractability | 3% |
-| | Definition Patterns | 2% |
+| | Definition Patterns | 1.5% |
 | | Entity Disambiguation | 2% |
 | **Trust & Authority** | Content Freshness Signals | 4% |
 | | Schema.org Structured Data | 3% |
+| | Creator Transparency | 2% |
+| | Methodology Transparency | 2% |
 | **Technical Foundation** | Semantic HTML5 & Accessibility | 2% |
 | | Clean, Crawlable HTML | 2% |
-| | Visible Date Signal | 2% |
+| | Visible Date Signal | 1.5% |
 | | Extraction Friction | 2% |
-| | Image Context for AI | 1% |
-| **AI Discovery** | Canonical URL Strategy | 1% |
+| | Image Context for AI | 0.5% |
+| **AI Discovery** | Canonical URL Strategy | 0.5% |
 
 The remaining 15 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, cross-page duplication, topic coherence, and content depth.
 
@@ -445,7 +457,7 @@ import type { PageScoreResult, PageCriterionScore } from 'aeorank';
 // Score a single page
 const result = scorePage(html, url);
 console.log(result.aeoScore);         // 0-75 (capped for single pages)
-console.log(result.criterionScores);  // 21 per-criterion scores
+console.log(result.criterionScores);  // 25 per-criterion scores
 console.log(result.scoreCapped);      // true if score was capped at 75
 
 // Score all pages from site data
@@ -574,13 +586,21 @@ console.log(result.comparison.tied);              // Criteria with equal scores
 
 ## Changelog
 
+### v3.1.1 - Duplicate Detection False-Positive Fix
+
+Duplicate-content detection now ignores short metadata rows like `Deadline:` and `Decision timeline:` so structured guides do not get penalized for repeated timeline labels. Shared duplicate-matching logic is now used by both page scoring and site-wide crawling.
+
 ### v3.1.0 - Duplicate Content Detection
 
 2 new criteria (#35-#36): Duplicate Content Blocks (intra-page, 5%) and Cross-Page Duplicate Content (3%). Detects identical text blocks within pages and copy-pasted paragraphs across pages using shingle-based Jaccard similarity. Boilerplate filtering excludes CTAs, signups, and template content from false positives. Duplication gate caps per-page scores when severe duplication is found. CLI now shows duplicate section names inline per page.
 
+### v3.2.0 - Helpful Content Criteria
+
+Added 4 new criteria: Helpful Purpose Alignment, First-Hand Experience Signals, Creator Transparency, and Methodology Transparency. The model now scores 40 total criteria and 25 page-level criteria while explicitly avoiding any "AI-written" detector.
+
 ### v3.0.0 - 5-Pillar Framework & 6 New Criteria
 
-Scoring Engine v2: 28 → 34 criteria (now 36) with 5-pillar framework (Answer Readiness, Content Structure, Trust & Authority, Technical Foundation, AI Discovery). 6 new criteria targeting citation quality, evidence packaging, and extraction friction. Per-pillar sub-scores, top-3 fixes, client-friendly names. Single-page score cap at 75. 15 per-page quality checks (up from 12).
+Scoring Engine v2: 28 → 34 criteria with 5-pillar framework (Answer Readiness, Content Structure, Trust & Authority, Technical Foundation, AI Discovery). 6 new criteria targeting citation quality, evidence packaging, and extraction friction. Per-pillar sub-scores, top-3 fixes, client-friendly names. Single-page score cap at 75.
 
 ### v2.3.0 - Coherence Scaling & Script Stripping
 
@@ -604,11 +624,11 @@ Internal linking analysis with orphan/pillar/hub detection, topic clusters. Phas
 
 ### v1.5.0 - Per-Page Scoring
 
-Individual page scores (0-100) against 14 page-level criteria. Top/bottom page rankings.
+Individual page scores against the initial page-level scoring model. Top/bottom page rankings.
 
 ## Benchmark Dataset
 
-The `data/` directory contains the largest open dataset of AI visibility scores - **13,619 domains** scored across 36 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 40 criteria, including **4,328 Y Combinator startups** across 48 batches (W06-W26):
 
 | File | Contents |
 |------|----------|

package/dist/browser.d.ts

@@ -64,7 +64,7 @@ declare function buildLinkGraph(pages: FetchResult[], domain: string, homepageUr
 
 /**
  * V2 Pillar Framework — 5-pillar scoring model.
- * Maps all 36 criteria into pillars, computes sub-scores,
+ * Maps all 40 criteria into pillars, computes sub-scores,
  * provides client-friendly names, and calculates top-3 fixes.
  */
 
@@ -320,7 +320,7 @@ interface SitemapDateAnalysis {
 declare function countRecentSitemapDates(sitemapText: string): SitemapDateAnalysis;
 declare function extractRawDataSummary(data: SiteData): RawDataSummary;
 /**
- * Run all 36 criteria checks using pre-fetched site data.
+ * Run all 40 criteria checks using pre-fetched site data.
  * All functions are synchronous (no HTTP calls) - data was already fetched.
  */
 declare function auditSiteFromData(data: SiteData): CriterionResult[];
@@ -456,7 +456,7 @@ declare function analyzeAllPages(siteData: SiteData): PageReview[];
 
 /**
  * Per-page AEO scoring.
- * Evaluates 21 of 36 criteria that apply at individual page level.
+ * Evaluates 25 of 40 criteria that apply at individual page level.
  * Produces a 0-75 AEO score per page (single-page cap at 75).
  */
 
@@ -484,7 +484,7 @@ declare function scoreExtractionFriction(html: string): number;
 /** 20. Image Context for AI */
 declare function scoreImageContextAI(html: string): number;
 /**
- * Score a single page against 20 AEO criteria.
+ * Score a single page against 25 AEO criteria.
  * Returns a 0-100 AEO score (capped at 75 for single pages) and individual criterion scores.
  */
 declare function scorePage(html: string, url?: string): PageScoreResult;