{
  "markdown": "# aiseo-audit\n\n[![npm version](https://img.shields.io/npm/v/aiseo-audit.svg?color=F5B0A4)](https://www.npmjs.com/package/aiseo-audit)\n[![License: MIT](https://img.shields.io/badge/License-MIT-7EB6D7.svg)](LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20.19-7EB6D7.svg)](https://nodejs.org)\n[![CI](https://github.com/agencyenterprise/aiseo-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/agencyenterprise/aiseo-audit/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/codecov/c/github/agencyenterprise/aiseo-audit?color=8FBC8F&label=coverage)](https://codecov.io/gh/agencyenterprise/aiseo-audit)\n\n**A deterministic, Lighthouse-style audit for AI search readiness.** Test how easily generative engines can fetch, extract, understand, and reuse a web page.\n\nAI SEO measures content readiness, not traditional search rank. The score is a research-informed heuristic audit, not a citation probability or a promise that an engine will cite the page.\n\n[Website & guides](https://aiseo-audit.com/) · [Quick start](#quick-start) · [CI/CD](#cicd) · [AI assistants](#use-with-ai-assistants-mcp) · [Library API](docs/API.md) · [Scoring methodology](docs/AUDIT_BREAKDOWN.md)\n\n## Quick Start\n\nRequires Node.js 20.19 or later.\n\n```bash\nnpx aiseo-audit https://yoursite.com\n```\n\nNo install or API key is required. Analysis runs locally with no AI API calls or telemetry. Network access is limited to the page, the sitemap, and domain-signal files such as `robots.txt` and `llms.txt`.\n\nTypical output begins with the overall score, pipeline stages, and highest-impact fixes:\n\n```text\nOverall Score: 68/100  Grade: D+\n\nPipeline Stages:\n  Technical Eligibility    PASS 96%\n  Retrieval Alignment           58%\n  Citation Fitness              63%\n  Provenance                    42%\n\nTop fixes:\n  1. Topic Consistency  (Entity Clarity)\n  2. Citation Patterns  (Grounding Signals)\n  3. Lead Summary       (Answerability)\n```\n\n<div align=\"center\">\n  <img src=\"docs/assets/ai-seo-bad-site-example.gif\" alt=\"Terminal demonstration of aiseo-audit running against a local web page\" width=\"600\" />\n</div>\n\nFor a project-local CLI installation:\n\n```bash\nnpm install --save-dev aiseo-audit\n```\n\nInstall it as a regular dependency when using the [programmatic API](docs/API.md), or globally with `npm install -g aiseo-audit`.\n\n## Why aiseo-audit?\n\n- **Content analysis, not tag detection.** Reads the page the way an engine would: does it name its subject consistently, answer questions directly, back claims with sources, and keep boilerplate out of the way? 50+ factors.\n- **Evidence-tiered scoring.** Every factor is labeled supported, conditional, heuristic, diagnostic, or experimental and mapped to the reviewed literature in [docs/EVIDENCE.md](docs/EVIDENCE.md).\n- **Pipeline-stage reporting.** See whether the main constraint is technical eligibility, retrieval alignment, citation fitness, or provenance.\n- **Deterministic and inspectable.** The same tool version, configuration, and fetched HTML produce the same score. Weights and thresholds are documented rather than hidden behind an external service.\n- **Multiple ways to run.** Use the CLI, GitHub Action, MCP server, or typed TypeScript API; render terminal, JSON, Markdown, or standalone HTML reports.\n\n## Common Workflows\n\n### Audit against target queries\n\nQuery-aware audits measure three things: query terms in structural fields such as the title and headings, query terms in the body text, and a section of the page addressing each aspect of the query. Supply about five queries for a stable measurement; the maximum is ten.\n\n```bash\nnpx aiseo-audit https://example.com/guide \\\n  --query \"how to set up sso\" \\\n  --query \"saml vs oidc\" \\\n  --query \"sso troubleshooting checklist\"\n```\n\nUse `--domain product` for product-specific price, specification, and comparison checks. `--engine gemini|gpt|perplexity` applies experimental presets that reweight existing categories toward each engine; they add no new checks.\n\n### Create a shareable report\n\nThe format is inferred from the output extension:\n\n```bash\nnpx aiseo-audit https://example.com --out report.html\nnpx aiseo-audit https://example.com --out report.md\nnpx aiseo-audit https://example.com --out report.json\n```\n\nUse `--tldr` for only the score and top three fixes.\n\n### Track changes over time\n\n```bash\n# First run establishes a baseline; later runs show the delta.\nnpx aiseo-audit https://example.com --diff\n\n# Compare with a specific result without updating tracked history.\nnpx aiseo-audit https://example.com --baseline ./previous-audit.json\n\n# Show the timeline for every tracked URL.\nnpx aiseo-audit --diff --all\n```\n\n`--diff` records JSON results in `./audits` by default and updates the discovered config file. See the [CLI guide](docs/CLI.md#tracking-results-over-time) before enabling it in a repository.\n\n### Audit a sitemap\n\n```bash\nnpx aiseo-audit --sitemap https://example.com/sitemap.xml --out site-report.html\n```\n\nThe report includes the average score, site-wide category averages, a host-level provenance profile, and per-URL results. Sitemap indexes are supported. URLs run sequentially, so scope large sitemaps intentionally.\n\nMore recipes and every flag are documented in the [CLI guide](docs/CLI.md). For tutorials and practical implementation guidance, visit [aiseo-audit.com](https://aiseo-audit.com/).\n\n## What the Audit Reports\n\nEvery report rolls results up into four pipeline stages:\n\n| Stage                     | Meaning                                                                                                |\n| ------------------------- | ------------------------------------------------------------------------------------------------------ |\n| **Technical Eligibility** | Can the page be fetched, yield usable text, and remain accessible to at least one known AI crawler?    |\n| **Retrieval Alignment**   | Do structural fields, entities, topic coverage, and structured data support retrieval?                 |\n| **Citation Fitness**      | Does the in-context content provide direct, grounded, appropriately fresh material that can be reused? |\n| **Provenance**            | Does the page communicate authorship, organization identity, and attribution clearly?                  |\n\nTechnical Eligibility is a gate. A fetch failure, unusable text, or blocking every known crawler caps the overall score at 25 and suppresses downstream percentages. Citation Fitness also has evidence-based negative gates for visibly stale time-sensitive content, target-query mismatch, and missing product prices.\n\nFactors are organized into ten categories, with Query Alignment appearing only when target queries are supplied and Product Fit appearing only for product pages. The complete factor, weight, threshold, and stage mapping lives in the [Audit Breakdown](docs/AUDIT_BREAKDOWN.md).\n\nUnscored diagnostics never affect the score. They keep observations visible when the research cannot yet justify scoring them.\n\n### Interpreting scores\n\nLetter grades use familiar academic score bands. They are not population percentiles, calibrated estimates of citation likelihood, or evidence that one site is “above average.” Use the score to compare the same page or page set under a stable tool version and configuration, then prioritize the highest-weight findings and re-measure.\n\nIf you use `--fail-under`, establish the threshold from your own v2 baselines rather than treating any universal score as a guaranteed passing grade.\n\n## CI/CD\n\nThe official [GitHub Action](https://github.com/marketplace/actions/ai-seo-audit) can gate a workflow and maintain a sticky PR comment:\n\n```yaml\nname: AI SEO Audit\non:\n  pull_request:\n\njobs:\n  audit:\n    runs-on: ubuntu-latest\n    permissions:\n      pull-requests: write\n    steps:\n      - uses: agencyenterprise/aiseo-audit@v2\n        with:\n          url: https://yoursite.com\n          fail-under: 70\n          comment-on-pr: true\n```\n\nCalibrate `fail-under` against your own pages before making the check blocking. A one-line CI invocation also works:\n\n```bash\nnpx aiseo-audit https://yoursite.com --fail-under 70\n```\n\n## Use with AI Assistants (MCP)\n\nThe included [MCP](https://modelcontextprotocol.io) server exposes an `audit_url` tool to Cursor, Claude Desktop, Windsurf, and other MCP clients:\n\n```json\n{\n  \"mcpServers\": {\n    \"aiseo-audit\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"aiseo-audit-mcp\"]\n    }\n  }\n}\n```\n\nThe tool accepts optional `queries` and `domain` arguments. No separate server installation is required.\n\n## Configuration\n\nThe CLI searches upward from the current directory for `aiseo.config.json`, `.aiseo.config.json`, or `aiseo-audit.config.json`.\n\n```json\n{\n  \"queries\": [\"how to audit ai seo\", \"ai seo checklist\"],\n  \"domain\": \"auto\",\n  \"format\": \"html\",\n  \"weights\": {\n    \"answerability\": 2,\n    \"groundingSignals\": 2,\n    \"queryAlignment\": 2\n  }\n}\n```\n\nMissing weight keys default to `1`; set a category to `0` to exclude it. See [CLI configuration](docs/CLI.md#configuration) for all fields, defaults, and examples.\n\n## Programmatic API\n\n```typescript\nimport { analyzeUrl, loadConfig, renderReport } from \"aiseo-audit\";\n\nconst config = await loadConfig();\nconst result = await analyzeUrl({ url: \"https://example.com\" }, config);\nconst html = renderReport(result, { format: \"html\" });\n\nconsole.log(result.overallScore, result.grade);\n```\n\nThe package supports ESM and CommonJS and exports the analyzer, sitemap, report, diff, configuration, and scoring types. See the [API guide](docs/API.md).\n\n## Limitations\n\n- **Fetched HTML, not a browser-rendered DOM.** The audit does not execute client-side JavaScript. Server-rendered and pre-rendered content is visible; content added only after page load may be missed.\n- **No visual or multimodal assessment.** Layout quality, intrusive ads, visual hierarchy, and information carried only in images are outside the audit. Image `alt` text can be inspected, but pixels are not.\n- **Public HTTP access is assumed.** Authentication, consent flows, personalization, bot mitigation, and geography can change what the audit receives.\n- **Network responses can vary.** Determinism applies to the scoring of identical fetched inputs; redirects, dynamic HTML, experiments, and server failures can change those inputs.\n- **Sitemap processing is sequential.** There is currently no CLI URL cap, so use intentionally scoped sitemaps when runtime matters.\n- **Engine behavior remains nondeterministic.** A readiness score cannot predict whether a deployed engine will retrieve or cite a page for a particular answer.\n\n## Research and Methodology\n\nThe scoring model is informed by peer-reviewed research on generative engine optimization (GEO) and generative information retrieval, including fixed-context experiments, retrieval studies, and observations of deployed engines. Evidence strength and experimental scope matter: weights and thresholds remain expert-set heuristics rather than fitted probabilities.\n\n- [Audit Breakdown](docs/AUDIT_BREAKDOWN.md): every category, factor, band, stage, and gate\n- [Evidence](docs/EVIDENCE.md): factor-to-evidence traceability and evidence tiers\n- [Emerging Research](docs/EMERGING_RESEARCH.md): cross-paper synthesis and maintenance policy\n- [Paper Reviews](docs/paper-reviews/README.md): primary-source reviews behind the current model\n\n## Migrating from 1.x\n\nVersion 2.0 rescored the factor set, so the same page will usually receive a different score. Re-baseline key pages and recalibrate CI thresholds before changing a GitHub Action from `@v1` to `@v2`. Existing 1.x config and baseline data remain readable, but the JSON emitted by `--tldr` changed shape.\n\nSee the complete [2.0 migration guide](docs/MIGRATION-2.0.md).\n\n## Documentation\n\n- [Website and guides](https://aiseo-audit.com/)\n- [CLI and configuration](docs/CLI.md)\n- [Programmatic API](docs/API.md)\n- [Scoring methodology](docs/AUDIT_BREAKDOWN.md)\n- [Evidence map](docs/EVIDENCE.md)\n- [Research synthesis](docs/EMERGING_RESEARCH.md)\n- [Future work](docs/FUTURE_PHASES.md)\n- [Changelog](CHANGELOG.md)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and pull request guidelines. Security issues should follow [SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 12301,
  "sha": "c6d48e09cd65b1536c78b486aa07270a81e046d379288c8785c7ace92752ba29",
  "repo_slug": "agencyenterprise/aiseo-audit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_agencyenterprise_aiseo_audit_74b9980c/readme"
}