Angeo AEO Audit — AI Engine Optimization for Magento 2

One CLI command that tells you exactly why ChatGPT, Gemini, Claude, and Perplexity aren't recommending your store — and how to fix it.

• 🏠 Project home: angeo.dev
• 📦 Source: github.com/angeo-dev/module-aeo-audit
• 🐛 Issues: github.com/angeo-dev/module-aeo-audit/issues
• 📖 Full guide: Magento 2 AEO Guide 2026

Compatibility

Tested with: Magento Open Source 2.4.7-p3 + PHP 8.3 + Hyvä 1.3.

What's new in v3.0.0

Major release — see CHANGELOG.md for the breaking-change migration guide if you have custom checkers.

15 signals (up from 9), reflecting the actual AEO landscape of 2026: AI shopping integrations, merchant policies, agentic commerce, and structured-data quality.

6 new checkers:

• merchant_policies — MerchantReturnPolicy + OfferShippingDetails — required by Google AI Mode and ChatGPT Shopping since Jan 2026
• organization_schema — brand entity in AI knowledge graphs
• ucp_profile — Universal Commerce Protocol (/.well-known/ucp), with built-in security check that detects leaked JWK private keys
• jsonld_quality — three-page schema breadth audit (homepage / category / product), WebSite+SearchAction, BreadcrumbList, ItemList
• well_known — discovery matrix for /.well-known/{ucp,ai-plugin.json,security.txt,mcp}
• core_web_vitals — LCP / INP / CLS via Google CrUX API (free, opt-in with API key)

Refactored architecture (this is the BC-break):

• Shared Service\HttpCache — eliminates duplicate fetches across checkers (hundreds of redundant HTTP requests on multi-store audits before, dozens now)
• Service\StoreUrlSampler — single source of truth for product / category / CMS URL sampling
• New --category and --fail-on-severity CLI flags for CI workflows
• Per-checker exception isolation — slow or failing checkers no longer halt the audit run

Note on access-log monitoring: an ai_bot_traffic checker was prototyped during v3 development and excluded from the release after security review — it encouraged broad read access on /var/log/nginx/, didn't work on Cloud/containerised hosting, and was dominated by false positives behind edge caches. AI-bot traffic is better measured at the edge (Fastly/Cloudflare Analytics) or via APM (New Relic, Datadog) than inside a PHP module. See CHANGELOG.md "Considered and rejected" for the full rationale. The live_signal category remains in CheckerInterface for third-party modules with secure live-signal sources — notably angeo/module-aeo-brand-visibility.

What it checks — 15 signals

★ NEW = added in v3.0.0.

Installation

composer require angeo/module-aeo-audit
bin/magento setup:upgrade
bin/magento cache:flush

For full coverage, install the companion modules:

composer require \
  angeo/module-llms-txt \
  angeo/module-rich-data \
  angeo/module-openai-product-feed \
  angeo/module-openai-product-feed-api \
  angeo/module-ucp \
  angeo/module-aeo-brand-visibility

CLI usage

# Audit all stores
bin/magento angeo:aeo:audit

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

# JSON output (for dashboards / CI)
bin/magento angeo:aeo:audit --format=json

# Markdown report to file
bin/magento angeo:aeo:audit --format=markdown --output=/var/www/html/aeo-report.md

# Fast technical-only checks (skip external APIs)
bin/magento angeo:aeo:audit --category=technical

# Run only external-API checks (Core Web Vitals + any third-party live signals)
bin/magento angeo:aeo:audit --category=external_api,live_signal

# Fail build if score below threshold
bin/magento angeo:aeo:audit --fail-on=80

# Fail build if any critical-severity check fails
bin/magento angeo:aeo:audit --fail-on-severity=critical

# Run without saving to DB (CI / read-only environments)
bin/magento angeo:aeo:audit --no-save

Sample output:

  AEO Score: [████████████████░░░░] 81% — Good
  ✓ Pass: 12  ⚠ Warn: 3  ✗ Fail: 1

  Critical fixes needed:
  → Install angeo/module-openai-product-feed and register at chatgpt.com/merchants

  💡 Fix with angeo modules:
     composer require angeo/module-openai-product-feed angeo/module-openai-product-feed-api
     composer require angeo/module-ucp

Configuration

Some checkers need configuration. All are accessed via: Stores → Configuration → Angeo AEO.

Admin UI

• Marketing → Angeo AEO → AEO Audit Results — full history grid
• Marketing → Angeo AEO → Score Trend — line chart of AEO score over time
• ▶ Run Audit Now button (on the Audit Results grid, Score Trend, and result view pages) — triggers an on-demand audit. Since 3.1.0 this is a POST action protected by the admin form key and the dedicated Angeo_AeoAudit::run_audit ACL permission; the old GET menu entry was removed.

Score interpretation

Cron

Weekly audit every Monday at 03:00 server time. Results saved to DB, last 50 per store retained.

bin/magento cron:run --group=default

For fast daily checks (without external APIs or log scans), schedule an additional cron job calling the audit with --category=technical.

Extending with custom checks

Implement Angeo\AeoAudit\Api\CheckerInterface (or extend Angeo\AeoAudit\Model\Checker\AbstractChecker, which provides HTTP cache, URL sampling and JSON-LD parsing), and register via 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>

v3 interface:

public function getName(): string;       // "My Custom Check"
public function getCode(): string;       // "my_check"
public function getWeight(): float;      // 0.0–1.0
public function getCategory(): string;   // CheckerInterface::CATEGORY_*
public function getSeverity(): string;   // CheckerInterface::SEVERITY_*
public function getFixCommand(): string; // "composer require vendor/fix-module" or ""
public function check(\Magento\Store\Api\Data\StoreInterface $store): CheckResult;

Migrating from v2? See CHANGELOG.md for the migration guide.

Running tests

vendor/bin/phpunit -c app/code/Angeo/AeoAudit/phpunit.xml

v3 ships with unit tests covering all 15 checkers, both services (HttpCache, StoreUrlSampler), the AuditRunner, and the report value objects.

Code quality

# Magento Coding Standard
vendor/bin/phpcs --standard=Magento2 \
    --extensions=php,phtml --severity=10 \
    app/code/Angeo/AeoAudit/

# PHPStan static analysis
vendor/bin/phpstan analyse -l 5 app/code/Angeo/AeoAudit/

The Angeo AI Visibility Suite

Contributing

Issues and PRs welcome at github.com/angeo-dev/module-aeo-audit.

Before opening a PR:

1. Run vendor/bin/phpunit -c phpunit.xml — all tests must pass
2. Run vendor/bin/phpcs --standard=Magento2 — no MCS violations
3. Add tests for any new checker

License

MIT — see LICENSE

Made with care by Ievgenii Gryshkun — open-source contributions to the Magento + AI commerce ecosystem.