mage2kishan / module-ai-visibility

1.3.0 2026-11-03 06:54 UTC

Requires

• php: ~8.1.0||~8.2.0||~8.3.0||~8.4.0||~8.5.0
• mage2kishan/module-core: *
• magento/framework: ^103.0
• magento/module-backend: ^102.0
• magento/module-config: ^101.2
• magento/module-cookie: ^100.4
• magento/module-cron: ^100.4
• magento/module-email: ^101.1
• magento/module-page-cache: ^100.4
• magento/module-sales: ^103.0
• magento/module-store: ^101.1
• magento/module-ui: ^101.2

MIT

• Kishan Savaliya

• analytics
• seo
• ai
• magento2
• magento2-module
• attribution
• llm
• panth
• ai-crawlers
• ai-referrals

Published on Packagist.org on 2026-11-03 06:54 UTC

README

Panth AI Visibility shows how AI crawlers and AI assistants use a Magento 2 store. It counts requests from AI crawlers (training, search and live-answer bots), including pages served from Magento's built-in full page cache, detects shoppers who arrive from AI assistants such as ChatGPT, Perplexity, Gemini or Copilot, credits their orders to the assistant, and presents the results on an admin dashboard with insights and data-health checks.

Version 1.1 turns the numbers into a to-do list: every night rules check the collected data and list concrete fixes ranked by how much AI traffic they affect (for example pages that answer 404 to AI bots, or products no AI bot has fetched). When you mark a fix as applied, the module compares the traffic before and after the change with similar pages or products you did not change and reports whether the fix likely helped, always with a range. A weekly summary email and CSV exports of every report are included.

Version 1.2 learns from the store's own data. It learns the normal hourly levels of AI traffic and raises alerts when a bot stops, traffic spikes, errors or response times jump, or AI visits drop. It estimates AI visits that arrive without a referrer (always as a separate estimate with a range, never added to confirmed numbers) and tags orders as "Probable AI" in their own column. It scores products for AI readiness with weights learned from which products AI bots fetch on this store, ranks recommendations by what actually worked here, can run selected fixes automatically (off by default, with a kill switch and undo), and can check AI bot IP addresses against the lists their operators publish. Eleven rules now check the data every night, including a rule for spoofed AI bots. Every model needs a minimum amount of data first and says how much is still missing; until then built-in defaults apply.

Version 1.3 adds an experimental, off-by-default feature for AI assistants built into the browser (for example Gemini in Chrome): through WebMCP, storefront pages can offer a few shop tools (search products, product details, show the cart and, only when you select it, add to cart) that the browser's agent calls instead of reading and clicking through pages. The module counts how agents use these tools and which orders follow, always apart from confirmed and probable AI orders (see Browser agents (WebMCP, experimental)).

Everything is measured and stored inside the Magento database. The module sends no data to third-party services. Its only outbound request is the optional, off-by-default download of the IP lists that AI companies publish for their bots (see Bot IP Verification).

Features

• AI crawler tracking. 22 built-in AI bots from OpenAI, Anthropic, Perplexity, Meta, Amazon, Apple, DuckDuckGo, Mistral, You.com, ByteDance, Common Crawl, Cohere and Diffbot (for example GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-SearchBot, Claude-User, PerplexityBot, Perplexity-User, Amazonbot, Applebot, Bytespider, CCBot). Each hit is stored with bot, company, category, store view, page type (product, category, CMS, other), path, HTTP status and response time.
• Cached pages are counted. Hits are recorded while Magento serves the response, including built-in full page cache hits. Human visitors only cost an in-memory User-Agent check and cause no database work.
• Bot categories. Every bot is classed as training (collects data for model training), search (builds an AI search index) or live answer (fetches a page while a user is waiting for an answer), so the dashboard shows which kind of AI traffic a page receives.
• AI referral visits. A small CSP-safe collector script (under 2 KB, no libraries, works on Hyva and Luma) reports once per browser session when a shopper arrives from an AI assistant. Built-in sources: ChatGPT, Perplexity, Gemini, Microsoft Copilot, Claude, Meta AI, Le Chat (Mistral), DeepSeek, Grok and You.com, recognised by referrer host or utm_source. Custom hosts and utm_source values can be added.
• Signed attribution cookie. The first and the latest AI source are kept in a signed, HttpOnly, SameSite=Lax first-party cookie (panth_aiv) for a configurable attribution window. Magento cookie consent is respected.
• Order attribution. Orders placed through the one-page checkout and the multishipping checkout are tagged with the first-touch and the last-touch AI source. An "AI Source" column and filter appear in the order grid, and an "AI Attribution" block on the order view. The attribution model (first or last touch) can be switched at any time without losing data. Since 1.2 a separate "Probable AI (%)" column shows orders that probably came from an AI assistant without a referrer (see Hidden AI traffic and probable AI orders).
• Dashboard and insights. KPIs, server-rendered SVG charts, top pages, top bots, AI visits and revenue by source, with a date range and store view filter. Insights point out AI bots blocked by robots.txt, llms.txt fetches, products that AI bots have not fetched and bot error rates.
• Crawler Log. Admin grid of detailed crawler hits with filters, column controls and export.
• Discovery. Bot-like User-Agents that are not in the catalogue, clients that fetch /llms.txt, and AI-looking referrer hosts and utm_source values are listed as candidates. Confirm a candidate as AI (it is then counted like a built-in bot or source, including its earlier hits), mark it Not AI, or ignore it. Ordinary browsers and well-known search engine, social, SEO and uptime bots are never listed.
• Data-health checks. Eight checks (page cache, cron, collector, cookie consent, table size, access log import, tracking switches, bot IP lists) run hourly and on demand, and are shown on the dashboard.
• Access log importer for Varnish and CDN stores. Cached responses served by Varnish or a CDN never reach Magento. The importer reads nginx, Apache and varnishncsa access logs (combined format) with resume, rotation detection and locking, so these hits are counted as well.
• Traffic simulator. A deterministic generator creates realistic test traffic (marked as simulated and hidden on the dashboard by default) and removes it again with one option. Since 1.3 it can also plant simulated browser agent (WebMCP) sessions and orders.
• Bounded storage. Raw rows are kept for a configurable number of days, daily summaries for a configurable number of months, and a daily cap limits detailed rows during a crawler storm while totals stay correct.
• Recommendations (1.1). Eleven rules (ten since 1.1, spoofed AI bots since 1.2) run nightly per store view and list concrete fixes on Panth Infotech > AI Visibility > Recommendations, ranked by an impact score of 0 to 100, each with its evidence (numbers, date range, top examples, bots involved), a "How to fix" text and a link to the admin page where the fix is made. Each recommendation can be marked as applied (with an optional note), dismissed for 30 days, or rated useful / not useful; "not useful" lowers the ranking of that rule. The rules only read data; nothing in the store is changed automatically unless Auto-Actions are switched on.
• Fix verification (1.1). An applied fix is checked after the verification window (default 14 days before vs 14 days after, UTC days). The result reads "Likely helped", "No clear effect", "Likely made it worse" or "Not enough data yet", always with a 95% range and a before / after bar chart. "Likely helped" means the whole range points to an improvement. A fix can be undone while it is still waiting for its verdict.
• Weekly summary email (1.1). Once a week cron emails AI crawler hits, live-answer fetches, AI visits, orders and revenue compared with the week before, the top pages and AI sources, the top open recommendations, verdicts reached that week and new Discovery candidates. Plain HTML, no images, no tracking.
• CSV export (1.1). The dashboard exports the daily series, top pages, bots, AI sources, recommendations, verdicts and (since 1.3) the daily browser agent tool calls as CSV with the dashboard's date range and store view filter. Cells that could start a spreadsheet formula are neutralised.
• Normal levels and alerts (1.2). Hourly series per bot, bot category, AI source, error share, response time and AI visits are compared with the normal level learned for that weekday and hour. Alerts appear on the Alerts page and a dashboard card, optionally by email, and learn from Useful / Not useful feedback.
• Hidden AI traffic estimate (1.2, experimental, off by default). An estimate of AI visits without a referrer, from direct landings that follow a live AI fetch of the same page, shown next to the confirmed AI visits with a likely range. It is never added to confirmed visits, orders or revenue.
• Probable AI orders (1.2). When the visit that led to an order was likely enough to come from an AI assistant (default at least 80%), the order gets a "Probable AI" tag with the probability, in its own grid column. Confirmed attribution always wins; a probable tag never credits a source.
• AI readiness score (1.2). Every visible product gets a score from 0 to 100 from features such as description length, complete structured data, image labels, reviews and stock. The weights are learned from which products AI search and live-answer bots fetch on this store; the AI Readiness page lists the lowest-scoring products with what they miss, and "What matters on your store" names the features that make a clear difference here.
• Ranking by what worked (1.2). Rules whose verified fixes helped on this store move up, rules whose fixes did not help move down ("Worked on this store: X of Y verified fixes").
• Auto-actions (1.2). Opt-in: selected fixes can run automatically after the nightly recommendations, within a daily limit, with a global kill switch and undo. Off by default.
• Bot IP Verification (1.2). Opt-in: AI bot hits are checked against the IP lists the bot operators publish, and the "Spoofed AI bots" rule lists bots whose hits mostly come from other addresses. Off by default; it is the module's only outbound request.
• Browser agents (WebMCP, 1.3, experimental, off by default). Storefront pages can register shop tools for AI assistants built into the browser: search products, product details, show cart and, only when selected, add to cart. The tools call only this store and return catalogue data and the shopper's own cart lines, never personal data; they never go to checkout, pay or touch the customer account. Tool calls, failed calls, agent sessions, add-to-carts and orders that follow are counted as their own channel "Browser agent (WebMCP)", shown on a dashboard card, in the order grid and order view, in the weekly email and as a CSV export.
• Learned models with versions (1.2). Normal levels, the hidden traffic estimate, readiness weights and fix effectiveness are versioned per store view. A model can be reset to its built-in defaults or rolled back to the previous version; either choice is kept for 7 days before the model learns again.

Compatibility

Platform	Versions
Magento Open Source	2.4.7 to 2.4.9
Adobe Commerce	2.4.7 to 2.4.9
PHP	8.1, 8.2, 8.3, 8.4, 8.5
Themes	Hyva and Luma

Requirements

• Magento Open Source or Adobe Commerce 2.4.7 to 2.4.9.
• PHP 8.1 to 8.5.
• mage2kishan/module-core (module Panth_Core), installed automatically by Composer.
• MySQL 8 or MariaDB 10.6 or later (all module tables use utf8mb4).
• A working Magento cron for the daily summaries, retention, Discovery, health checks and the access log import.

Installation

composer require mage2kishan/module-ai-visibility
bin/magento module:enable Panth_Core Panth_AiVisibility
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

• setup:di:compile and setup:static-content:deploy are only needed in production mode.
• setup:upgrade creates the 29 panth_aiv_* tables.

Check that the module is enabled:

bin/magento module:status Panth_AiVisibility

Configuration

Settings: Stores > Configuration > Panth Infotech > AI Visibility (section panth_aivisibility, ACL resource Panth_AiVisibility::config).

Reports: Panth Infotech > AI Visibility in the admin menu, with the pages Dashboard, Recommendations, Alerts, AI Readiness, Crawler Log, Discovery and Configuration.

ACL resource	Allows
Panth_AiVisibility::dashboard	Dashboard, the "Browser agents (WebMCP)" card and the CSV exports (daily series, top pages, bots, AI sources and browser agent tool calls agent_daily)
Panth_AiVisibility::recommendations	Recommendations page (apply, dismiss, feedback, undo, check now), the "Top recommendations" and "Latest verdicts" dashboard cards and the recommendations / verdicts CSV exports (they contain admin user names and notes)
Panth_AiVisibility::alerts	Alerts page (acknowledge, Useful / Not useful feedback)
Panth_AiVisibility::readiness	AI Readiness page and its CSV export
Panth_AiVisibility::learning	Reset and roll back learned models
Panth_AiVisibility::log	Crawler Log
Panth_AiVisibility::discovery	Discovery
Panth_AiVisibility::config	Configuration section

Defaults after installation: crawler tracking, visit tracking, Discovery and recommendations are on; the access log import is off until log files are listed, the weekly summary email is off until it is switched on with at least one recipient, and the browser agent (WebMCP) shop tools are off until "Register Shop Tools for Browser AI Agents (Experimental)" is set to Yes.

Group	Setting	Default
General	Enable AI Visibility (store view scope)	Yes
General	Track AI Crawlers	Yes
General	Track Visits from AI Assistants	Yes
General	Attribution Window (days), 1 to 365	30
General	Attribution Model	First touch
AI Crawlers	Discover Unknown AI Bots and Apps	Yes
AI Crawlers	Custom AI Bots (Name | token | category | company per line)	empty
AI Crawlers	Max Detailed Hits per Day, 1000 to 10000000	200000
AI Referrer Sources	Custom AI Referrer Hosts (host | Source Name per line)	empty
AI Referrer Sources	Custom utm_source Values (utm_value | Source Name per line)	empty
Storefront Collector	Max Reports per IP per Minute, 1 to 600	20
Storefront Collector	Direct Landing Sample Rate (%), 0 to 100	25
Privacy and Data Retention	Respect Cookie Consent	Yes
Privacy and Data Retention	Keep Detailed Crawler Hits (days), 1 to 365	14
Privacy and Data Retention	Keep Detailed AI Visits (days), 1 to 730	30
Privacy and Data Retention	Keep Direct Landings (days), 1 to 365	30
Privacy and Data Retention	Keep Daily Summaries (months), 1 to 60	13
Access Log Import (Varnish / CDN)	Import Crawler Hits from Access Logs	No
Access Log Import (Varnish / CDN)	Log Files (/absolute/path/access.log | store_code per line)	empty
Access Log Import (Varnish / CDN)	Max Lines per Run, 1000 to 5000000	200000
Recommendations	Create Recommendations	Yes
Recommendations	Minimum Events per Finding, 1 to 1000000	20
Recommendations	Max Open Recommendations per Store View, 1 to 500	50
Fix Verification	Verification Window (days), 7 to 56	14
Fix Verification	Minimum Events for a Verdict, 1 to 1000000	30
Fix Verification	Max Comparison Subjects, 3 to 500	50
Weekly Summary Email	Send Weekly Summary	No
Weekly Summary Email	Recipients (comma or line separated, up to 20)	empty
Weekly Summary Email	Email Sender (store email identity)	General Contact
Weekly Summary Email	Send on (weekday, UTC)	Monday
Weekly Summary Email	Send at (UTC)	07:00
Learning	Learn from This Store's Data	Yes
Learning	Weeks Used for Normal Levels, 4 to 10	8
Learning	Minimum Weeks Before Alerts, 1 to 12	3
Alerts	Detect Unusual Changes	Yes
Alerts	Sensitivity, 0.5 to 2.0	1.0
Alerts	Email New Alerts Immediately	No
Alerts	Hours Between Emails for the Same Alert, 1 to 168	24
Hidden AI Traffic Estimate	Estimate AI Visits Without a Referrer	No (experimental)
Hidden AI Traffic Estimate	Confirmed Visits Needed, 5 to 100000	30
Hidden AI Traffic Estimate	Probable AI Order Threshold (%), 50 to 99	80
AI Readiness Score	Score Products for AI Readiness	Yes
AI Readiness Score	Products Needed to Learn Weights, 20 to 1000000	200
AI Readiness Score	Products Fetched by AI Needed, 5 to 1000000	30
AI Readiness Score	Max Weight Change per Week, 0.01 to 0.5	0.05
Recommendation Ranking	Rank by What Worked on This Store	Yes
Auto-Actions	Allow Auto-Actions (Global Kill Switch)	No
Auto-Actions	Fixes That May Run Automatically	none
Auto-Actions	Max Items per Day, 1 to 10000	100
Bot IP Verification	Verify Bot IP Addresses (Outbound Request)	No
Bot IP Verification	Published IP Lists (bot_code | https URL per line)	official lists of OpenAI, Perplexity, Apple and Common Crawl
Bot IP Verification	Warn When Lists Are Older Than (days), 1 to 90	7
Browser AI Agents (WebMCP, Experimental)	Register Shop Tools for Browser AI Agents (Experimental)	No (experimental)
Browser AI Agents (WebMCP, Experimental)	Tools Offered to Agents	search products, product details, show cart (add to cart not selected)
Browser AI Agents (WebMCP, Experimental)	Max Search Results per Call, 1 to 25	10
Browser AI Agents (WebMCP, Experimental)	Chrome Origin Trial Token (Optional, per website or store view)	empty
Browser AI Agents (WebMCP, Experimental)	Count Tool Calls and Agent Orders	Yes

Numeric settings are checked when they are used: values out of range fall back to the nearest allowed value or the default.

Console commands

Command	Purpose
bin/magento panth:aivisibility:rollup [--date=Y-m-d] [--days=N]	Rebuild the daily summaries for a day (default today) or the last N days. Safe to run any time.
bin/magento panth:aivisibility:import-logs [--file=/abs/path] [--dry-run] [--from-start --force]	Import AI crawler hits from the configured access logs now. --dry-run parses and counts without writing (also while the import is disabled). --from-start reads the files again from byte 0 and needs --force, because lines imported before are counted twice.
bin/magento panth:aivisibility:simulate --days=60 [--seed=7] [--store=1] [--scale=1] [--until=Y-m-d] [--with-orders=N] [--scenario=NAME] [--hidden-share=0-100] [--plant=sd-2x|none] [--webmcp-sessions=N] [--json] [--force] [--purge [--store=N]]	Generate deterministic simulated traffic for testing (marked is_simulated, hidden on the dashboard unless "show simulated data" is used). --days defaults to 60 (1 to 400), ending yesterday unless --until is given. --scenario plants an applied fix with a known effect (fix-helped, fix-no-effect) or bot-stops (the busiest crawler stops at 14:00 UTC on the last day, for alert testing); --hidden-share sends that share of AI visits without a referrer; --plant=sd-2x gives products with complete structured data twice the AI fetches (readiness testing). --webmcp-sessions=N (0 to 100000, default 0 = off) spreads N simulated browser agent sessions over the simulated days with a realistic tool mix (most searches, fewer product details, fewer cart reads, a few add-to-carts and a few failed calls) and, together with --with-orders, gives a small share of those orders the channel webmcp; runs without it write exactly the same rows as before. --purge removes every simulated row, including simulated agent rows; --purge --store=N only the simulated rows of store view N. Raw simulated rows older than the retention settings are removed by the nightly retention like real ones, so a long simulation keeps only its daily summaries for older days. Do not run it on a production store.
bin/magento panth:aivisibility:recommend [--store=ID] [--dry-run] [--simulated]	Evaluate the recommendation rules now and update the recommendation list. --dry-run prints the findings without saving them. --simulated also reads simulator rows (a test preview; it implies --dry-run, so simulated findings are never saved).
bin/magento panth:aivisibility:verify [--action=ID] [--dry-run]	Verify applied fixes whose verification window has ended, or one action now. --dry-run prints the result without saving it.
bin/magento panth:aivisibility:email [--dry-run [--simulated]] [--to=address]	Send the weekly summary email now, or print it with --dry-run. --to=address sends a test copy to that address only (also while the summary is switched off) and does not count as the weekly send. --dry-run --simulated includes simulator rows in the preview; simulated numbers are never sent.
bin/magento panth:aivisibility:learn [--model=baselines|hidden|readiness|effectiveness|all] [--store=ID] [--dry-run] [--simulated]	Train the learned models now, whatever the weekday. --dry-run prints the result without saving it; --simulated reads simulator rows and needs --dry-run.
bin/magento panth:aivisibility:alerts [--store=ID] [--dry-run] [--simulated] [--at="YYYY-mm-dd HH:00"]	Run the alert detection now, or as of a given UTC hour. --simulated needs --dry-run.
bin/magento panth:aivisibility:auto [--dry-run]	Run the selected auto-actions now (nothing happens while the Auto-Actions kill switch is off).
bin/magento panth:aivisibility:ip-lists [--dry-run] [--show]	Download the published bot IP lists now (only when Bot IP Verification is on). --show prints the stored ranges per bot and never downloads.
bin/magento panth:aivisibility:model [--reset=CODE] [--rollback=CODE] [--store=ID]	List the stored versions of the learned models, reset a model to its built-in defaults, or roll back to its previous version.

Cron jobs (group default)

Job	Schedule	What it does
panth_aiv_rollup	every 30 minutes	Rebuilds the daily summaries of today and yesterday.
panth_aiv_retention	03:10 daily	Deletes raw and daily rows past the retention settings, expired rate-limit rows, and Discovery candidates that are not confirmed and were not seen for 90 days.
panth_aiv_discovery	hourly at :25	Scores AI referrer candidates against live-answer crawler fetches.
panth_aiv_health	hourly at :40	Runs the data-health checks shown on the dashboard.
panth_aiv_import_logs	every 5 minutes	Imports new access log lines (does nothing unless the log import is enabled).
panth_aiv_recommend	04:20 daily	Evaluates the recommendation rules (real data only).
panth_aiv_verify	04:40 daily	Verifies applied fixes whose verification window has ended.
panth_aiv_weekly_email	hourly at :05	Sends the weekly summary email at the configured weekday and hour (UTC), once per ISO week; a run missed at that hour is caught up later in the same week.
panth_aiv_hourly	hourly at :05	Rolls the previous complete hours up into hourly series, then checks them against the learned normal levels (alerts).
panth_aiv_learn	04:50 daily	Learns normal levels daily, the hidden AI traffic estimate and readiness weights weekly (Monday, UTC) or when never trained, and fix effectiveness nightly.
panth_aiv_auto	05:30 daily	Runs the selected auto-actions (does nothing unless the Auto-Actions kill switch is on).
panth_aiv_ip_lists	03:15 daily	Downloads the published bot IP lists (does nothing and makes no request unless Bot IP Verification is on).

How the numbers are kept

• Raw rows (crawler hits, AI visits, landings) are kept for the configured number of days; daily summaries are kept for the configured number of months, so the dashboard keeps its history after raw rows are deleted.
• All days are UTC days and every stored time is UTC, whatever the store or server time zone.
• The daily summaries are rebuilt from the raw rows per store view and per real / simulated data. A day whose raw rows were already removed by retention is never rebuilt, so its summaries are kept as they are. Raising a retention setting does not bring deleted raw rows back.
• Above "Max Detailed Hits per Day" a hit is only counted (per bot, store view and status class), not stored in detail; it still appears in the totals as page type "other". Unknown bots above the cap share one counter. Since 1.2 these capped hits are also counted per UTC hour (panth_aiv_overflow_hourly) and added to the hourly series, so a crawler storm above the cap neither raises a false "Stopped" alert nor understates a spike.
• Top pages keep the 500 most fetched paths per store view, category and day. Beyond that limit a path is still kept when it had at least 3 client or server errors (4xx / 5xx) that day, or at least 3 timed hits that took more than 2 seconds on average; at most 2000 such extra paths are kept per store view and day (most errors first), so error and speed fixes can be verified after the raw rows are deleted while a flood of one-off 404s cannot grow the table without limit.
• Since 1.1 a separate daily table counts AI crawler hits per product and per category without any limit (panth_aiv_entity_daily). The "products AI crawlers never visited" recommendation and the verification of product and category fixes read it, so large catalogues are covered completely.
• Since 1.1 AI visits are also counted per day and landing path without any limit (panth_aiv_visit_path_daily), so visit and order fixes on single pages can be verified after the raw visit rows are deleted.
• Since 1.1 the daily crawler summary also counts the hits with a measured response time and the hits with and without a query string (columns timed_hits, query_hits, canonical_hits of panth_aiv_crawl_daily). On days summarised before 1.1 these columns are empty (NULL); the verification leaves those days out of the average response time and the share of clean URLs instead of counting their hits as untimed or as clean.
• Since 1.2 the retention cron also removes hourly series and the hourly counts of capped hits older than 70 days (panth_aiv_hourly, panth_aiv_overflow_hourly), resolved alerts older than 180 days (panth_aiv_alert), daily hidden traffic estimates older than "Keep Daily Summaries (months)" (panth_aiv_estimate_daily) and model versions beyond the newest 10 per model and store view (panth_aiv_model). Normal levels (panth_aiv_baseline), alert sensitivities (panth_aiv_series_tuning) and product scores (panth_aiv_product_score) are rewritten by their models instead of being pruned; bot IP ranges (panth_aiv_ip_range) are replaced on every successful list download.
• Since 1.3 browser agent (WebMCP) tool calls are counted per UTC day, store view and tool (panth_aiv_agent_daily: calls, failed calls, agent sessions; for add_to_cart the failed calls column holds the adds that did not happen); the retention cron removes rows older than "Keep Daily Summaries (months)". No raw row is stored per call.
• The table size health check uses MySQL table statistics, which the database refreshes on its own; the figure is an estimate.

Recommendations and fix verification

The recommendation rules run every night (cron panth_aiv_recommend) and on Check this store view now on the Recommendations page. A problem is only listed when at least "Minimum Events per Finding" requests, visits or items are behind it, and at most "Max Open Recommendations per Store View" are kept, best first.

Rule	Looks at
robots.txt blocks AI search bots	AI search and live-answer bots that robots.txt blocks (needs the Panth robots.txt module)
Pages answer client errors (4xx) to AI bots	Client errors AI bots received in the last 7 complete days, with redirect suggestions
Server errors or slow pages for AI bots	5xx answers, or pages that took over 2 seconds on average, in the last 7 complete days
Products AI crawlers never visited	Enabled, visible, in-stock products no AI crawler fetched in 90 days (needs 14 days of per-product history)
AI answers send shoppers but no sales	Pages fetched by live-answer bots that sent AI visitors but no orders in 30 days
Thin product content read by AI	Products read by AI bots with a description under 150 words or images without a label
llms.txt is not served	llms.txt switched off, answering with errors, or never fetched while AI bots crawl the store (30 days)
AI crawl wasted on URLs with parameters	More than 30% of AI crawler hits on URLs with query strings in the last 7 complete days
AI shoppers land on out-of-stock products	AI visitors landing on out-of-stock products in 30 days
Unknown AI bots and apps wait for review	Discovery candidates waiting for review for more than 7 days
Spoofed AI bots (1.2)	Bots with more than 20% of their IP-checked hits in the last 7 days coming from addresses outside the bot's published list (only while Bot IP Verification is on and that bot's list is fresh; see Bot IP Verification)

Mark a fix as applied after you made the change. After "Verification Window (days)" the module compares the days before the change with the same number of days after it (the day of the change is left out), using the measure that fits the rule:

• Pages or products you changed are compared with similar ones you did not change (difference in differences with a bootstrap range), so a store-wide trend or a new bot is not mistaken for the effect of the fix. Each changed page is paired only with unchanged pages that had similar numbers (within about 1.65 times) in both the "before" window and the window of the same length before it (the comparison window). The rules pick pages because they were unusually high just before the change (for example the pages with the most 404s in the last 7 days), and such pages fall back towards their usual level afterwards even when nothing changed; partners that were just as high in both windows fall back the same way. Pages without at least 3 such partners, for example pages that only started erroring a few weeks ago while no other page did, get "Not enough data yet" with the reason "no comparable subjects" instead of a guess. A second comparison must agree: the comparison window as the baseline, with partners picked on the "before" window (right when pages were picked for a reason the numbers do not show, such as best sellers). The range shown covers both ranges. When the changed pages had nothing in the comparison window the second comparison cannot be computed, and the first one decides alone; that is only possible with partners that also had (almost) nothing then. Without data for the comparison window (a new store, or right after the upgrade) the result is "Not enough data yet" with the reason "comparison history not available yet"; the module never falls back to a weaker comparison.
• Whole-store counts (for example llms.txt fetches) are compared before and after with a Poisson rate test; the average response time with a t-test across the daily averages.
• Products that were never fetched are compared as shares: the share of fixed products that got crawled after the change against the share of other products, not fetched in the 90 days before, that got their first crawl normally, with the difference in percentage points. A share below the normal one is reported as "no clear effect", never as "worse".

Limitation: the comparison assumes the changed pages would have moved like their unchanged partners. Pages that were already rising or falling on their own before the change (for example a product whose demand was growing) can be misjudged, because that trend looks like the effect of the fix; read a "likely helped" on such pages with care. With fewer than "Minimum Events for a Verdict" events the result is "Not enough data yet". The Recommendations page, the dashboard cards, the weekly email and the cron jobs use real data only; simulated rows only appear in the --simulated command line previews.

Learned models (1.2)

Four models learn from this store's real data (simulated rows are never used): normal levels (baselines, nightly), the hidden AI traffic estimate (hidden, weekly on Monday UTC), readiness weights (readiness, weekly on Monday UTC) and fix effectiveness (effectiveness, nightly). A model that was never trained is trained at the next nightly run; a reset or rolled-back model is trained again 7 days after that action (see below). The Learning card on the dashboard shows each model's state, for example "Learning - needs 9 more days of data", and what it uses until then.

• Reset retires every version of a model; the built-in defaults apply again and the history is kept. It is offered only for a model with a learned (active) version: a model that is still learning already uses the defaults.
• Roll back re-activates the version that was active before the current one (after a Reset: the version that was active most recently).
• Both take effect at once: readiness scores are recalculated with the weights now in use, and the cached probable-AI settings are cleared.
• Both are buttons on the Learning card (ACL Panth_AiVisibility::learning) and options of panth:aivisibility:model. At most 10 versions are kept per model and store view; normal levels are stored per version, so a Roll back of baselines brings back the levels of that version.
• A Reset or Roll back is a merchant decision and is kept for 7 days: during that time the nightly run does not train that model again for that store view (its summary says "Kept as set by the reset or rollback until ..."), and the Learning card shows the date, for example "Rolled back: this version stays in use until ...". After the 7 days the model learns again as usual.

What to expect: models need weeks of data. Normal levels need "Minimum Weeks Before Alerts" (default 3) weeks of hourly history, the hidden estimate needs "Confirmed Visits Needed" (default 30) AI visits that follow a live AI fetch, and readiness weights need "Products Needed to Learn Weights" (default 200) products of which "Products Fetched by AI Needed" (default 30) were fetched by AI search or live-answer bots in 90 days. Every learned number is an estimate from this store's history, not a measurement.

Alerts

Every hour (cron panth_aiv_hourly) the previous complete hours are rolled up into hourly series and compared with the normal level of the same weekday and hour (median of the last "Weeks Used for Normal Levels" weeks, with a robust spread). While normal levels are still learning no alerts fire.

Alert	When
Stopped	A series has no hits for 1 to 3 hours while at least 5 were expected
Spike	Over 3 hours at least twice the expected count and at least 20
More errors	The 4xx or 5xx share of bot hits over 3 hours is at least 10 points above normal, with at least 30 hits
Slower	The average bot response time over 3 hours is more than twice normal and at least 500 ms above it, with at least 30 timed hits
AI visits dropped	AI visits in the last 24 hours are far below normal while at least 10 were expected

• Each check is a statistical test, scaled by the global "Sensitivity" and by your feedback: "Not useful" makes that series and alert type less sensitive, "Useful" more sensitive (0.5 to 2.0).
• Alerts allow for the normal ups and downs of whole days: the nightly learning measures how much 1-, 2-, 3- and 24-hour totals really vary on your store, and alerts fire only beyond that. Steady growth or decline is followed: expected values are scaled by how the last seven days ran against normal (between half and double), so a lasting new level stops alerting after about four days. On a store whose daily AI traffic varies by about 20%, a one-day drop of three quarters is caught reliably (about 12 to 20 hours after it starts) and a drop of about half only in about one of three cases; at 30% daily variation a drop of three quarters is caught only in about two of three cases, 16 to 23 hours after it starts, and a drop of half is mostly within normal variation. A stopped crawler and a sudden spike are caught within a few hours.
• One alert stays open per store view, series and type; repeats update it, and it resolves after 3 normal hours. Acknowledge an alert to show it is being handled.
• "Email New Alerts Immediately" sends new alerts to the weekly summary recipients, at most once per alert every "Hours Between Emails for the Same Alert".
• Limitation: an alert says that a series is unusual for this store, not why. Very quiet series (a few hits a day) cannot raise "Stopped" alerts, because a quiet hour is normal for them.

Hidden AI traffic and probable AI orders

This feature is experimental and switched off by default: turn on "Estimate AI Visits Without a Referrer" under Stores > Configuration > Panth Infotech > AI Visibility > Hidden AI Traffic Estimate. Probable AI order tags need it too. Read the Known limitations below before relying on the numbers.

Some shoppers open a page an AI assistant showed them without any referrer, so they cannot be confirmed as AI visits. The module estimates them from the sampled direct landings ("Direct Landing Sample Rate (%)"): landings on a page shortly after a live-answer bot linked to an AI source fetched that page are compared with that page's usual direct landings at other times of the same day (pooled with its other days when the page has few landings), so a page that is simply busier on the days AI assistants fetch it is not counted as hidden AI traffic. When a store's direct landings bunch in hours (a newsletter or a social post that also makes AI assistants fetch the page), each fetch is compared with the same page's landings in the minutes around it instead (at least 10 minutes on each side, at least twice the time window), so a busy hour is not counted as hidden AI traffic either. The time window comes from confirmed AI visits that followed a live fetch (90th percentile of the delay, 30 seconds to 30 minutes).

• The weekly model (Monday, UTC) covers the last 14 complete days (fewer when raw rows are kept for a shorter time) and stores one estimate per day. It also stores a 95% range for every run of at least 7 consecutive days of that period (the last 7 days, all 14 days, ...) that has at least 10 sampled landings inside fetch windows, each computed for exactly those days: ranges of days cannot be added up. Shorter periods show the estimate with "range not available for periods shorter than 7 days" (in tests, ranges of 1 to 6 days held the true number far less often than 95 times in 100).
• The dashboard card follows the dashboard's date range: confirmed AI visits of that range next to "about N estimated hidden AI visits, likely A to B" for the days the model covered. A range is shown only for at least 7 days that lie inside one weekly estimate of one store view; otherwise (for example the 30- and 90-day presets, which span several weekly estimates, or "All store views" with several estimating store views) the card shows the estimate with "range not available for this period". Per-source estimates have no range. A range the model never covered says "No estimate for this date range". The weekly email shows the same for the email week.
• The estimate is never added to confirmed visits, orders or revenue anywhere in the module.
• Probable AI orders: the collector checks every direct deep landing; when the learned probability for it is at least "Probable AI Order Threshold (%)" (default 80), it sets the signed panth_aiv_p cookie (consent respected), and an order placed within the attribution window without a confirmed AI source gets the channel probable_ai with that probability. The order grid shows it in the "Probable AI (%)" column (filter by a range in percent, for example 80 to 100); the order view shows it as an estimate without a credited source.
• A store's landings are tagged only when the model is sure enough: the lower end of the 95% range of the learned probability must reach the threshold, and the model must have seen at least 30 sampled landings inside fetch windows. With fewer, a single busy day could push the probability over 80% on a small store without any hidden AI traffic. On small stores (a few hundred direct landings a day) probable tagging therefore usually stays off. A model trained before 1.2.0 tags nothing until its next weekly run.
• Reliability check: when direct landings arrive in bursts together with the AI fetches (for example a newsletter that also makes AI assistants fetch the page), the background cannot be measured reliably. The model checks two signs of this (in-window landings that scatter far more than counting noise allows, and excess that grows with a page's direct traffic); when either is clear, the card and the weekly email show "Estimate not reliable for this period: direct traffic arrives in bursts that coincide with AI fetches" with no number and no range, and no order is tagged as probable AI. The weekly email also says when its 7 days are only partly covered by the weekly model.
• Limitations: the estimate divides by the current sample rate, so changing the rate skews the estimate until a full period has passed at the new rate. A probability is an estimate for the visit, not proof; individual probable orders can be wrong.

AI readiness

Each week the readiness model scores every enabled, visible product of a store view from 0 to 100. Features: description length, complete structured data (price, availability, brand, GTIN), listed in llms.txt, image labels, reviews, stock, bot response time, URL depth, noindex and days since the last update. Features whose source module is not installed are left out, not counted as zero.

• Until enough products exist the built-in weights apply. Learned weights replace them only for features that make a clear difference on this store (ridge regression; the range must exclude zero even after allowing for testing about ten features at once, so a store without any real effect shows a "what matters" claim in at most about 1 run in 20 when products are independent; see Known limitations for categories), and each weight moves at most "Max Weight Change per Week" per run.
• A feature is judged only when at least 20 products, and at least 10% of the products, differ from the rest on it. A yes/no feature that only a few products have (for example 4 noindex pages or 7 out-of-stock products) is listed as "Not enough variety to judge" and never changes the weights.
• While the model is learning, the Learning card says what is missing, for example "Learning - needs 3 more enabled, visible products and 30 more products fetched by AI search or live bots".
• Panth Infotech > AI Visibility > AI Readiness lists the lowest-scoring products with their missing features, edit links and a CSV download (ACL Panth_AiVisibility::readiness). The dashboard card "What matters on your store" names the strong features in plain words.
• Limitation: the learned weights describe which products AI bots fetch more on this store. They show an association, not proof that changing a feature will bring more AI fetches; use Fix verification to check a change.

Ranking and auto-actions

With "Rank by What Worked on This Store" on, each rule's verified fixes adjust its ranking: the share of fixes that "likely helped" (with a small prior, so one verdict cannot dominate) gives a factor between 0.5 and 1.5. Rules without verdicts keep factor 1. The Recommendations page, the dashboard card and the weekly email use the same ranking.

Auto-actions are off by default. They run only when "Allow Auto-Actions (Global Kill Switch)" is on, the rule is selected in "Fixes That May Run Automatically" and the action is available; the kill switch is checked again before every action, and "Max Items per Day" caps the items per day.

• Available today: "Products AI crawlers never visited" submits the product URLs through the Panth IndexNow module's own queue (only when that module is installed, enabled and configured for the store view). This module never sends the request itself.
• An auto-action is recorded like a manual fix (applied by "auto") and verified the same way. Undo removes the URLs that are still queued; URLs IndexNow already submitted cannot be recalled, and the page says so. An undone action is not verified.
• When nothing runs, the run says why: the kill switch is off, no fix is selected, the daily limit is used up, or per store view that AI Visibility is disabled there or that the action is not available there (the module it needs is missing, switched off or not configured, for example the IndexNow module is switched off).

Bot IP Verification

Off by default. When "Verify Bot IP Addresses (Outbound Request)" is on, the cron panth_aiv_ip_lists (03:15 daily) or panth:aivisibility:ip-lists downloads the IP lists listed in "Published IP Lists". This is the only outbound request of the module; nothing is downloaded while the feature is off.

• Defaults: the official lists of OpenAI (GPTBot, OAI-SearchBot, ChatGPT-User), Perplexity (PerplexityBot, Perplexity-User), Apple (Applebot) and Common Crawl (CCBot). Lists are JSON in the common prefixes format or plain text with one IPv4 / IPv6 range per line.
• HTTPS only, 10 seconds timeout, at most 2 MB per list and 20 lists. A list replaces the stored ranges of its bot only when the download and parsing succeed; on failure the old ranges are kept.
• Each AI bot hit handled by Magento is checked in memory against its bot's list: verified = 1 (in the list), 0 (not in the list) or NULL (not checked: the feature is off, the bot has no list, the list is older than "Warn When Lists Are Older Than (days)", or the address is private or internal). The IP address is never stored or logged. Hits from the access log import and the simulator stay unchecked.
• The "Bot IP lists" health check warns about stale or failed lists. panth:aivisibility:ip-lists --show prints the stored ranges per bot without downloading.
• The "Spoofed AI bots" rule lists bots with more than 20% unverified hits among their checked hits in the last 7 days.
• Behind a reverse proxy, load balancer or CDN, Magento must be configured to read the visitor address from the forwarding header; otherwise every hit carries the proxy's address and is left unchecked or reported as unverified.

Browser agents (WebMCP, experimental)

WebMCP is a new browser API with which a web page offers tools to the AI assistant built into the browser. When an agent such as Gemini in Chrome helps a shopper on your store, it can call these tools and get exact answers instead of reading and clicking through pages. The feature is experimental and switched off by default; with it off, or in a browser without WebMCP, nothing changes for shoppers.

Tools

Tool	Input	Returns
search_products	a search text (1 to 100 characters), optional number of results (up to "Max Search Results per Call")	Matching products: name, SKU, product URL, price, currency, in stock yes / no, image URL
get_product	a SKU or a product URL of this store	Name, SKU, URL, product type (simple, virtual, configurable, bundle, grouped, ...), whether add_to_cart supports it, price, currency, in stock, short description as plain text (up to 600 characters) and, for configurable products, the options with their values
get_cart	nothing	The product lines Magento's cart section returns for the shopper's own cart (by default the 10 most recent items; name, SKU, product URL, quantity, price), plus the subtotal and cart count of the whole cart (number of items or total quantity, as the store's cart link counts it), cart and checkout URLs
add_to_cart	a SKU, optional quantity (1 to 100) and, for configurable products, the option values	Whether it worked, a short message and the new cart count; when the product is not added, a message, the product URL where there is one and, when the store was asked, the cart count (see below)

• No tool returns personal data: no names, email or postal addresses, customer account data, order history, cart ID or payment data. get_cart returns product lines only.
• The three read tools are selected by default. add_to_cart is not selected by default; when you select it under "Tools Offered to Agents", an agent may put products into the shopper's own cart the same way the Add to Cart button does. No tool ever goes to checkout, pays or performs account actions.
• add_to_cart handles simple, virtual and configurable products that are in stock and answers "Added to the cart" when the cart count, the subtotal or the quantity of that product's lines went up. For bundle, grouped, downloadable and other products that need choices, and for a configurable product without a valid value for every option, it answers "Open the product page to choose options" with the product URL. When the store refuses the product (for example more than the quantity in stock, or required custom options), it answers "The store did not add the product. See the product page" for a simple or virtual product and "The store did not add the product. Open the product page to choose options" for a configurable one, with the product URL and the cart count. Concurrent add_to_cart calls run one after the other.
• add_to_cart timing: each add has 8 seconds once it starts. A call that is still waiting in the queue after 8 seconds answers "The store took too long to answer" and is never sent to the store. When the add was already sent and the time runs out (or the request fails), the cart is read once more and the answer is "Added to the cart" or "The store did not add the product. ..." as above, or "The product may have been added - check get_cart" when the store cannot be read.
• get_cart lines show the SKU of the item in the cart; for a configurable product that is the SKU of the chosen variant, which get_product may not find on its own, so use the product URL of the line instead.
• Out-of-stock products: with "Display Out of Stock Products" set to No (Magento's default), the store's GraphQL hides them, so agents usually do not see them at all; get_product and add_to_cart then answer "Product not found or not available" (the same answer as for an unknown SKU).
• Every tool checks its input before any request, stops after 8 seconds (for add_to_cart see the timing above) and answers errors as a short JSON message ({"ok":false,"error":...}, for example "Invalid input: ...", "The store took too long to answer", "The store could not be reached" or "The store could not run this query") instead of failing the agent.
• search_products, get_product and add_to_cart read the catalogue through the store's own GraphQL endpoint (/graphql, module Magento_CatalogGraphQl); without that module only get_cart is offered.

Switching it on

1. Make sure "Enable AI Visibility" and "Track Visits from AI Assistants" are Yes: the tools are loaded by the same small collector script.
2. Under Stores > Configuration > Panth Infotech > AI Visibility > Browser AI Agents (WebMCP, Experimental) set "Register Shop Tools for Browser AI Agents (Experimental)" to Yes, choose the tools and save. From the command line: bin/magento config:set panth_aivisibility/webmcp/enabled 1 (other paths: panth_aivisibility/webmcp/tools, max_results, origin_trial_token, track_calls).
3. Changes reach cached pages automatically: when a browser agent setting (or "Enable AI Visibility", "Track Visits from AI Assistants" or "Direct Landing Sample Rate (%)") changes, saving it in the admin or with bin/magento config:set cleans the full page cache. Only a change written directly into the database (core_config_data) needs bin/magento cache:clean config full_page afterwards.

Browser support

• Chrome offers WebMCP (Chrome 149 or later at the time of writing) when the user switches on the developer flag chrome://flags/#enable-webmcp-testing, or on sites that have an origin trial token. To take part in the trial, register your store address for the WebMCP origin trial with Chrome and paste the token into "Chrome Origin Trial Token (Optional)"; it is printed as <meta http-equiv="origin-trial"> in the page head. The token is public, not a secret, and each store address needs its own (the setting has website and store view scope).
• Only browsers that support WebMCP download the tool script; all other browsers download nothing extra.
• WebMCP is still being designed and the API may change; a later browser version may need a module update.

What is counted

With "Count Tool Calls and Agent Orders" on (default Yes):

• Tool calls per tool and day, failed calls and agent sessions (the first tool call in a browser tab session). For the read tools (search_products, get_product, get_cart) only real failures count as failed calls (the store could not be reached, timeout, store or GraphQL error, invalid input); "Product not found or not available" is a successful call. The error share is read-tool errors divided by read-tool calls.
• add_to_cart calls are counted as "added" (the store added the product) or "not added" (every other answer: options needed, not found or not available, refused by the store, or a failure), never as errors, and they are left out of the error share. In the agent_daily CSV the "errors" column of an add_to_cart row holds the number not added.
• Each call sends one small report to the collector with only the tool name, whether it worked and whether it started a session; never the search text, the SKU or anything personal.
• Orders: after the first tool call the signed panth_aiv_a cookie is set; while the agent keeps calling tools it is refreshed at most once an hour, so it stays valid for 30 days from the last call (to within an hour). It is deleted when the customer logs out. An order placed while it is valid gets the channel webmcp, shown as "Browser agent (WebMCP)" in the order grid's AI Source column (with its own filter value) and on the order view. A confirmed AI referral (the shopper came from an AI assistant's link) always wins; probable AI applies only when neither is present.
• Browser agent orders are kept apart from confirmed and probable AI orders: they are never added to the confirmed AI orders, revenue by source or orders by day, and never to probable AI.
• The dashboard card "Browser agents (WebMCP)" shows the status (off / on and the tools offered), calls per tool (with errors, or not added for add_to_cart), the error share of the read tools, agent sessions, products added to the cart (and how many were not added) and the orders and revenue of the channel for the dashboard's date range and store view. It says when WebMCP is switched on but no tools load because the module or "Track Visits from AI Assistants" is off. The CSV export agent_daily lists day, store view, tool, calls, errors (not added for add_to_cart) and sessions. The weekly email adds one block when there was any browser agent activity that week, with the same read-tool error share and add-to-carts added and not added.
• Simulated agent rows (panth:aivisibility:simulate --webmcp-sessions=N) are hidden like other simulated data.

Privacy and CSP

• The tools call only this store (same origin); the module makes no outbound request for this feature. What the agent does with a tool's answer is up to the browser and its AI provider, so the answers contain only data that is already public on the storefront, plus the shopper's own cart lines.
• Only counts are stored (panth_aiv_agent_daily), no raw row per call and no IP address. The panth_aiv_a cookie is signed, HttpOnly and SameSite=Lax, holds only the times of the first and the last tool call (the last call time is updated at most once an hour), is set only when cookie consent allows it and is removed at customer logout.
• CSP: the tool script is a static file of the module loaded from the store's own static URL with a script tag, without inline code or eval, and it fetches only same-origin URLs, so the default Magento CSP (script-src and connect-src include 'self') allows it.

Known limitations

• The WebMCP API is experimental and may change; only some agents use it today (Gemini in Chrome with the flag or an origin trial token), so most stores will see few calls at first.
• Tool results are untrusted content for the agent: names and descriptions are catalogue text that the merchant (or, through reviews and imports, others) wrote. The tools mark them as such, but how an agent treats them is up to the agent.
• add_to_cart uses the store's normal cart form (/checkout/cart/add) and needs a form key; it uses the form_key cookie or creates one the way Magento's own storefront does. Magento shows its usual "You added ... to your shopping cart" message, and themes or extensions that change the cart form can make the call fail.
• Prices follow the shopper's session, like the storefront: a logged-in shopper gets the prices of their customer group (for example catalog price rules for that group). Only when GraphQL sessions are switched off (graphql/session/disable = 1) are guest prices shown to everyone.
• Shared browsers: the panth_aiv_a cookie belongs to the browser, not to a person. If someone else orders in the same browser within 30 days of the last tool call, without a customer logout in between, that order is also tagged webmcp.
• Agents running in a headless browser are treated as bots by the collector and are not counted. The collector's rate limit ("Max Reports per IP per Minute") can drop calls of a very busy agent, so counts can be low.
• An agent session is counted per browser tab session; the same agent in a new tab counts as a new session.

Upgrading from 1.2

1. Run composer update mage2kishan/module-ai-visibility, then bin/magento setup:upgrade (plus setup:di:compile and setup:static-content:deploy in production mode; the release adds the static file js/webmcp.js) and bin/magento cache:flush.
2. setup:upgrade adds one table, panth_aiv_agent_daily (29 tables in total). Existing tables keep their structure and data; panth_aiv_order.channel gets the new value webmcp.
3. No new ACL resource and no new cron job: the dashboard card uses Panth_AiVisibility::dashboard, and the retention cron also prunes panth_aiv_agent_daily.
4. Browser agents (WebMCP) stay off until you switch them on; nothing changes for shoppers before that. If your own reports read panth_aiv_order, keep the webmcp channel apart from referral and probable_ai like the module does.

Upgrading from 1.1

1. Run composer update mage2kishan/module-ai-visibility, then bin/magento setup:upgrade (plus setup:di:compile and setup:static-content:deploy in production mode) and bin/magento cache:flush.
2. setup:upgrade adds nine tables (panth_aiv_hourly, panth_aiv_overflow_hourly, panth_aiv_model, panth_aiv_baseline, panth_aiv_series_tuning, panth_aiv_alert, panth_aiv_estimate_daily, panth_aiv_product_score, panth_aiv_ip_range), indexes on is_simulated and created_at of panth_aiv_hit and panth_aiv_visit, the columns origin and auto_payload of panth_aiv_action, checked_hits and unverified_hits of panth_aiv_crawl_daily and activated_at of panth_aiv_model. The column verified of panth_aiv_hit becomes nullable (NULL = not checked); a data patch sets the old placeholder value 0 to NULL, because no hit was checked before 1.2. Existing data is kept.
3. Give the new ACL resources to the admin roles that need them: Panth_AiVisibility::alerts (Alerts page), Panth_AiVisibility::readiness (AI Readiness page and CSV) and Panth_AiVisibility::learning (Reset and Roll back of learned models).
4. Four new cron jobs start working after the upgrade: panth_aiv_hourly, panth_aiv_learn, panth_aiv_auto and panth_aiv_ip_lists. The first hourly run backfills the hourly series from the raw rows still kept; auto-actions and Bot IP Verification do nothing until you switch them on.
5. What to expect: alerts start after "Minimum Weeks Before Alerts" (default 3) weeks of hourly history; readiness weights and the hidden traffic estimate are trained on the next Monday (UTC) or at the next nightly run when never trained, and show "Learning - needs N more ..." until enough data exists. Raw crawler hits are kept for 14 days by default, so the hourly history before the upgrade is short.

Upgrading from 1.0

1. Run composer update mage2kishan/module-ai-visibility, then bin/magento setup:upgrade (plus setup:di:compile and setup:static-content:deploy in production mode) and bin/magento cache:flush.
2. setup:upgrade adds the three 1.1 tables (panth_aiv_recommendation, panth_aiv_action, panth_aiv_impact), the per-product table panth_aiv_entity_daily, the per-landing-path visit table panth_aiv_visit_path_daily and new columns in the daily summaries (19 tables in total), plus an index on status and time in panth_aiv_hit for the crawler error rules (on a table with millions of crawler hits this adds some time to the upgrade). Existing data is kept; the new crawler summary columns stay empty (NULL) on days summarised before 1.1.
3. During setup:upgrade a one-time data patch rebuilds the daily summaries of every day still inside the raw retention, that is the larger of "Keep Detailed Crawler Hits (days)" (default 14) and "Keep Detailed AI Visits (days)" (default 30), at most 60 days, oldest day first. Those days get per-product counts, per-path visit counts and error / speed details at once. A day that cannot be rebuilt is skipped and logged as a warning in var/log/system.log; the upgrade itself never stops. To rebuild later, run bin/magento panth:aivisibility:rollup --days=30 (use your retention setting).
4. Days older than the raw retention keep their 1.0 summaries: dashboard totals, charts and top pages stay as they were, but those days have no per-product counts and no per-page error details.
5. What to expect: the first recommendations appear after the next nightly run (or click Check all store views now). "Products AI crawlers never visited" waits until 14 days of per-product history exist. The verification of a fix on pages or products needs two full windows of per-day history before the change (the comparison window and the "before" window, 2 x "Verification Window (days)", 28 days by default); until then it reports "Not enough data yet" with the reason "comparison history not available yet". The upgrade rebuilds per-product and per-page crawler counts only for the days whose detailed crawler hits are still kept ("Keep Detailed Crawler Hits (days)", default 14), so with the defaults crawler fixes applied in the first 14 days after the upgrade get that answer (28 - 14 days; none with a retention of 28 days or more).
6. Give the new ACL resource Panth_AiVisibility::recommendations to the admin roles that should see the Recommendations page; roles with only the Dashboard resource no longer see the recommendations cards or download the recommendations and verdicts exports.
7. The weekly summary email stays off until you switch it on and enter recipients.

Access log import (Varnish / CDN)

Behind Varnish or a page-caching CDN most bot requests never reach PHP. Enable Access Log Import, then list one file per line as /absolute/path/access.log | store_code. The combined / varnishncsa default format is read.

• Only new, complete lines are read; the position is saved per file. Rotation (new inode), truncation (> file) and a file that was truncated and written again past the saved position are detected and read from the start.
• Configure the current log file only. Compressed rotated files (.gz) are not supported and are reported as an error. A symlink and its target are imported once.
• Web API requests (/rest, /soap, /graphql), static files and media (except sitemaps) are skipped, like for requests handled by PHP.
• Days that receive hits are summarised at the end of each run, also days older than yesterday. Lines of days whose raw rows were already removed by retention are only summarised when that day has no summary yet.
• A line whose write fails stops the run at that line; after three failed runs on the same line it is skipped, so the import never stalls. The last error is shown by the "Log import" health check and by the command output.
• When a store view is mapped to a log file, PHP tracking skips crawler hits for that store view so nothing is counted twice.

Data and privacy

• The collector (POST /panth_aiv/collect) never starts a PHP session, never sets a session cookie and does not renew Magento's private_content_version cookie. It may set two first-party cookies, both signed, HttpOnly and SameSite=Lax, for the attribution window and only when cookie consent allows it: panth_aiv (the first and latest confirmed AI source) and, since 1.2, panth_aiv_p (only a probability, a time and the landing path of a probable AI visit). Since 1.3, with browser agent tools on, a third one: panth_aiv_a (only the times of the first and the last tool call, 30 days from the last call, refreshed at most once an hour and removed at customer logout).
• The collector sends only the referrer host name, the utm_source value and the landing path. No full referrer URLs, query strings, IP addresses or customer data are stored.
• Rate limiting stores only a salted hash of the IP address in short-lived counters. Requests are counted per client IP: at most "Max Reports per IP per Minute" beacons per client and 50 times that in total per minute.
• Crawler hit rows hold the bot, path, status, response time and, with Bot IP Verification on, whether the address was in the bot's published list (never the address itself); visit rows hold the source, referrer host and landing path. Order attribution rows hold the order ID, the first and last AI source with their times, the landing path and, for probable AI orders, the probability.
• Browser agent (WebMCP) tool results contain catalogue data and the shopper's own cart lines only; the module stores only daily counts per tool (calls, failed calls, sessions), never the search text, SKUs or anything personal.
• Recommendations and applied fixes store the admin user name that applied a fix and the optional note.
• The weekly summary email contains only aggregated numbers, page paths and titles; it is sent through the Magento mail transport to the configured recipients.
• All data stays in the Magento database. The only outbound request is the optional download of published bot IP lists (Bot IP Verification, off by default); bot IP addresses are compared in memory and never stored.

Known limitations

• Google AI Overviews / AI Mode and Microsoft Copilot answers are fetched by Googlebot and Bingbot, so their share cannot be separated from ordinary search crawling.
• Errors that end a request before Magento sends its response (uncaught exceptions with a 500 page, the 503 maintenance page) are not recorded, so the 5xx share of crawler hits can be lower than in the web server log. Use the access log import for exact error rates.
• AI referrer visits are only attributed on the storefront domain that sets the cookie. Headless storefronts on another domain and cross-domain checkouts are not attributed.
• A visitor whose browser sends no referrer and no utm_source cannot be recognised as coming from an AI assistant; sampled direct landings show which deep pages are opened this way.
• Ordinary browsers that open /llms.txt are treated as people and never become Discovery candidates. AI agents that browse with an unmodified browser User-Agent cannot be told apart from shoppers.
• When a log file is rotated by renaming, lines written to the old file after the last import run (up to 5 minutes) can be missed.
• Discovery lists the 200 most active candidates per status.
• The "AI Source" column of the order grid sorts by source code, not by the displayed name.
• Learned numbers (normal levels, hidden traffic, probable AI, readiness weights, effectiveness) are estimates from this store's history. They need weeks of data and can be wrong for unusual periods such as sales or a site migration; reset a model when its history no longer represents the store.
• A crawler that sends only about 5 requests an hour on a store whose traffic is very irregular may be reported as stopped only after 3 hours.
• Hidden AI traffic: a page's day-to-day background rate is pooled with its other days when it has few direct landings. On quiet pages whose direct popularity and AI fetches rise and fall together, part of that day-to-day movement can still be read as hidden AI traffic; this raises the estimate slightly and makes the probable-AI probability somewhat too high for such pages.
• Hidden AI traffic and busy hours: bursts that raise a page's direct landings and its AI fetches in the same hour are compared with the landings in the gaps between and around the fetches, which removes most of their effect, and bursts of strongly varying size are caught by the reliability check (tests without any hidden traffic, 20 runs each: up to 10 evenly sized bursts a day leave an upward bias of about 1 to 5 points of the AI visit share, with the range including 0 in 17 to 20 runs; bursts of varying size were marked not reliable in 8 to 20 of 20 runs, the rest covered). Not caught: when most direct landings arrive in such bursts (60 bursts a day of 15 landings and 6 AI fetches each, about 60% of all direct landings) the estimate is still far too high (about 1 to 2.7 times the confirmed AI visits instead of 0) and is marked not reliable in only about 1 to 5 of 20 runs; with long delays between fetch and visit (median 5 minutes) bursts add about 30 points and only 1 to 2 of 20 runs are marked. In all of these the learned probability stays far below 80%, so no order is tagged as probable AI.
• Hidden AI traffic ranges: the range of a run of days covers the counting noise of those days. Ranges of 7 and 14 days held the true number in about 94 to 99 of 100 tests across store sizes, sample rates of 10% and 25%, hidden shares of 0% and 30% and day-to-day swings. A run of days with fewer than 10 sampled landings inside fetch windows gets no range of its own (the card shows "range not available"), which is common on small stores and at low sample rates. It does not fully cover errors of the delay model or stores where a few pages are fetched almost all the time (tested with 40 pages: 15 to 18 of 20 weeks held the true number). On very small stores a range of 8 to 13 days is rare, but when one appears it is usually driven by a single busy day and can sit above the true number (about 1 run in 100 in tests).
• Hidden AI traffic weekly fit: each store view's fit stops after 4 minutes; the previous model then stays in use and the run is logged as skipped.
• AI readiness on small or zero-heavy catalogues: a real effect is often missed. In tests a feature that doubles AI fetches was ranked first in only about 1 of 10 runs with 200 products and about 8 to 9 of 10 runs with 1,000 products, and never (0 of 30) when about 60% of products were never fetched by AI bots. "Nothing stands out" does not mean that no feature matters.
• AI readiness and categories: the "about 1 run in 20" false-claim rate assumes that products are independent. When AI demand differs by category and features cluster by category (for example long descriptions in one category, short ones in another), a feature that only stands in for its category can be reported as strong: in tests without any real effect this happened in about 66% of runs with 200 products and 78% with 1,000 products. Check a "what matters" claim within one category before acting on it, and use Fix verification.
• Browser agents (WebMCP) are experimental: see the Known limitations under Browser agents (WebMCP, experimental).
• After a Discovery rule is deleted, its raw rows go back to the candidate; summaries of days whose raw rows were already removed keep the rule code and are shown as "Deleted rule (code)".

Disabling and uninstalling

To stop collecting data, set Enable AI Visibility to "No" (store scope) or turn off crawler / visit tracking. This keeps all data.

Warning: bin/magento module:disable Panth_AiVisibility followed by bin/magento setup:upgrade drops all 29 panth_aiv_* tables (declarative schema), including the order attribution history. Back up the tables first (for example mysqldump <database> $(mysql -N -e "SHOW TABLES LIKE 'panth_aiv_%'" <database>)), or run bin/magento setup:upgrade --safe-mode=1, which keeps a backup of the dropped data in var/declarative_dumps_csv/ that setup:upgrade --data-restore=1 can restore.

To remove the module after taking a backup:

bin/magento module:disable Panth_AiVisibility
composer remove mage2kishan/module-ai-visibility
bin/magento setup:upgrade
bin/magento cache:flush

The configuration rows under panth_aivisibility/ in core_config_data are left in place.

Support

• Website: kishansavaliya.com
• Contact form: kishansavaliya.com/contact
• Email: [e-mail]

License

Free and open source under the MIT License. See LICENSE.txt.

Changelog

See CHANGELOG.md.