=== PufferSights - AI Crawler Insights ===
Contributors: senols
Tags: ai, crawlers, bots, analytics, llms.txt
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.1.2
License: GPLv2 or later

Monitor 100+ known AI crawler and AI agent user agents with local analytics, AI referrals, llms.txt, and opt-in robots.txt policy tools.

== Description ==

PufferSights monitors 100+ known AI crawler and AI agent user agents, hashes IP addresses, groups traffic by bot, provider, crawl purpose, content type, and response status, tracks human referrals from AI surfaces, and can publish a dynamic llms.txt content map for public site content.

The dashboard summarizes:

* HTTP traffic by bot.
* Crawl purpose.
* Content type.
* Response status.
* AI referrals and crawl-to-refer ratio.
* Top crawled content.
* Tracked agent count.
* Dynamic llms.txt content map.
* robots.txt audit and policy snippets.

The crawler registry is based on current public operator documentation and industry references for OpenAI, Anthropic, Perplexity, Google, Apple, Common Crawl, Meta, ByteDance, Microsoft, Amazon, and related AI crawler operators.

The plugin does not contact any external service. All analytics data is stored in your own WordPress database.

robots.txt publishing is off by default. The plugin can generate and optionally publish policies for:

* Monitor only.
* Block training crawlers.
* Allow AI search/user-action bots while blocking training crawlers.
* Block all known AI bots.

llms.txt publishing is on by default and can be disabled in the PufferSights settings. The generated `/llms.txt` file lists selected published public pages and posts in Markdown so AI assistants can find the site's main public content more easily.

== Important Notes ==

Crawler detection is not bot verification. User agents and signature headers can be spoofed. ChatGPT Cloud browser traffic is recognized by the claimed `Signature-Agent: "https://chatgpt.com"` identity together with `Signature` and `Signature-Input` headers. The plugin does not authenticate signatures or fetch public keys. Header matches are labeled as unverified. Raw IP addresses are not stored; the plugin stores a salted hash for rough uniqueness.

robots.txt is voluntary. Use a WAF, CDN, or server-level controls when technical enforcement is required.

Google-Extended and Applebot-Extended are robots.txt control tokens, so they appear in robots.txt audits and policy snippets but are excluded from traffic detection and the tracked-agent count. Blocking Google-Extended restricts both Gemini training and grounding, but does not affect Google Search inclusion. Both training policies include this restriction.

ChatGPT Cloud browser has no documented robots.txt token. PufferSights does not generate a rule for it or treat a wildcard robots.txt rule as a supported control for that identity. Use server or CDN controls to restrict its access.

The registry was reviewed on September 14, 2026. Google-GeminiNotebook includes Google-NotebookLM as a legacy alias. Exa uses ExaSearchBot; the unconfirmed ExaBot match has been removed. Older ExaBot records retain their original data and may contain inaccurate attribution. Historical charts group by stable crawler IDs and show current names. Legacy Anthropic and Omgili identifiers are labeled in the dashboard Help tab and bot summaries.

llms.txt is a content map, not an access-control policy. It does not replace robots.txt and does not force AI systems to use or cite your content.

== Privacy ==

PufferSights stores local analytics for public, logged-out requests only. It does not track wp-admin pages, logged-in users, AJAX requests, or WP-Cron requests.

The plugin stores:

* Request time and date.
* Event type, such as AI crawler request or AI referral.
* HTTP method.
* Request path without query string.
* HTTP response status.
* MIME/content group.
* Matched crawler or AI referral provider.
* User-agent string and user-agent hash.
* Salted one-way hash of the request IP address.
* Referrer origin only, such as `https://chatgpt.com`, without referrer path or query string.

The plugin does not store raw IP addresses, cookies, browser local storage, or complete referrer URLs. It does not send analytics, telemetry, crawler records, or site data to third-party services.

If llms.txt publishing is enabled, the plugin serves a Markdown overview of selected published public posts and pages at `/llms.txt`. Drafts, private posts, and password-protected posts are not included.

Administrators can disable tracking, clear captured events, and configure retention from the PufferSights admin page. The default retention period is 90 days. On uninstall, the plugin removes its custom analytics table, saved options, and scheduled cleanup hook.

The plugin also adds suggested disclosure text to WordPress' Privacy Policy Guide.

== Installation ==

1. Upload the `puffersights-ai-crawler-insights` folder to `wp-content/plugins`.
2. Activate PufferSights - AI Crawler Insights.
3. Open the PufferSights menu in wp-admin.

== Screenshots ==

1. Dashboard summary cards and HTTP traffic by bot.
2. Crawl purpose and AI referral summary metrics.
3. Request trend heatmap by bot across recent days.
4. Content type breakdown for crawler requests.
5. Response status breakdown for crawler requests.
6. AI referral providers and visit counts.
7. Top crawled content with request and bot counts.
8. Recent event log showing crawler and referral activity.
9. Settings screen for tracking, retention, robots.txt policy, and llms.txt.

== Frequently Asked Questions ==

= Are detected AI crawlers verified? =

No. The plugin matches user-agent strings and ChatGPT Cloud browser's claimed signature identity. Neither a matching user agent nor the presence of signature headers authenticates a request. Treat the dashboard as unverified crawler analytics unless you add server, CDN, or WAF verification.

= Does the plugin block AI crawlers? =

Not by default. robots.txt publishing is off by default. If enabled, the plugin can append crawler-specific robots.txt rules, but robots.txt is voluntary and does not technically enforce access.

= What is llms.txt? =

llms.txt is a proposed Markdown convention for giving AI assistants a concise map of important public site content. PufferSights can serve a dynamic `/llms.txt` file with selected published pages and posts. It does not expose drafts, private posts, or password-protected posts.

= Does the plugin send data to third parties? =

No. The plugin does not use external analytics APIs and does not send analytics, telemetry, crawler records, or site data to any third party.

= What happens when I delete the plugin? =

The `uninstall.php` cleanup removes the plugin options, scheduled cleanup hook, and custom analytics table.

== Changelog ==

= 0.1.2 =
* Protect ordinary search crawlers and preserve existing site restrictions when publishing AI crawler policies.
* Correct robots.txt group parsing, audit results, and public policy publication status.
* Refresh robots.txt checks without delaying the dashboard; cache results briefly and retain HTTPS certificate verification.
* Use the origin-root robots.txt URL on sites installed in a subdirectory.

= 0.1.1 =
* Add MistralAI-Training, bedrockbot, amazon-kendra, amazon-QBusiness, Mozilla-Tabstack, AIWebIndex, AIWebIndex-Agent, and Webzio.
* Update Google Gemini Notebook and Exa identifiers and robots.txt rules.
* Recognize ChatGPT Cloud browser signature-header claims without implying verification; remove its unsupported robots.txt rule.
* Clarify Google-Extended's effect on Gemini grounding and label legacy crawler identifiers.
* Keep renamed crawlers together in historical charts and exclude robots.txt-only controls from the tracked-agent count.
* Prevent Applebot-Extended policy tokens from being counted as Applebot traffic.

= 0.1.0 =
Initial release.
