aeorank 1.0.0 → 1.2.0

package/README.md

@@ -6,6 +6,10 @@ Score any website for AI engine visibility across 23 criteria. Pure HTTP + regex
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js CI](https://github.com/AEO-Content-Inc/aeorank/actions/workflows/ci.yml/badge.svg)](https://github.com/AEO-Content-Inc/aeorank/actions/workflows/ci.yml)
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AEO-Content-Inc/aeorank/main/demo.gif" alt="aeorank demo" width="700">
+</p>
+
 ## Quick Start
 
 ### CLI
@@ -17,7 +21,9 @@ npx aeorank example.com
 ```bash
 npx aeorank example.com --json          # JSON output
 npx aeorank example.com --summary       # Human-readable scorecard
+npx aeorank example.com --html          # Standalone HTML report
 npx aeorank example.com --ci --threshold 80  # CI gate
+npx aeorank site-a.com site-b.com       # Side-by-side comparison
 ```
 
 ### Programmatic
@@ -65,10 +71,12 @@ AEORank evaluates 23 criteria across 4 categories that determine how AI engines
 
 ```
 aeorank <domain> [options]
+aeorank <domain-a> <domain-b> [options]   # comparison mode
 
 Options:
   --json              Output raw JSON to stdout
   --summary           Print human-readable scorecard
+  --html              Generate standalone HTML report file
   --ci                CI mode: JSON + exit 1 if score < threshold
   --threshold <N>     Score threshold for --ci (default: 70)
   --no-headless       Skip Puppeteer SPA rendering
@@ -79,9 +87,21 @@ Options:
 
 ## GitHub Actions
 
+Use the built-in action to gate deployments on AEO score:
+
+```yaml
+- name: AEO Audit
+  uses: AEO-Content-Inc/aeorank@v1
+  with:
+    domain: example.com
+    threshold: 70
+```
+
+Or use `npx` directly:
+
 ```yaml
 - name: AEO Audit
-  run: npx aeorank ${{ env.SITE_URL }} --ci --threshold 70
+  run: npx aeorank example.com --ci --threshold 70
 ```
 
 ## API
@@ -153,6 +173,74 @@ Score interpretation:
 - **41-55** - Below average, multiple areas need attention
 - **0-40** - Critical gaps, largely invisible to AI engines
 
+## HTML Reports
+
+Generate a self-contained HTML report with score visualization, scorecard grid, and opportunities table:
+
+```bash
+npx aeorank example.com --html
+# -> aeorank-example-com.html
+
+npx aeorank site-a.com site-b.com --html
+# -> aeorank-site-a-com-vs-site-b-com.html
+```
+
+Reports include inline CSS and SVG - no external dependencies. Open directly in any browser or share as a file.
+
+Programmatic usage:
+
+```ts
+import { audit, generateHtmlReport } from 'aeorank';
+
+const result = await audit('example.com');
+const html = generateHtmlReport(result);
+```
+
+## Comparison Mode
+
+Compare two sites side-by-side. Both audits run in parallel:
+
+```bash
+npx aeorank site-a.com site-b.com
+npx aeorank site-a.com site-b.com --json
+npx aeorank site-a.com site-b.com --html
+```
+
+Programmatic usage:
+
+```ts
+import { compare } from 'aeorank';
+
+const result = await compare('site-a.com', 'site-b.com');
+console.log(result.comparison.scoreDelta);       // Overall score difference
+console.log(result.comparison.siteAAdvantages);   // Criteria where A leads
+console.log(result.comparison.siteBAdvantages);   // Criteria where B leads
+console.log(result.comparison.tied);              // Criteria with equal scores
+```
+
+## Benchmark Dataset
+
+The `data/` directory contains open benchmark data from 500+ audited domains:
+
+| File | Description |
+|------|-------------|
+| [`data/benchmark.json`](data/benchmark.json) | All domains with per-criterion scores, sector/category |
+| [`data/yc.json`](data/yc.json) | YC startups with company metadata |
+| [`data/sectors.json`](data/sectors.json) | Pre-computed sector statistics |
+
+Use the dataset for research, benchmarking, or building on top of AEORank:
+
+```ts
+import benchmark from './data/benchmark.json' assert { type: 'json' };
+
+// Find domains scoring above 80
+const topDomains = benchmark.entries.filter(e => e.score >= 80);
+
+// Get sector averages
+import sectors from './data/sectors.json' assert { type: 'json' };
+console.log(sectors.sectors.healthcare.mean); // Average score for healthcare
+```
+
 ## Contributing
 
 ```bash