=== EdgeShaping Lite – AI Bot Visibility vs Human Traffic ===
Contributors: mareinterno
Tags: ai crawler, ai bot, bot log, analytics, llm
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2026.10.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

See which pages AI bots like GPTBot, ClaudeBot and PerplexityBot are reading, and compare them with your human traffic. Nothing is blocked.

== Screenshots ==

1. Dashboard showing AI bot visit frequency ranking
2. Access log with date filter and CSV export
3. AHQG Matrix — AI bot visits vs. human search clicks
4. Settings screen — Google Search Console connection


== Description ==

**EdgeShaping Lite** is a WordPress implementation of the EdgeShaping AI bot observation framework developed by [mare interno](https://mareinterno.com). Product details: [edgeshap.ing](https://edgeshap.ing)

This plugin answers one question:

> **Which AI bots are reading which pages of your site, and when?**

= What it does =

* Detects AI bot visits using a dictionary of known AI crawlers
* Records bot name, visited URL, and timestamp
* Dashboard with bot visit frequency ranking and most AI-visited pages
* Full access log with date filter and CSV export
* AHQG Matrix — visualizes AI bot visits vs. human search clicks (requires Google Search Console integration)
* AHTG Matrix — visualizes AI bot visits vs. human page views (WordPress's own pageview tracking). Unlike AHQG, no Google Search Console connection required.

= What it does NOT do =

* It does not block AI bots
* It does not modify your content
* It does not send data externally — all data stays in your WordPress database

= Note on CDN environments =

This plugin observes AI bot traffic at the PHP layer. In environments with a CDN (e.g. Cloudflare, CloudFront), cached requests may not reach PHP and will not be recorded. For full CDN-layer observation, see [EdgeShaping](https://edgeshap.ing).

= EdgeShaping Framework =

EdgeShaping is a framework for observing AI bot behavior to understand how AI systems read and interpret your content. For more information, visit [edgeshap.ing](https://edgeshap.ing).

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/edgeshaping-lite/` or install via the WordPress plugin screen
2. Activate the plugin through the Plugins menu in WordPress
3. Navigate to **EdgeShaping Lite** in the admin menu to view your dashboard

Data collection begins immediately after activation.

== Frequently Asked Questions ==

= Does this plugin slow down my site? =

The plugin adds a lightweight database write on each request matched to an AI bot. Non-bot traffic is not logged and has zero performance impact.

= How often is the bot dictionary updated? =

The dictionary is updated via plugin updates.

= Can I export the data? =

Yes. CSV export is available from the access log screen with date filter applied.

= What about GDPR? =

The plugin logs only requests whose User-Agent matches the bot dictionary: time, URL, User-Agent and IP address. The IP address is used to verify that a request really comes from the bot it claims to be. The plugin sets no cookies, does not track human visitors, and sends nothing externally. If you prefer not to store IP addresses, turn off "IP address recording" in Settings: stored IP addresses are deleted and none are stored from then on (bot verification is turned off as well).

= What is the AHQG Matrix? =

AHQG Matrix is a framework that classifies pages into four quadrants based on AI bot visits and human search clicks. Requires Google Search Console integration.

= What is the AHTG Matrix? =

AHTG Matrix uses the same four-quadrant model as AHQG, but the human axis is WordPress's own page views instead of Google Search Console clicks — no external connection required, and it reflects all traffic sources, not just search.

== External Services ==

This plugin connects to the following external services:

= Google Search Console API =

This plugin optionally connects to the Google Search Console API to retrieve human search click data for use in the AHQG Matrix feature.

* What it is used for: Retrieving search analytics data (clicks per page) to compare with AI bot traffic.
* What data is sent: The plugin sends OAuth 2.0 authentication requests and search analytics queries to Google's API. No personal user data from your site visitors is transmitted.
* When it is used: Once the administrator connects their Google Search Console account, the plugin fetches click data from the API once per day in the background (via WordPress cron, or on an admin page load if cron is unavailable) and stores it in your WordPress database, so that historical data remains available after Search Console's own 16-month retention window. No requests are sent before the account is connected, and disconnecting stops them.
* Service provider: Google LLC
* Terms of Service: https://developers.google.com/terms
* Privacy Policy: https://policies.google.com/privacy

== Changelog ==

= 2026.10.0 =
* Changed: the bot dictionary now lists only crawlers that their operators officially document. Bots without an official statement are no longer recorded. Existing log entries are kept.
* Changed: the bots used for the AI axis of the AHQG/AHTG matrices follow the updated dictionary, so matrix results for past periods may differ from what you saw before.
* Added: on sites running the MCP Adapter plugin (WordPress 6.9+), a read-only ability `edgeshaping/get-daily` lets an MCP client signed in as a user with the Contributor role or higher read the daily summary. The plugin itself still sends nothing externally.
* Added: a setting to turn off IP address recording. Turning it off deletes all stored IP addresses; bot verification stops, and the dashboard and matrices then count every dictionary-matched visit.
* Fixed: uninstalling the plugin now removes all of its tables (they are kept while the other edition is installed).
* Fixed: unnecessary database work on every page load.
* Removed: the CDN period note on the dashboard and matrix screens.

= 2026.9.1 =
* Added: IP verification support for CDN environments.
* Fixed: the dashboard summary tables now read from verified data.
* Fixed: Access Log and CSV export now output all rows, unfiltered.
* Changed: log cleanup is now unified with the daily aggregation batch.

= 2026.9.0 =
* Changed: version numbering moved to CalVer (`YYYY.M.PATCH`), since releases are driven by the monthly bot dictionary update.
* Added: IP verification. Bot IP ranges published by each vendor are bundled with the plugin and matched against the recorded IP in the nightly batch. The dashboard and matrices now count only verified visits, so a request merely claiming to be a known crawler no longer inflates your numbers. The access log is unfiltered as before.
* Added: the client IP is now recorded for bot requests and shown in the access log and CSV export. Only bots matched by the dictionary are logged, so no visitor data is stored.
* Changed: the dashboard and matrices now end at yesterday, matching the nightly batch. The access log still shows today.
* Fixed: the dashboard scorecards included noise paths (robots.txt, sitemaps, archives) and did not match the tables below them.
* Changed: bot dictionary updated.

= 1.6.2 =
* Fixed: in the AHQG and AHTG matrices, the same page could appear as two separate rows (with and without a trailing slash), splitting its counts. Both axes are now normalized consistently.
* Fixed: category, author, and pagination archive URLs (e.g. /category/, /author/, /page/2/) are no longer mixed into the matrices.
* Changed: the top page is now excluded from both the AHQG and AHTG matrices (it always lands in the same quadrant and only skews the thresholds).
* Changed: the AHQG date range now ends a few days before today, because Search Console data for the most recent days is not yet final. This keeps the human axis from being understated.
* Added: Search Console click data is now imported once per day and stored in your WordPress database, so the human axis remains available even beyond Search Console's own retention window.
* Changed: expanded the spam/scan path filtering used by Inferred Path (dot-files, config files, API and GraphQL probes, etc.).

= 1.6.1 =
* Changed: bot dictionary reviewed and corrected; a few entries added and a few unverifiable ones removed.
* Fixed: the upsell notices shown for paid-edition-only screens (REST API, Category Analysis, Access Log detail) referenced an outdated API structure and pricing. Simplified to a generic notice pointing to the purchase page.
* Changed: internal bot-signature data file renamed (no functional change).

= 1.6.0 =
* Changed: increased the rolling row limit from 20,000 to 100,000.
* Changed: statistics are now pre-aggregated in a daily batch instead of being computed on every page view, improving admin screen performance.

= 1.5.0 =
* Added AHTG Matrix — visualizes AI bot visits vs. human page views. Unlike AHQG, no Google Search Console connection required.
* Added general-purpose bot exclusion list (SEO tools, uptime monitors, scrapers) to keep human traffic counts clean.
* Changed: increased the rolling row limit from 10,000 to 20,000.

= 1.4.1 =
* Fixed: full-page cache compatibility (WP Rocket, W3 Total Cache, WP Super Cache, LiteSpeed) — AI-crawler hits are now recorded reliably.
* Changed: previously-excluded noise paths (robots.txt, sitemap, etc.) are now kept in the access log instead of being discarded.

= 1.3.5 =
* Fixed: uninstalling this plugin while the paid edition is active no longer deletes shared observation data

= 1.3.4 =
* Bug fixes (i18n: missing translators comments, escaping, placeholder ordering)

= 1.3.3 =
* Bug fixes (internationalization: hardcoded strings wrapped in translation functions)

= 1.3.2 =
* Bug fixes (upsell links for paid edition, plugin URL correction)

= 1.3.1 =
* Bug fixes (plugin installation path correction, broken documentation link fix)

= 1.3.0 =
* Added Inferred Path detection (AI-visited URLs not in sitemap)
* Added Dark Pages detection (sitemap URLs with no AI or human traffic)
* Added sitemap fetching via robots.txt directive
* Added /category/, /tag/, /author/ to default exclude paths

= 1.2.0 =
* Added AHQG Matrix with Google Search Console integration
* Added date filter (7 days, 30 days, this month, last month, custom)
* Added CSV export
* Added settings screen for GSC OAuth connection
* Added automatic data cleanup (retention period and row limit)
* Updated bot dictionary to 2026.05 version
* Added path exclusion filter (robots.txt, sitemap, wp-, feed)

= 1.1.0 =
* Added data retention settings (120 days default)
* Added rolling row limit (10,000 rows default)
* Added date filter to dashboard and log

= 1.0.0 =
* Initial release

== Upgrade Notice ==

= 2026.10.0 =
Bot dictionary now lists only officially documented crawlers; undocumented bots are no longer recorded and past matrix results may change. Adds a read-only MCP ability and a setting to turn off IP address recording. Existing data carries over.

= 2026.9.1 =
Adds CDN IP verification. Fixes dashboard summaries to use verified data only. Access Log and CSV export now output all rows unfiltered. Existing data carries over automatically. Display name is now "EdgeShaping Lite – AI Bot Visibility vs Human Traffic" (slug unchanged).

= 2026.9.0 =
Adds IP verification: the dashboard and matrices now count only bot visits that match a vendor-published IP range. Scorecards now use the daily summary, and those screens end at yesterday. Version numbering moves to CalVer.

= 1.6.2 =
Fixes duplicate rows and stray archive URLs in the AHQG/AHTG matrices, and begins storing Search Console history in your database. No action needed.

= 1.6.1 =
Bot dictionary reviewed and corrected; fixes outdated upsell text on paid-edition-only screens. No action needed.

= 1.2.0 =
Major update: AHQG Matrix, GSC integration, CSV export, and bot dictionary update.
