geo-ai-search-optimization 2.6.0 → 2.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 The most comprehensive open-source CLI toolkit for **Generative Engine Optimization (GEO)**. Optimize your website for AI-powered search engines — ChatGPT, Perplexity, Gemini, Google AI Overviews, and Bing Copilot.
 
-**Zero dependencies. 43 commands. 12-dimension scoring. TypeScript support.**
+**Zero dependencies. 55+ commands. 18+ analysis dimensions. Full TypeScript support. REST API included.**
 
 [![npm version](https://img.shields.io/npm/v/geo-ai-search-optimization)](https://www.npmjs.com/package/geo-ai-search-optimization)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -25,7 +25,7 @@ npx geo-ai-search-optimization diagnose https://example.com
 # Smart diagnosis — auto-detects URL, directory, or file
 geo-ai-search-optimization diagnose https://example.com
 
-# Full 12-dimension page audit
+# Full multi-dimension page audit
 geo-ai-search-optimization full-page-audit https://example.com/blog/post
 
 # Generate ready-to-use fix code
@@ -34,18 +34,18 @@ geo-ai-search-optimization auto-fix https://example.com/blog/post
 # Compare two pages
 geo-ai-search-optimization compare https://yoursite.com https://competitor.com
 
-# Project-level audit
-geo-ai-search-optimization full-audit ./your-project
+# Interactive HTML dashboard
+geo-ai-search-optimization dashboard https://example.com --out report.html
 
-# CI/CD gate
-geo-ai-search-optimization ci ./your-project --min-score 60 --fail-on-regression
+# Start REST API server
+geo-ai-search-optimization api-server --port 3456
 ```
 
 ## What It Does
 
 GEO is **Generative Engine Optimization** — the practice of making your content understandable, extractable, and citable by AI search engines.
 
-This tool analyzes your pages across **12 dimensions** and tells you exactly what to fix:
+This tool analyzes your pages across **18+ dimensions** and tells you exactly what to fix:
 
 | Dimension | What It Checks |
 |-----------|---------------|
@@ -55,12 +55,20 @@ This tool analyzes your pages across **12 dimensions** and tells you exactly wha
 | **Readability** | Flesch-Kincaid grade, sentence length, passive voice, reading time |
 | **Heading Structure** | H1-H6 hierarchy, semantic coverage, question headings |
 | **Internal Links** | Link count, anchor text quality, path depth |
+| **Link Quality** | External link health, broken links, domain diversity, rel attributes |
 | **Social Meta** | Open Graph (10 tags), Twitter Card (7 tags) |
 | **Platform Readiness** | ChatGPT, Perplexity, Gemini, Google AI Overviews, Bing Copilot |
 | **Schema Validation** | JSON-LD correctness, required fields, AI discoverability enhancements |
-| **Content Freshness** | Date extraction (9 patterns), content age, staleness detection |
+| **Content Freshness** | Date extraction, temporal signals, stale references, evergreen scoring |
 | **Security** | HTTPS, security headers, viewport, robots meta, mixed content |
 | **Topic Coverage** | TF-IDF keywords, bigrams, topic clusters |
+| **Image Audit** | Alt text quality, lazy loading, srcset, og:image, ImageObject schema |
+| **Backlink Profile** | Authority signals, expert authorship, original research, link-worthiness |
+| **AI Snippet Readiness** | Predicted AI citations, quotable passages, snippet simulation |
+| **Multi-Language** | Language detection, hreflang validation, content-language consistency |
+| **Canonical** | Canonical URL issues, signal conflicts, redirect consistency |
+| **Accessibility** | Semantic HTML, heading order, alt text, ARIA landmarks, form labels, skip links |
+| **Performance** | Page weight, render-blocking resources, lazy loading, resource hints |
 
 ## Commands
 
@@ -68,17 +76,19 @@ This tool analyzes your pages across **12 dimensions** and tells you exactly wha
 
 ```bash
 diagnose <url|dir|file>              # Auto-detect input, run right analysis
-compare <page-A> <page-B>           # 12-dimension side-by-side comparison
+summary <url|dir|file>               # One-line score summary
+compare <page-A> <page-B>           # Multi-dimension side-by-side comparison
 auto-fix <url|file>                  # Generate fix code (meta, JSON-LD, robots.txt, llms.txt)
+explain <url|file>                   # Explain scores with evidence
 ```
 
 ### Page-Level Analysis
 
 ```bash
 page-audit <url|file>               # Basic GEO page audit
-full-page-audit <url|file>          # Full 12-dimension audit (with --save for snapshots)
+full-page-audit <url|file>          # Full multi-dimension audit (with --save for snapshots)
 batch-page-audit <urls...>          # Batch basic audits
-batch-full-page-audit <urls...>     # Batch 12-dimension audits
+batch-full-page-audit <urls...>     # Batch multi-dimension audits
 ```
 
 ### Project-Level Analysis
@@ -87,9 +97,10 @@ batch-full-page-audit <urls...>     # Batch 12-dimension audits
 scan <dir>                           # Signal scanning
 audit <dir>                          # Project audit with scoring
 full-audit <dir>                     # Project + infra + optional page sampling
+bulk-optimize <url|urls-file>        # Site-wide audit with prioritized fix list
 ```
 
-### Specialized Analysis (14 commands)
+### Specialized Analysis (20+ commands)
 
 ```bash
 crawlers <url|file>                  # AI crawler access (GPTBot, ClaudeBot, etc.)
@@ -97,7 +108,8 @@ citability <url|file>                # Static citability scoring
 eeat <url|file>                      # E-E-A-T signal analysis
 readability <url|file>               # Flesch-Kincaid, reading ease
 heading-structure <url|file>         # H1-H6 hierarchy analysis
-internal-links <url|file>            # Link analysis
+internal-links <url|file>            # Internal link analysis
+link-quality <url|file>              # External link quality audit
 social-meta <url|file>               # OG + Twitter tags
 platform-ready <url|file>            # Multi-platform readiness
 validate-schema <url|file>           # JSON-LD validation
@@ -105,23 +117,51 @@ validate-llms <url|file>             # llms.txt validation
 sitemap <url|file>                   # XML sitemap analysis
 security <url|file>                  # Security headers + checks
 freshness <url|file>                 # Content age analysis
+content-freshness <url|file>         # Deep freshness with temporal signals
 topics <url|file>                    # Keyword + topic extraction
+image-audit <url|file>               # Image SEO/GEO audit
+backlink-profile <url|file>          # Authority signal analysis
+ai-snippet <url|file>                # AI snippet simulation
+canonical <url|file>                 # Canonical URL diagnostics
+multi-lang <url|file>                # Multi-language / hreflang audit
+accessibility <url|file>             # Accessibility audit (12 checks)
+performance <url|file>               # Performance hints for AI crawlers
 ```
 
 ### Competitive Analysis
 
 ```bash
-benchmark <url> --competitors <urls> # Signal matrix comparison
-content-gap <url> --competitors <urls> # Gap analysis
+benchmark <url> --competitors <urls>          # Signal matrix comparison
+deep-benchmark <url> --competitors <urls>     # Deep multi-dimension benchmark
+content-gap <url> --competitors <urls>        # Content gap analysis
+keyword-gap <url> --competitors <urls>        # Keyword coverage gaps
+track-competitors <url> --competitors <urls>  # Persistent competitor tracking
+watch-competitors <url> --competitors <urls>  # Single-pass competitor watch
 ```
 
-### Tracking & CI
+### Content Generation & Optimization
+
+```bash
+auto-fix <url|file>                  # Generate meta tags, JSON-LD, robots.txt, llms.txt
+generate-llms <url|file>             # Smart llms.txt generation from site content
+optimize-llms <url|file>             # Optimize existing llms.txt
+generate-schema <url|file>           # Auto-generate JSON-LD schemas
+generate-sitemap <url|dir>           # Generate XML sitemap
+rewrite-content <url|file>           # Content improvement suggestions
+```
+
+### Tracking & Monitoring
 
 ```bash
 full-page-audit <url> --save         # Save page snapshot
 page-trend <url>                     # View page score history
 trend                                # View project score trend
-snapshot                             # Manage audit snapshots
+monitor <url>                        # Detect score drops
+score-history <url>                  # View score history with sparklines
+record-score <url> --score <n>       # Record a score entry
+alert-check <url>                    # Evaluate alert rules
+cache-stats                          # View cache statistics
+cache-clear                          # Clear cached results
 ci <dir> --min-score 60              # CI/CD gate
 watch <dir>                          # Auto-audit on file changes
 init-hook                            # Git pre-commit hook
@@ -130,30 +170,69 @@ init-hook                            # Git pre-commit hook
 ### Citation Tracking
 
 ```bash
-citation-check <url> --queries <q1,q2>  # Check if cited in AI search
+citation-check <url> --queries <q1,q2>        # Check if cited in AI search
 citation-monitor <url> --queries-file <file>  # Monitor citation rate
 ```
 
-### Code Generation & Init
-
-```bash
-auto-fix <url|file>                  # Generate meta tags, JSON-LD, robots.txt, llms.txt
-init-llms [dir]                      # Generate llms.txt template
-init-schema <type> [dir]             # Generate JSON-LD template
-init-config [dir]                    # Generate .georc.json
-init-hook [dir]                      # Generate pre-commit hook
-```
-
-### Reports & Export
+### Reports & Output
 
 ```bash
 report <input>                       # Unified report (markdown/html/json)
 pdf-report <audit.json>              # PDF-ready HTML report
+dashboard <url|file>                 # Interactive HTML dashboard
+slack-report <audit.json>            # Slack/Discord webhook report
 html-pack <input> --out-dir <dir>    # Static HTML pages
 export-pack <input> --out-dir <dir>  # Multi-format export
 publish-pack <input> --out-dir <dir> # Full deliverable package
 ```
 
+### REST API Server
+
+```bash
+api-server [--port 3456] [--host 127.0.0.1]
+```
+
+All API responses are cached for 10 minutes by default. Add `?no-cache=1` to bypass. Use `/api/cache-stats` and `POST /api/cache-clear` to manage.
+
+Exposes all analysis functions as HTTP endpoints:
+
+```
+GET /api/health
+GET /api/full-audit?url=<url>
+GET /api/citability?url=<url>
+GET /api/eeat?url=<url>
+GET /api/crawlers?url=<url>
+GET /api/link-quality?url=<url>
+GET /api/content-freshness?url=<url>
+GET /api/ai-snippet?url=<url>
+GET /api/structured-data?url=<url>
+GET /api/backlink-profile?url=<url>
+GET /api/accessibility?url=<url>
+GET /api/performance?url=<url>
+GET /api/readability?url=<url>
+GET /api/heading-structure?url=<url>
+GET /api/internal-links?url=<url>
+GET /api/social-meta?url=<url>
+GET /api/security?url=<url>
+GET /api/topics?url=<url>
+GET /api/validate-schema?url=<url>
+GET /api/platform-ready?url=<url>
+GET /api/image-audit?url=<url>
+GET /api/cache-stats
+POST /api/cache-clear
+GET /api/endpoints
+```
+
+### Init & Config
+
+```bash
+init-llms [dir]                      # Generate llms.txt template
+init-schema <type> [dir]             # Generate JSON-LD template
+init-config [dir]                    # Generate .georc.json
+init-hook [dir]                      # Generate pre-commit hook
+doctor                               # Check installation health
+```
+
 ## Programmatic API
 
 ```javascript
@@ -165,35 +244,61 @@ import {
   analyzeCrawlers,
   analyzeCitability,
   analyzeEeat,
-  analyzeReadability
+  analyzeLinkQuality,
+  analyzeContentFreshness,
+  simulateAiSnippet,
+  generateStructuredData,
+  analyzeBacklinkProfile,
+  trackCompetitors,
+  bulkOptimize,
+  generateLlmsTxt,
+  optimizeLlmsTxt,
+  startApiServer,
+  formatSlackReport,
+  generateDashboard,
+  evaluateAlertRules,
+  getScoreHistory,
+  auditAccessibility,
+  analyzePerformance,
+  createCache
 } from 'geo-ai-search-optimization';
 
 // Smart diagnosis
 const result = await diagnose('https://example.com');
 console.log(result.score, result.quickWins);
 
-// Full 12-dimension audit
+// Full multi-dimension audit
 const audit = await fullPageAudit('https://example.com/blog/post');
 console.log(audit.compositeScore, audit.dimensions);
 
-// Compare two pages
-const comparison = await comparePages(
+// AI snippet simulation
+const snippet = await simulateAiSnippet('https://example.com/blog/post');
+console.log(snippet.simulatedSnippets.chatgpt);
+
+// Competitor tracking with alerts
+const tracking = await trackCompetitors(
   'https://yoursite.com',
-  'https://competitor.com'
+  ['https://competitor1.com', 'https://competitor2.com']
 );
-console.log(comparison.overallWinner, comparison.dimensionWins);
+console.log(tracking.ownRank, tracking.alerts);
+
+// Start REST API
+const api = await startApiServer({ port: 3456 });
+console.log(`API running at ${api.url}`);
 
-// Generate fix code
-const fixes = await generateAutoFix('https://example.com');
-console.log(fixes.jsonLdSchemas, fixes.metaTags);
+// Generate HTML dashboard
+const dashboard = await generateDashboard('https://example.com', {
+  outputPath: 'report.html',
+  theme: 'dark'
+});
 ```
 
-Full TypeScript declarations included (`index.d.ts`) — 230+ exports with IDE autocomplete.
+Full TypeScript declarations included (`index.d.ts`) — 300+ exports with IDE autocomplete.
 
 ## GitHub Action
 
 ```yaml
-- uses: redredchen01/geo-ai-search-optimization@v2.6.0
+- uses: redredchen01/geo-ai-search-optimization@v2.8.0
   with:
     project-path: ./your-project
     min-score: 60
@@ -236,25 +341,43 @@ export function register(api) {
 
 Load via config: `"plugins": ["./my-plugin.js"]`
 
+## Alert Rules
+
+Configure automated alerts in a JSON file:
+
+```json
+[
+  { "name": "Low Score", "condition": "score-below", "threshold": 40, "action": "webhook", "actionConfig": { "url": "https://hooks.slack.com/..." } },
+  { "name": "Score Drop", "condition": "score-drop", "threshold": 10, "action": "console" },
+  { "name": "Weak Citability", "condition": "dimension-below", "threshold": 30, "dimension": "citability", "action": "file", "actionConfig": { "filePath": "alerts.log" } }
+]
+```
+
+```bash
+geo-ai-search-optimization alert-check https://example.com --rules-file rules.json
+```
+
 ## Why GEO?
 
 - **35%+ of search queries** are now handled by AI assistants (2026)
 - **SaaS GEO tools cost $100-$3000/month** — this is free and open-source
 - **No other npm package** provides comprehensive GEO analysis with zero dependencies
 - **CI/CD native** — fail your build if GEO score drops
-- **Agent-friendly** — 25 bundled Codex skills for AI coding assistants
+- **REST API included** — integrate with any tool or pipeline
+- **Agent-friendly** — 25+ bundled Codex skills for AI coding assistants
 
 ## Numbers
 
 | Metric | Value |
 |--------|-------|
-| CLI Commands | 43 site ops + agent workflow commands |
-| API Exports | 230+ |
-| Analysis Dimensions | 12 |
-| Test Cases | 139 |
+| CLI Commands | 50+ |
+| API Exports | 300+ |
+| Analysis Dimensions | 15+ |
+| Test Cases | 466 |
 | External Dependencies | 0 |
 | TypeScript Support | Full declarations |
 | GitHub Action | Included |
+| REST API | Included |
 | Plugin System | Extensible |
 
 ## License

package/action.yml

@@ -51,7 +51,7 @@ runs:
 
     - name: Install geo-ai-search-optimization
       shell: bash
-      run: npm install -g geo-ai-search-optimization@2.6.0
+      run: npm install -g geo-ai-search-optimization@2.8.0
 
     - name: Run GEO Audit
       id: audit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {