aiseo-audit 1.4.19 → 1.5.0

package/README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-7EB6D7.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-7EB6D7.svg)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-7EB6D7?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Tests](https://img.shields.io/badge/tests-459%20passed-8FBC8F)](https://github.com/agencyenterprise/aiseo-audit)
+[![Tests](https://img.shields.io/badge/tests-558%20passed-8FBC8F)](https://github.com/agencyenterprise/aiseo-audit)
 [![Coverage](https://img.shields.io/codecov/c/github/agencyenterprise/aiseo-audit?color=8FBC8F&label=coverage)](https://codecov.io/gh/agencyenterprise/aiseo-audit)
 [![GitHub Stars](https://img.shields.io/github/stars/agencyenterprise/aiseo-audit?style=flat&color=8FBC8F)](https://github.com/agencyenterprise/aiseo-audit/stargazers)
 ![npm downloads](https://img.shields.io/npm/dt/aiseo-audit?label=Total%20Downloads)
@@ -23,6 +23,9 @@ Deterministic CLI that audits web pages for **AI search readiness**. Think Light
 **Who is this for?** Content teams running pre-publish checks, developers gating deployments in CI/CD, and marketers auditing their own or competitor pages. If your content needs to be cited (not just ranked), this tool tells you where you stand.
 
 - [Quick Start](#quick-start)
+- [Quick Summary Mode](#quick-summary-mode)
+- [Tracking AI SEO Over Time](#tracking-ai-seo-over-time)
+- [Use with AI Assistants (MCP)](#use-with-ai-assistants-mcp)
 - [CI/CD](#cicd)
 - [CLI Options](#cli-options)
 - [Site-Wide Auditing](#site-wide-auditing)
@@ -76,6 +79,12 @@ npm install -g aiseo-audit
 # Pretty terminal output (default)
 aiseo-audit https://example.com
 
+# Quick summary only (top 3 wins + projected score, skip the full breakdown)
+aiseo-audit https://example.com --tldr
+
+# Track score changes over time
+aiseo-audit https://example.com --diff
+
 # JSON output
 aiseo-audit https://example.com --json
 
@@ -106,9 +115,150 @@ aiseo-audit https://example.com --user-agent "MyBot/1.0"
 aiseo-audit https://example.com --config aiseo.config.json
 ```
 
+## Quick Summary Mode
+
+Use `--tldr` to get just the top 3 highest-impact fixes and the projected score after applying them. No detailed category breakdown, no long recommendations list. Ideal for CI logs, Slack notifications, and quick pre-publish checks.
+
+```bash
+aiseo-audit https://example.com --tldr
+```
+
+```
+============================================================
+  AI SEO Audit
+  https://example.com
+============================================================
+
+  Score: 59/100 Grade: F   →   Top 3 fixes: ~87/100 B+
+
+  Quickest wins:
+    1. +13 pts  Answer Capsules      (Answerability)
+    2. +10 pts  Author Attribution   (Authority Context)
+    3.  +7 pts  Image Alt Text       (Content Extractability)
+```
+
+`--tldr` works with every output format (`--json`, `--md`, `--html`) so you can pipe it into any integration. Combine with `--out` to write a slim summary to a file.
+
+## Tracking AI SEO Over Time
+
+`--diff` records every audit and shows you what changed since the last run for the same URL.
+
+> [!IMPORTANT]
+> `--diff` is the only flag that writes files outside of `--out`. On first use it creates `./audits/` (or your configured `historyDir`) and an `aiseo.config.json` in the current directory if one doesn't exist. Both are announced on stderr the moment they're created — nothing is written silently. Add `./audits/` to `.gitignore` if you don't want the history tracked in version control, or commit it to keep a record of AI SEO over time.
+
+```bash
+# First run — establishes a baseline
+aiseo-audit https://example.com --diff
+
+# Subsequent runs — shows the delta
+aiseo-audit https://example.com --diff
+```
+
+Output on the second run:
+
+```
+  Changes since baseline (2026-04-10 → 2026-04-17)
+    Overall            59 → 68   (+9)
+    Answerability      18 → 28   (+10)
+    Grounding Signals  23 → 26   (+3)
+```
+
+**How it works.** Each `--diff` run writes a full JSON audit to `./audits/<slug>-<timestamp>.json` and appends an entry to `aiseo.config.json` under a `diff` key. Nothing is ever overwritten — every run is preserved so you can walk the history.
+
+```json
+{
+  "historyDir": "./audits",
+  "diff": {
+    "https://example.com": [
+      {
+        "path": "audits/example-2026-04-10.json",
+        "timestamp": "2026-04-10T…",
+        "score": 59
+      },
+      {
+        "path": "audits/example-2026-04-17.json",
+        "timestamp": "2026-04-17T…",
+        "score": 68
+      }
+    ]
+  }
+}
+```
+
+### Saving a formatted report alongside the baseline
+
+`--diff` always writes the JSON baseline to `historyDir` automatically. If you also want a human-friendly report (HTML, Markdown, pretty), pass `--out` with a file path and the rendered report will be written there:
+
+```bash
+# Creates two files: the auto-named JSON baseline in ./audits/,
+# and a rendered HTML report at ./audits/report.html.
+aiseo-audit https://example.com --diff --html --out ./audits/report.html
+```
+
+`--out` never replaces the baseline. It's purely for the rendered report. If `--out` points at an existing directory, the audit exits early with a clear error rather than silently writing an invalid file.
+
+### Cross-URL timeline
+
+Drop the URL and pass `--diff --all` to see every tracked URL at a glance with a sparkline of its history:
+
+```bash
+aiseo-audit --diff --all
+```
+
+```
+  Audit History (2 URLs tracked, 7 total runs)
+
+  https://example.com       ▂▅▇▆  59 → 68 → 72 → 70
+  https://another-site.com  ▇▇    72 → 72
+```
+
+Works with `--html` for a shareable timeline page with inline SVG line charts.
+
+### Explicit baseline
+
+If you want to compare against a specific prior JSON result without touching the tracked history, use `--baseline`:
+
+```bash
+aiseo-audit https://example.com --baseline ./previous-audit.json
+```
+
+## Use with AI Assistants (MCP)
+
+aiseo-audit ships an [MCP](https://modelcontextprotocol.io) server so Cursor, Claude Desktop, Windsurf, and any other MCP client can call the `audit_url` tool inline in a chat.
+
+No install required — the server runs via `npx` from the published package.
+
+**Cursor** (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "aiseo-audit": {
+      "command": "npx",
+      "args": ["-y", "aiseo-audit-mcp"]
+    }
+  }
+}
+```
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "aiseo-audit": {
+      "command": "npx",
+      "args": ["-y", "aiseo-audit-mcp"]
+    }
+  }
+}
+```
+
+Once configured, prompt your assistant naturally — e.g. "audit https://mysite.com for AI search readiness" — and it will invoke the tool and return a full audit inline.
+
 ## CI/CD
 
-Drop this into any GitHub Actions workflow to gate PRs on AI search readiness:
+aiseo-audit ships an official [GitHub Action](https://github.com/marketplace/actions/ai-seo-audit). Drop it into any workflow to gate PRs on AI search readiness and post a sticky PR comment with the summary:
 
 ```yaml
 # .github/workflows/aiseo-audit.yml
@@ -121,8 +271,23 @@ on:
 jobs:
   audit:
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
-      - run: npx aiseo-audit https://yoursite.com --fail-under 70
+      - uses: agencyenterprise/aiseo-audit@v1
+        with:
+          url: https://yoursite.com
+          fail-under: 70
+          comment-on-pr: true
+```
+
+With `comment-on-pr: true`, the Action updates a single sticky comment on each PR with the TL;DR score, grade, and top fixes — so reviewers see the impact of content changes inline.
+
+Prefer a one-liner without the Action wrapper? This still works:
+
+```yaml
+steps:
+  - run: npx aiseo-audit https://yoursite.com --fail-under 70
 ```
 
 **Using a preview deployment URL?** If your CI pipeline produces a dynamic URL (e.g. a Vercel or Netlify preview), capture it from a prior step and pass it in:
@@ -158,8 +323,12 @@ The `--fail-under` threshold sets the minimum acceptable score. Exit code `1` is
 | `--timeout <ms>`       | Request timeout in ms                                                             | `45000`                                       |
 | `--user-agent <ua>`    | Custom User-Agent string                                                          | `AISEOAudit/<version>`                        |
 | `--config <path>`      | Path to config file                                                               | -                                             |
+| `--tldr`               | Emit only the TL;DR summary (no detailed breakdown)                               | -                                             |
+| `--diff`               | Track score over time: record this run, diff against the previous recorded run    | -                                             |
+| `--all`                | With `--diff` and no URL, render audit history across all tracked URLs            | -                                             |
+| `--baseline <path>`    | Diff against a specific prior JSON result (bypasses history tracking)             | -                                             |
 
-Either `[url]` or `--sitemap` must be provided, but not both. If no output flag is given, the default is `pretty` (color-coded terminal output). The default format can also be set in the config file.
+Either `[url]` or `--sitemap` must be provided (or `--diff --all` for the cross-URL timeline). If no output flag is given, the default is `pretty` (color-coded terminal output). The default format can also be set in the config file.
 
 When `--out` is provided, the format is automatically inferred from the file extension (`.html` becomes HTML, `.md` becomes Markdown, `.json` becomes JSON) so you don't need to pass a separate format flag. An explicit `--html`, `--md`, or `--json` flag takes precedence if provided.
 
@@ -242,13 +411,22 @@ The audit evaluates 7 categories of AI search readiness (_[Detailed Breakdown he
 
 ### Interpreting Your Score
 
+Grades follow a standard US academic scale with +/- sub-grades for granular tracking across iterations.
+
 | Score  | Grade | What It Means                                                                                            |
 | ------ | ----- | -------------------------------------------------------------------------------------------------------- |
-| 90–100 | A     | Highly optimized. AI engines can fetch, understand, and cite your content with minimal friction.         |
-| 75–89  | B     | Good foundation. A few targeted improvements will push you into the top tier.                            |
-| 60–74  | C     | Moderate readiness. Structural or content gaps are likely limiting your citation potential.              |
-| 40–59  | D     | Significant gaps. Core signals (structure, answerability, authority) need attention.                     |
-| 0–39   | F     | Not AI-ready. Start with Content Extractability. If the content cannot be fetched, nothing else matters. |
+| 93–100 | A     | Highly optimized. AI engines can fetch, understand, and cite your content with minimal friction.         |
+| 90–92  | A-    | Near top tier. A handful of polish items stand between you and an A.                                     |
+| 87–89  | B+    | Strong foundation with a few high-impact gaps worth closing.                                             |
+| 83–86  | B     | Good foundation. Targeted improvements will push you into the top tier.                                  |
+| 80–82  | B-    | Solid, but several category gaps are holding back citation potential.                                    |
+| 77–79  | C+    | Above average. Structural or content gaps are limiting citation potential.                               |
+| 73–76  | C     | Moderate readiness. Multiple categories need attention.                                                  |
+| 70–72  | C-    | Below the comfort zone. Prioritize high-impact recommendations.                                          |
+| 67–69  | D+    | Noticeable gaps across core signals.                                                                     |
+| 63–66  | D     | Significant gaps. Core signals (structure, answerability, authority) need attention.                     |
+| 60–62  | D-    | On the edge of failing. Most categories need meaningful work.                                            |
+| 0–59   | F     | Not AI-ready. Start with Content Extractability. If the content cannot be fetched, nothing else matters. |
 
 The per-category breakdown in each report shows exactly where to focus. Start with high-priority recommendations in your lowest-scoring categories.
 
@@ -299,12 +477,16 @@ You can also pass an explicit path with `--config path/to/config.json`.
     "groundingSignals": 1,
     "authorityContext": 1,
     "readabilityForCompression": 1
-  }
+  },
+  "historyDir": "./audits",
+  "diff": {}
 }
 ```
 
 Weights are relative. Set a category to `2` to double its importance, or `0` to exclude it entirely from scoring.
 
+`historyDir` controls where `--diff` writes audit JSONs (default `./audits`). `diff` is managed by the tool — each `--diff` run appends an entry keyed by URL. See [Tracking AI SEO Over Time](#tracking-ai-seo-over-time).
+
 **Example: tuning for a blog or editorial site.** Content that needs to be cited by AI engines should be highly answerable and readable. Double those weights and reduce the emphasis on domain-signal files (`authorityContext` covers schema markup, while `groundingSignals` covers citations and statistics):
 
 ```json
@@ -367,6 +549,9 @@ import type {
   AuditResultType,
   CategoryNameType,
   CategoryResultType,
+  CategoryDeltaType,
+  DiffEntryType,
+  DiffResultType,
   FactorResultType,
   RecommendationType,
   ReportFormatType,
@@ -374,7 +559,7 @@ import type {
 } from "aiseo-audit";
 ```
 
-`RecommendationType` includes the base fields (`category`, `factor`, `currentValue`, `priority`, `recommendation`) plus three optional fields populated for high-impact factors:
+`RecommendationType` includes the base fields (`category`, `factor`, `currentValue`, `priority`, `recommendation`) plus optional fields populated for high-impact factors:
 
 ```typescript
 type RecommendationType = {
@@ -383,12 +568,17 @@ type RecommendationType = {
   currentValue: string;
   priority: "high" | "medium" | "low";
   recommendation: string;
+  expectedGain?: number; // points you'd recover by resolving this factor
   steps?: string[]; // ordered implementation steps
   codeExample?: string; // ready-to-use code snippet
   learnMoreUrl?: string; // link to canonical spec or docs
 };
 ```
 
+### Diffing results programmatically
+
+`computeDiff(current, baseline)` compares two `AnalyzerResultType` values and returns a `DiffResultType` with the overall delta and per-category deltas. Pair with `renderDiffReport(result, diff, { format })` to render the diff in any format, or `renderHistoryTimeline(diffMap, { format })` to render a cross-URL timeline from a tracked history map.
+
 ## Philosophy
 
 This tool measures **AI search reusability**: how well a page's content can be fetched, extracted, understood, and reused by AI engines like ChatGPT, Claude, Perplexity, and Gemini.
@@ -414,7 +604,7 @@ It is:
 
 **Zod** - Uses [Zod 4](https://zod.dev). If you consume the library API and also use Zod in your project, ensure you are on Zod 4+ to avoid type incompatibilities.
 
-**CJS bin entry** - The `bin/aiseo-audit.js` executable uses `require()` (CommonJS). This is compatible with all Node 20+ environments regardless of your project's module system. The library exports support both ESM (`import`) and CJS (`require`).
+**CJS bin entries** - Both `bin/aiseo-audit.js` (CLI) and `bin/aiseo-audit-mcp.js` (MCP server) use `require()` (CommonJS). This is compatible with all Node 20+ environments regardless of your project's module system. The library exports support both ESM (`import`) and CJS (`require`).
 
 **Config discovery** - When using the programmatic API, `loadConfig()` searches for config files starting from `process.cwd()`. If your application's working directory differs from where your config file lives, pass an explicit path:
 

package/bin/aiseo-audit-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../dist/mcp.js");