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.

Changelog

All notable changes to angeo/module-aeo-audit will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[3.1.0] — 2026-06-10

Minor release. Adds per-signal enable/disable configuration, configurable
sitemap placeholder-slug handling, and fixes two false-signal bugs in the
sitemap checker. Fully backward compatible — no interface or DB changes.

Added

• Per-signal configuration. Every one of the 15 signals can now be enabled
  or disabled individually under Stores → Configuration → Angeo AEO → AEO
  Audit → Signals (Checks). All signals are enabled by default, so a
  fresh install behaves exactly as before. Disabled signals are skipped during
  the audit and excluded from the score entirely — they neither raise nor lower
  it (removed from both numerator and denominator). Settings are store-scoped.
• Configurable sitemap placeholder-slug handling. New group Angeo AEO →
  AEO Audit → Sitemap Checker:
  • Placeholder slug handling — Affect score (default) or Ignore
    (report-only, never changes status/score).
  • Placeholder slug threshold — how many placeholder slugs are tolerated
    before the score is affected (default 1).
• New Angeo\AeoAudit\Model\Config — a single typed reader for all module
  settings, so checkers no longer touch ScopeConfig directly.
• New Angeo\AeoAudit\Model\Config\Source\SlugMode option source.
• Unit tests: disabled-checker skipping in AuditRunner; sitemap foreign-element
  FAIL; placeholder-slug score/ignore modes; disproportion-false-positive
  regression.

Fixed

• Sitemap: false "disproportion" warning. The v3 check compared sitemap URL
  count against active products only, but a sitemap also lists the homepage,
  CMS pages and categories — so healthy stores were frequently warned. URL count
  is now compared against the full indexable surface (products + categories +
  CMS pages) and reported as informational context only (coverage_ratio);
  it never changes the result status.
• Sitemap: false "stale" warning. Staleness was computed from the first
  <lastmod> in the file, so a single old entry (often the homepage or a CMS
  page) flagged the whole sitemap as stale. A legitimately unchanged product
  should keep an old <lastmod> — that is honest metadata, not a defect. The
  check now inspects the newest <lastmod> across the file and only warns
  if nothing at all has changed in 180 days (a sign of a broken generation
  cron). Individual old entries are informational only.

Added — sitemap structural integrity

• Sitemap: foreign-element detection. Non-sitemap elements injected directly
  into <urlset> (e.g. a stray <script> from a theme or module) are now
  detected and reported as a FAIL. libxml parses such markup without error, so
  the previous XML-validity check missed it.
• Sitemap: placeholder-slug detection. Slugs that carry no meaning for an AI
  engine (test2.html, product-name.html, bare numbers, etc.) are surfaced so
  they can be renamed. Behaviour is controlled by the new configuration above.

[3.0.0] — 2026-05-22

Major release. Adds 6 new checkers, refactors the checker architecture, and
requires changes in third-party modules that implement CheckerInterface.

⚠️ Breaking changes

• CheckerInterface::check() signature changed from
  check(string $baseUrl): CheckResult to
  check(\Magento\Store\Api\Data\StoreInterface $store): CheckResult.
  Custom checkers must be updated. The base URL is available via
  $store->getBaseUrl() or StoreUrlSampler::getBaseUrl($store).
• CheckerInterface adds two required methods: getCategory(): string and
  getSeverity(): string. Subclassing AbstractChecker provides sensible
  defaults (technical / weight-derived severity). Custom checkers extending
  the interface directly need to implement both.
• AbstractChecker constructor signature changed. Now requires
  HttpCache and StoreUrlSampler instead of Curl. DI handles this
  automatically for checkers that don't override the constructor.

Added — 6 new checkers (now 15 total signals)

• MerchantPoliciesChecker — validates hasMerchantReturnPolicy +
  OfferShippingDetails + priceValidUntil + itemCondition on a sampled
  product. Required by Google AI Mode and ChatGPT Shopping since Jan 2026.
  Weight 0.9.
• OrganizationSchemaChecker — validates Organization / OnlineStore
  JSON-LD on the homepage. Establishes brand entity in AI knowledge graphs.
  Weight 0.8.
• UcpProfileChecker — validates /.well-known/ucp (Universal Commerce
  Protocol, integration with angeo/module-ucp). HTTPS-only, JWK validation
  including leaked-private-key detection (CRITICAL security check).
  Weight 0.9.
• JsonLdQualityChecker — three-page scan (home + product + category) with
  @context validation, duplicate-schema detection, BreadcrumbList /
  ItemList / WebSite+SearchAction presence. Weight 0.7.
• WellKnownAggregateChecker — inventory matrix for /.well-known/ucp,
  ai-plugin.json, security.txt, mcp. Weight 0.5.
• CoreWebVitalsChecker — LCP / INP / CLS via Google CrUX API
  (requires API key under Stores → Configuration → Angeo AEO).
  Category external_api. Weight 0.5.

Added — architecture

• Service\HttpCache — request-scoped HTTP cache. Eliminates duplicate
  fetches across checkers (a single runAll() for 10 stores went from
  hundreds of HTTP requests to a few dozen).
• Service\StoreUrlSampler — centralized product / category / CMS URL
  sampling, memoized per store. Replaces ad-hoc sampling logic inside
  individual checkers.
• --category CLI flag — filter checkers by category
  (technical|live_signal|external_api|feed). Useful for fast cron checks.
• --fail-on-severity CLI flag — fail the build on critical / important
  / info severity. Complements --fail-on=<score> for CI.
• Per-checker timeout logging — slow checkers (>30s) emit warning to log;
  checker exceptions no longer halt the audit run.
• Test/Unit/Model/Checker/CheckerTestHelper trait — shared test scaffolding
  for checker unit tests.

Enhanced — existing checkers

• RobotsTxtChecker: detects versioned UAs (GPTBot/1.0), Crawl-delay
  on bots that ignore it, HTTP sitemap directives, conflicting Allow: /
  Disallow: rules. AI bot list expanded to 12.
• SitemapXmlChecker: detects sitemap.xml.gz, compares URL count to
  active catalog product count (warns on >30% delta).
• LlmsTxtChecker: validates store-locale + currency match metadata;
  flags cross-host links on subdomain stores.
• CanonicalChecker: now cross-checks canonical against og:url and
  Product JSON-LD url; verifies HTTPS; checks hreflang presence on
  multi-store setups.

Considered and rejected — ai_bot_traffic checker

An access-log-based AI-bot traffic checker was prototyped during the v3
development cycle and excluded from the release after a security and
usefulness review. The summary, recorded so the trade-off is documented:

• Encouraged poor permissions hygiene. The natural way to make
  /var/log/nginx/access.log readable to PHP-FPM is usermod -aG adm www-data or chmod 644, both of which expose unrelated sensitive logs
  (auth.log, syslog) to any future LFI/RCE in the application. The
  bundled ACL guidance helped, but a module whose presence creates the
  incentive at all violates "secure by default".
• Unusable on managed platforms. On Adobe Commerce Cloud, Magento
  Cloud, and any containerised hosting, nginx logs go to stdout and
  centralised collection (Fastly/New Relic/Splunk). PHP-FPM cannot read
  them at all. The check returns WARN on these platforms 100% of the
  time, contributing only noise.
• Dominated by false positives. Even on self-hosted setups, sites
  behind Cloudflare/Fastly with edge caching never see the AI bots reach
  origin — the bots are served from edge. WARN again.
• Better-served externally. Edge analytics (Fastly, Cloudflare
  Analytics), APM platforms (New Relic, Datadog), and dedicated log
  analyzers (GoAccess, Matomo) measure AI-bot traffic without coupling
  it to PHP application permissions.

This means 15 built-in signals, not 16. The live_signal category
remains in CheckerInterface for third-party modules that have their own
secure live-signal source — notably angeo/module-aeo-brand-visibility,
which queries AI provider APIs rather than parsing host logs.

Configuration

• New encrypted config field: angeo_aeo/crux/api_key
  (Stores → Configuration → Angeo AEO → CrUX API Key).

Suggested

• New suggest entry: angeo/module-ucp — companion module for UCP profile.
• New suggest entry: angeo/module-aeo-brand-visibility — live AI
  visibility checker (adds a brand_visibility signal via DI injection).

Migration guide for v2 → v3

For most users (using only built-in checkers): composer update. No code
changes needed.

For custom checkers extending AbstractChecker: update the check() signature:

- public function check(string $baseUrl): CheckResult
+ public function check(\Magento\Store\Api\Data\StoreInterface $store): CheckResult
  {
-     [$status, $html] = $this->fetch($baseUrl . '/path');
+     $base = $this->urlSampler->getBaseUrl($store);
+     [$status, $html] = $this->fetch($base . '/path');
  }

For custom checkers implementing CheckerInterface directly: also add
getCategory() and getSeverity(). Sensible defaults:

public function getCategory(): string { return CheckerInterface::CATEGORY_TECHNICAL; }
public function getSeverity(): string { return CheckerInterface::SEVERITY_IMPORTANT; }

[2.1.2] — 2026-05-01

Fixed

• Recursive @graph parsing in JSON-LD extraction — handles nested @graph and top-level array roots correctly
• Bug-report URL in fallback error path now points to the correct repository
• Composer constraint accuracy: explicit ^ ranges for Magento dependencies instead of *
• Test/ directory excluded from production classmap

Added

• Unit tests for ProductSchemaChecker, FaqSchemaChecker, ProductFeedChecker, LlmsJsonlChecker (9 of 9 checkers now have tests)
• CHANGELOG.md and CONTRIBUTING.md
• GitHub Actions CI workflow (PHPUnit + PHPStan + MCS)
• Magento Coding Standard as a require-dev dependency

Changed

• README updated with explicit Magento version compatibility (2.4.6, 2.4.7, 2.4.8)
• README mentions tested PHP versions (8.2, 8.3, 8.4)
• Removed hardcoded version field from composer.json — Packagist resolves from git tags

[2.1.1] — 2026-04-24

Added

• getFixCommand() method on CheckerInterface for dynamic CLI fix suggestions
• LlmsJsonlChecker for /llms.jsonl validation
• Score Trend dashboard in admin UI

[2.1.0] — 2026-04-15

Added

• Score Trend dashboard
• Dynamic fix commands in CLI output
• Deeper llms.txt validation (12 checks)

[2.0.0] — 2026-03-20

Added

• Deep robots.txt parser with first-match semantics
• Product schema validation including offers.availability
• Hyvä theme detection
• Admin UI with results grid
• Cron scheduling (weekly Monday 03:00)
• Extensible architecture via CheckerInterface + di.xml

Changed

• Weighted scoring: critical signals weight 1.0, informational lower

[1.0.0] — 2026-02-10

Added

• Initial release with 6 AEO signal checks
• CLI command bin/magento angeo:aeo:audit
• Table, JSON, and Markdown output formats