Module reference

AEO Audit for Magento 2 — module reference

Covers angeo/module-aeo-audit 4.2.4 · Checked 16 October 2026 · MIT licensed

AEO Audit checks how ready a Magento 2 store is for AI answer engines such as ChatGPT, Gemini, Claude and Perplexity. One command scores 20 signals per store view. For every failed signal it tells you what is wrong and how to fix it.

The module only reads. It does not change your store. You can run it on production, on staging, or in a CI pipeline.

What it checks

The audit has two layers. Configuration signals check that the store is set up for AI engines. Evidence signals (added in 4.0.0) check that AI crawlers can really reach the store.

You can switch each signal on or off in the configuration. A switched-off signal is not part of the score.

Bots are judged by purpose

The audit knows three kinds of AI bot:

• Search bots (OAI-SearchBot, PerplexityBot, Claude-SearchBot) index pages for AI answers. Blocking one is a fail, because the store drops out of AI answers.
• Training bots (GPTBot, ClaudeBot, CCBot) collect pages to train models. Blocking one is your licensing choice. It is reported, but it does not lower the score.
• Opt-out tokens (Google-Extended, Applebot-Extended) never crawl. They are shown as notices.

The evidence layer

waf_reality and ai_crawler_activity work together:

Crawler activity comes from built-in counting at the PHP level (on by default). You can add your web server access log, or your own source through BotHitSourceInterface. Only daily totals per bot are stored. No IP addresses, URLs or user agents.

Requirements

The audit works best with the other angeo modules installed, because most fix hints point to one of them. It also works alone.

Installation

composer require angeo/module-aeo-audit
bin/magento module:enable Angeo_AeoAudit
bin/magento setup:upgrade
bin/magento setup:di:compile                # production mode only
bin/magento setup:static-content:deploy     # production mode only
bin/magento cache:flush

Running the audit

# All store views
bin/magento angeo:aeo:audit

# One store view
bin/magento angeo:aeo:audit --store=en_us

# JSON for dashboards, Markdown for reports
bin/magento angeo:aeo:audit --format=json
bin/magento angeo:aeo:audit --format=markdown --output=/var/www/html/aeo-report.md

# Only fast technical checks, no external APIs
bin/magento angeo:aeo:audit --category=technical

# Fail a CI build below a score, or on any critical failure
bin/magento angeo:aeo:audit --fail-on=80
bin/magento angeo:aeo:audit --fail-on-severity=critical

# Do not save the result to the database
bin/magento angeo:aeo:audit --no-save

The score reads like this:

Admin panel

• Marketing → Angeo AEO → AEO Audit Results shows every past audit.
• Marketing → Angeo AEO → Score Trend shows the score over time.
• Run Audit Now starts an audit from the admin. It is a POST action with a form key, and it needs the Angeo_AeoAudit::run_audit permission.

Configuration reference

All settings are under Stores → Configuration → Angeo → AEO Audit. The table shows each field, its config path (for bin/magento config:set) and its default value.

Signals (Checks) (18)

Setting	Config path	Default
robots.txt — AI bot access	angeo_aeo/signals/robots_txt	Yes
llms.txt	angeo_aeo/signals/llms_txt	Yes
llms.jsonl — machine-readable catalog	angeo_aeo/signals/llms_jsonl	Yes
sitemap.xml — AI crawler discovery	angeo_aeo/signals/sitemap	Yes
Product JSON-LD schema	angeo_aeo/signals/product_schema	Yes
Merchant return & shipping policies	angeo_aeo/signals/merchant_policies	Yes
Organization JSON-LD schema	angeo_aeo/signals/organization_schema	Yes
UCP profile (/.well-known/ucp)	angeo_aeo/signals/ucp_profile	Yes
AI product feed	angeo_aeo/signals/ai_product_feed	Yes
JSON-LD quality	angeo_aeo/signals/jsonld_quality	Yes
Canonical & hreflang	angeo_aeo/signals/canonical	Yes
Open Graph tags	angeo_aeo/signals/open_graph	Yes
FAQPage schema	angeo_aeo/signals/faq_schema	Yes
well-known endpoint matrix	angeo_aeo/signals/well_known	Yes
Core Web Vitals (CrUX)	angeo_aeo/signals/core_web_vitals	Yes
A2A Agent Card	angeo_aeo/signals/agent_card	Yes
Edge vs robots.txt consistency (WAF reality)	angeo_aeo/signals/waf_reality	Yes
AI crawler activity (observed)	angeo_aeo/signals/ai_crawler_activity	Yes

General (1)

Setting	Config path	Default
Show fix suggestions	angeo_aeo/general/show_fix_suggestions	Yes

Live Signal (Observed Crawler Activity) (4)

Setting	Config path	Default
Built-in instrumentation	angeo_aeo/live_signal/instrumentation_enabled	Yes
Webserver access log path (optional)	angeo_aeo/live_signal/access_log_path	—
Evidence window (days)	angeo_aeo/live_signal/window_days	30
Counter retention (days)	angeo_aeo/live_signal/retention_days	90

Scheduled Audit (1)

Setting	Config path	Default
Cron schedule	angeo_aeo/cron/schedule	0 3 * * 1

Sitemap Checker (2)

Setting	Config path	Default
Placeholder slug handling	angeo_aeo/sitemap/placeholder_slug_mode	score
Placeholder slug threshold	angeo_aeo/sitemap/placeholder_slug_threshold	1

Core Web Vitals (CrUX API) (1)

Setting	Config path	Default
CrUX API Key	angeo_aeo/crux/api_key	— (stored encrypted)

The CrUX API key is free. Create it in the Google Cloud console and enable the Chrome UX Report API. Without a key, the Core Web Vitals check is skipped.

To read an access log, point the module at a file the PHP user can read. Do not chmod the live log. Give targeted access instead, for example setfacl -m u:www-data:r /var/log/nginx/access.log. Only the last 8 MB of the file is read.

Cron and stored data

The scheduled audit runs every Monday at 03:00 by default. It keeps the last 50 results per store. Old bot counters are removed after the retention period.

Adding your own check

Implement Angeo\AeoAudit\Api\CheckerInterface, or extend Angeo\AeoAudit\Model\Checker\AbstractChecker (it gives you the HTTP cache, URL sampling and JSON-LD parsing). Then register it in di.xml:

<type name="Angeo\AeoAudit\Model\AuditRunner">
    <arguments>
        <argument name="checkers" xsi:type="array">
            <item name="my_check" xsi:type="object">Vendor\Module\Model\Checker\MyChecker</item>
        </argument>
    </arguments>
</type>

A checker returns its name, code, weight (0–1), category, severity and a fix command, and runs check(StoreInterface $store). One failing checker does not stop the audit.

FAQ

Does the audit change anything on my store?

No. It only reads pages and configuration. It writes only its own result rows, and you can turn that off with --no-save.

Why does blocking GPTBot not lower my score?

GPTBot collects pages for model training. Blocking it is a licensing choice and does not remove you from AI search. Blocking a search bot such as OAI-SearchBot does, so that one fails the audit.

Can I use it in CI?

Yes. Use --format=json for machine-readable output and --fail-on or --fail-on-severity to fail the build. Add --category=technical for a fast run without external APIs.

Why is Core Web Vitals skipped?

The check needs a free Google CrUX API key. Add it under Core Web Vitals (CrUX API) in the configuration. Small stores may also have no CrUX data yet.

Does it work with Hyvä?

Yes. The product schema check detects Hyvä, and the module has no storefront code.

Related

• Robots.txt AEO — manage AI crawler rules in robots.txt and verify real bots
• llms.txt — generate llms.txt, llms.jsonl, Markdown mirrors and agents.md
• Rich Data — one linked JSON-LD graph per page, with offers and policies
• AEO Brand Visibility — measure whether AI assistants name and recommend your store
• AI Agent Activity — report on AI agent calls, crawler visits, fake bots and agent-built orders
• All module reference pages · Compatibility matrix

This page was written from the README.md, composer.json and etc/*.xml files of tag 4.2.4, read on 16 October 2026. Settings, commands and defaults come straight from that code. If a newer release is out, the README on GitHub wins.