aiseo-audit 1.4.17 → 1.5.0

package/README.md

@@ -6,9 +6,10 @@
 [![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)
 
 <div align="center">
   <strong>Testing example</strong><br /><br />
@@ -22,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)
@@ -75,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
 
@@ -105,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
@@ -120,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:
@@ -157,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.
 
@@ -217,7 +387,10 @@ The audit also checks for three domain-level files that AI crawlers look for:
 - **`llms.txt`** is a proposed standard that provides LLMs with a concise summary of your site's purpose, key pages, and preferred citation format.
 - **`llms-full.txt`** is the extended version of `llms.txt` with more comprehensive site documentation.
 
-When auditing over HTTP, these files are checked against your local server. If your local server serves them, they will pass. If not, they will show as missing. Keep in mind that your local and production configurations for these files may differ, so verify them separately against your production domain.
+When auditing over HTTP, these files are checked against your local server. If your local server serves them, they will pass. If not, they will show as missing.
+
+> [!NOTE]
+> Local audit results may differ slightly from production. Domain signal files (`robots.txt`, `llms.txt`, `llms-full.txt`) are often configured at the hosting or CDN level and may not be present on your local dev server. Always verify these signals separately against your production domain.
 
 ## Audit Categories
 
@@ -238,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.
 
@@ -295,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
@@ -363,6 +549,9 @@ import type {
   AuditResultType,
   CategoryNameType,
   CategoryResultType,
+  CategoryDeltaType,
+  DiffEntryType,
+  DiffResultType,
   FactorResultType,
   RecommendationType,
   ReportFormatType,
@@ -370,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 = {
@@ -379,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.
@@ -410,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");