=== BotPass — GEO Experiments for WordPress ===
Contributors: botpass
Tags: geo, ai, seo, ai citations, experiments
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 3.6.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Controlled experiments that prove which page changes make AI assistants cite you. Half your pages change, half don't. Eight weeks later, you know.

== Description ==

**BotPass is a GEO platform that proves which on-page changes make AI assistants cite your pages — using a real experiment with a control group.**

Most GEO advice is correlational: someone changed twenty things, citations went up, and nobody knows why. BotPass built the control group.

= How it works =

1. **Pick** — choose one change from a closed catalogue (never a free-text guess).
2. **Split** — your eligible pages are drawn at random into a treated half and a control half.
3. **Apply** — the plugin changes the treated pages only, always reversibly. Nothing touches the control.
4. **Measure** — BotPass queries four AI providers directly and logs every crawler that visits your pages.
5. **Compare** — after eight weeks, the difference between the two groups, with its confidence interval, is your result.

Changes that clear the statistical bar enter a shared playbook and are applied automatically to every site with that page type — including yours, whether or not you ran that experiment.

= What the plugin does =

The plugin is the WordPress half of the BotPass system. The server decides which pages get each change and measures the result; the plugin executes the assignment on your site and reports back.

**On your WordPress site, the plugin:**

* Pulls experiment assignments from the BotPass server and applies approved changes to the right pages.
* Applies every change in the render layer (not in the database), so reverting means deleting one record — nothing to undo in post content.
* Logs every crawler visit, identifies the AI provider by user-agent and IP, and sends the signal to the measurement server.
* Emits a human-referral event when a visitor arrives from an AI-referred link, which is the denominator of the extraction ratio.
* Never modifies your templates, your styles, or your SEO plugin's output.
* Works alongside Yoast, RankMath, WPML, Polylang, WooCommerce, and any standard caching layer.

= What you see in the dashboard =

**Status** — a live readiness check: plugin connected, parity verified, baseline window complete, pages inventoried. The checklist is computed from the database on every load, not from stored flags, so it stays honest even after a theme update or a caching plugin change.

**Experiments** — all experiments on your site: which are in progress, which are awaiting the AI crawl, and which have a result. Each one shows what it is waiting for and who, if anyone, needs to act.

**Settings** — API key, the opt-in/opt-out toggle for network waves, the risk ceiling for automatic changes, and the IP logging preference.

= The extraction ratio diagnostic =

Before you run an experiment, BotPass can show you your extraction ratio: how many pages each AI provider reads for every visit it sends back. The diagnostic is free, runs over 28 days, and requires no payment card. It is the first number you need to decide whether running an experiment is worth it.

= Extraction ratio by provider (industry, July 2026) =

* Mistral: 3,389 pages read per referred visit
* Anthropic: 2,237 : 1
* Perplexity: 225 : 1
* OpenAI: 217 : 1
* Copilot: 35 : 1
* Google: 4.6 : 1

Your site's number will be different. Finding it costs nothing.

= Safety and cloaking =

BotPass serves identical content to people and to AI machines. After each experiment wave, the server issues a parity report by URL and date that your SEO team and legal team can inspect. Cloaking means showing machines something different from what people see; BotPass does not do that, and the parity report is the evidence.

Every change in the catalogue is reversible with one click. A record of what was applied, to which pages, and when is always available.

= Plans =

**Network — $39/month**
Everything already proven applied to your site. You join the network waves that test new changes. Extraction ratio, always on.

**Program — $569/month**
One experiment inside your own site, up to 300 pages, with your own control group and a result with a confidence interval. Three-month minimum, because one experiment takes eight weeks.

**Program Plus — $2,199/month**
Three concurrent experiments, up to 300 pages each, with four AI providers measured.

**Agency and Enterprise — custom**
Domain portfolio view, white-label reports, REST API, SSO. Priced on request.

The diagnostic is free for any plan, no card required.

= Compatibility =

* WordPress 6.2+, PHP 8.0+
* Compatible with Yoast SEO, RankMath, All in One SEO
* Compatible with WooCommerce, WPML, Polylang
* Compatible with WP Rocket, W3 Total Cache, LiteSpeed Cache, and other page caches
* The plugin flags itself as inactive if it cannot verify parity with the active cache layer

= What BotPass is not =

* Not a visibility tool. Visibility tools measure what the AI says; BotPass changes your site and measures the difference.
* Not a GEO content agency. Nobody from our team touches your site.
* Not a guarantee of citations. Nobody controls what a model answers. Anyone who guarantees it is lying.

== Installation ==

1. In your WordPress dashboard, go to Plugins > Add New.
2. Search for "BotPass" and click Install Now, then Activate.
3. Go to BotPass > Settings and paste your API key from botpass.io.
4. The Status screen will walk you through the remaining readiness checks (baseline window, page inventory, parity confirmation).

The initial baseline window is 14 days. BotPass measures your pages before touching anything, so the experiment has a clean starting point.

For non-WordPress sites, BotPass connects over the REST API with no plugin required. See botpass.io for documentation.

== Frequently Asked Questions ==

= How is this different from the AI visibility tool I already use? =

Visibility tools measure from the outside: they query the models and report what came back. They tell you what happened. They cannot tell you why, because nothing on your site changed on purpose.

BotPass changes a randomly drawn half of your pages and compares against the untouched half. That comparison is what makes a causal claim possible. Keep your visibility tool — BotPass can read its data as a measurement source.

= How long until the first result? =

Six to eight weeks from the start of the experiment. That is how long an AI takes to come back, re-read your changed pages and reflect them in its answers. Anyone promising results sooner is not measuring anything.

= Isn't this cloaking? Could Google penalise my site? =

No. BotPass serves exactly the same content to people and to machines, and issues a parity report by URL and date that documents it. Cloaking is serving something different to machines; BotPass does not do that.

= What happens if an experiment comes back flat? =

You are told in the same detail as if it had worked, and the next hypothesis is on the list. Knowing something does not work saves you the budget you were about to spend on it. That is part of the product, not a failure.

= Who writes to my site, and with what access? =

Nobody from the BotPass team. The plugin you install, running on your own server with credentials you control, pulls a task list and applies changes only to the pages in the experiment. Every change comes from a closed catalogue and every change is reversible.

= Does the plugin write to my post content? =

No. Every change is applied in the render layer, from a flag in post meta. Reverting means deleting one database row; there is nothing to undo in the post editor. Your content is never modified.

= Is my data shared with other sites in the network? =

What is shared is the aggregate measured effect of each change: the intervention type, the page type, the effect size and its confidence interval. Never your content, your traffic, your keywords, your domain or your company name. It is specified in the Data Processing Agreement from day one.

= Does it work with my caching plugin? =

Yes. BotPass requires that each URL is served consistently — one version to people, one version to machines — and the plugin verifies this on setup. If it cannot confirm that the active cache layer varies responses by the right headers, it flags this in the Status screen and does not proceed until the cache is configured correctly.

= What does it cost? =

Network is $39 per month. Program is $569, with a three-month minimum because an experiment takes eight weeks. Program Plus is $2,199 for three concurrent experiments. Agency and Enterprise are priced on request. The extraction-ratio diagnostic is free, no card required.

= My site is not on WordPress. Can I use BotPass? =

Yes. For Shopify, Magento, PrestaShop, headless or custom builds, BotPass connects over the REST API. Your technical team integrates it once; after that it works the same way.

== External services ==

This plugin relies on the BotPass API (https://api.botpass.io), a service operated by BotPass, to assign experiments, measure results and report readiness.

What the service does: it decides which pages receive each approved change, stores crawler and referral signals, and returns the Status, Experiments and Settings state shown in wp-admin.

What data is sent and when: when the plugin syncs, it sends the site URL, page inventory counts, crawler visit signals (user-agent, and the visitor IP only if you turn that on in Settings) and your API key for authentication. No WordPress security keys, salts or user passwords are ever transmitted.

Service provider: BotPass — https://botpass.io
Terms of Service: https://botpass.io/legal/terms
Privacy Policy: https://botpass.io/legal/privacy

To use the service you create a BotPass account and paste the API key from botpass.io into BotPass → Settings. By using the plugin you agree to the BotPass Terms of Service and Privacy Policy.

== Screenshots ==

1. Status screen — live readiness checklist showing connection, parity, baseline, and page inventory.
2. Experiments view — all active and completed experiments, with what each one is waiting for.
3. Extraction ratio — your site's ratio per AI provider over the diagnostic window.
4. Experiment result — the treated vs. control citation rate, confidence interval, and verdict.
5. Settings — API key, network opt-in, risk ceiling, and IP logging preference.

== Changelog ==

= 3.6.2 =
* The public plugin listing now describes BotPass 2.0: controlled experiments, Status, Experiments and Settings.

= 3.6.1 =
* WordPress admin stays on Status, Experiments and Settings. Analytics, Entity and Reports stay in the BotPass app.

= 3.6.0 =
* New: **Status home** — site readiness and AI extraction ratio for the last 28 days, read from the Botpass API so WordPress and the experiment engine share the same figure.
* New: **GEO experiments** — inventory, work and acknowledgements sync with the Botpass API. Accept a proposal, sync now, or stop and revert with one click.
* New: **Render-time interventions** — INT-004 complete structured data, INT-008 internal link to pillar, INT-009 organisation entity, INT-012 Markdown alternate. Changes are post-meta flags, not edits to `post_content`.
* New: **Safe revert** — deactivating the plugin removes every live intervention and restores pages as they were.
* Improvement: WordPress admin now focuses on Status, Experiments and Settings. Analytics, Entity and Reports stay in the Botpass app; AJAX and download handlers remain in the plugin.
* Improvement: signup, app and API hosts from `wp-config` constants are allowed for admin redirects (needed when pointing a site at staging).

= 3.4.0 =
* New: **Standards-based content negotiation** — Markdown is served on the **same canonical URL** when a client sends `Accept: text/markdown` (RFC 9110). `Accept: */*` always returns HTML, so Googlebot and browsers behave identically.
* New: **Parity-checked Markdown** — every variant is verified against your live HTML before delivery, with a signed `X-Parity-Id` header for auditing.
* New: **Page-cache safety** — daily health checks against WP Rocket, LiteSpeed, W3TC and Cloudflare; Markdown public caching stays off until variants are proven safe (fail-closed).
* New: **Gradual rollout** — choose `negotiation_mode`: legacy bot detection (`ua`), side-by-side comparison (`shadow`), or full Accept negotiation (`accept`).
* Improvement: **Proper HTTP contract** for Markdown — `Vary: Accept`, canonical `Link`, variant ETags and `X-Content-Variant`.
* Improvement: **Richer bot analytics** — visits are recorded even when HTML is served, so your dashboard reflects detection, not only Markdown deliveries.
* Improvement: **Cleaner Markdown output** (pipeline v3) — focused YAML frontmatter; JSON-LD stays in `<head>`, separate from the Markdown body.

= 3.3.4 =
* Improvement: AI crawlers now receive Markdown for the exact public URL they visited — including custom post types and translated paths with non-Latin characters.
* Improvement: Analytics lists that same public address, so reports match what people and crawlers see.

= 3.3.3 =
* Improvement: Smoother Markdown delivery on multilingual sites (WPML and Polylang).

= 3.3.2 =
* Fix: Structured data and AI discovery links now work on your homepage and all public content types — not only single posts and pages.
* Fix: Visits from AI bots behind a CDN are counted correctly in your analytics again.
* Fix: Botpass no longer tries to optimize system or non-content URLs (sitemaps, hidden files, etc.), which makes the plugin more reliable.

= 3.3.1 =
* Fix: Your entity profile (brand name, Entity Home and profile links) now stays in sync between the WordPress plugin and the Botpass web app.

= 3.3.0 =
* New: Gutenberg GEO sidebar updates while you edit (debounced live audit) with one-click auto-fixes for JSON-LD Article, FAQPage and author.
* New: WooCommerce Product/Offer JSON-LD and product catalog section in llms.txt, with Settings toggles in the Admin UI v2.
* New: local Markdown fallback when the Botpass API is down (last good render; X-BotPass-Cache: local).
* New: wp-admin banner when a GEO grade drop alert is open.
* Improvement: content language passed to render/llms for WPML and Polylang.
* Compatibility: disable Yoast llms.txt so Botpass owns `/llms.txt`.

= 3.0.2 =
* Improvement: dashboard, analytics and entity KPIs no longer show placeholder demo values — empty states when data is not available yet.

= 3.0.1 =
* New: Fan-out analysis tab under Entity — run a fan-out audit for any URL and review subquery coverage in the plugin.
* New: on-demand Pro monthly GEO report generation, plus an in-plugin report detail view (executive summary, top posts, bots, recommendations).
* New: intercepted bots settings — choose which AI bots receive Markdown, grouped by provider, with a Google cloaking warning.
* Improvement: Reports menu item only shown when the site is connected and on the Pro or Agency plan.
* Improvement: dashboard Fan-out card links directly to the Entity Fan-out tab.

= 3.0.0 =
* New: Admin UI v2 redesign — Dashboard, Analytics, Entity and Settings with dark bento layout.
* Improvement: refreshed admin typography (Instrument Serif, Work Sans, JetBrains Mono) and Chart.js palette aligned with brand.
* Improvement: site-wide GEO Score synced from Botpass API — dashboard matches botpass.io/app, with local average fallback.
* Compliance: vis-network graph library bundled locally (no third-party CDN) for WordPress.org guideline #8.

= 2.2.0 =
* New: Entity Suite — a full GEO entity optimization layer.
* New: Entity audit with KGMID detection and confidence (resultScore) scoring.
* New: Entity Gap Radar — benchmark your entity against competitors across five axes.
* New: Entity JSON-LD (@graph, @id, sameAs, FAQPage, Person) for citation-ready entities.
* New: sameAs chain manager and Entity Home to connect Wikidata, Wikipedia, LinkedIn and Crunchbase.
* New: NAP consistency check across your site, schema, social profiles and Wikidata.
* New: semantic cluster and co-occurrence analysis to map pillar + support architecture.
* New: Entity Equity Score — a single north-star metric for your authority in front of AI.
* New: Fan-out coverage — 7th GEO Score dimension with sub-query coverage matrix in the post metabox and dashboard.
* New: Reports page (Pro/Agency) — download monthly GEO PDF reports from Botpass → Reports.
* New: Top URLs served as Markdown — Analytics panel synced from the Botpass API.
* New: llms.txt entity manifest editor — organization metadata for the semantic llms.txt About section.
* New: GEO baseline and ROI tracking — install-time average vs. current site score on the dashboard.
* Improvement: per-dimension GEO Score breakdown with weights and recommendations in the metabox.

= 2.1.0 =
* New: guided onboarding — install the plugin, choose a Pro or Agency plan (7-day free trial) on our website and connect your API key.
* New: expanded AI crawler dictionary (50+ bots) with autonomous-agent and stealth-bot detection.
* New: author authority and fact-check signals in the machine-readable output to strengthen EEAT and reduce AI hallucination.
* New: enriched metadata (author, categories, tags, language, word count) in the AI output.
* New: llms-full.txt endpoint alongside llms.txt.
* New: per-post editorial control to exclude any post from AI optimization, llms.txt or JSON-LD.
* New: manage your Pro or Agency plan and connect your API key from Botpass → Settings.
* Improvement: faster delivery to AI crawlers through intelligent content caching.
* Security: API key stored encrypted (AES-256); debug headers exposed only when WP_DEBUG is enabled.

= 2.0.0 =
* New: serviceware architecture — all advanced processing is handled by the Botpass API; no plan-gated code ships in the plugin.
* Security: registration token is no longer derived from WordPress AUTH_KEY/salts; it now uses an independent random secret.
* Improvement: all CSS and JavaScript are loaded via wp_enqueue_* functions.
* Improvement: all output is escaped; JSON-LD output hardened.
* Change: Chart.js is now bundled locally instead of loaded from a CDN.
* Docs: readme rewritten in English with full external-services disclosure.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 3.6.2 =
Public listing now matches BotPass 2.0: controlled experiments, Status, Experiments and Settings. Recommended for all users.

= 3.6.1 =
WordPress admin stays on Status, Experiments and Settings. Recommended for all users.

= 3.6.0 =
Adds a Status home (readiness + extraction ratio) and GEO experiments applied at render time — accept or stop without rewriting your posts. Analytics, Entity and Reports stay in the Botpass app. Recommended for all users.

= 3.4.0 =
Standards-compliant AI delivery: Markdown via `Accept` on the same URL, parity checks, and safer page-cache integration. Default behavior is unchanged until you switch negotiation mode in settings. Recommended for all users.

= 3.3.4 =
More accurate Markdown and analytics for every public URL crawlers visit, including multilingual and custom post type pages. Recommended for all users.

= 3.3.3 =
A smoother experience on multilingual sites. Recommended for all users.

= 3.3.2 =
Better homepage structured data, more accurate AI bot analytics on CDN sites, and improved stability. Recommended for all users.

= 3.3.1 =
Keeps your entity profile in sync between the WordPress plugin and the Botpass web app. Recommended for all users.

= 3.3.0 =
Adds live GEO editing in Gutenberg, WooCommerce Product schema and llms catalog, and a local Markdown fallback if the API is unavailable. Recommended for all users.

= 3.0.2 =
Removes placeholder demo KPIs in admin screens and shows empty states until real data is available. Recommended for all users.

= 3.0.1 =
Adds Entity Fan-out analysis, on-demand Pro monthly reports, and intercepted-bots controls. Recommended for all users.

= 3.0.0 =
Admin UI v2 redesign with synced GEO Score from the Botpass API. Recommended for all users.

= 2.2.0 =
Introduces the Entity Suite plus Fan-out coverage, monthly PDF reports (Pro/Agency), Analytics top Markdown URLs, entity manifest editor and GEO baseline tracking. Recommended for all users.

= 2.1.0 =
Adds guided onboarding (Pro/Agency plan with a 7-day free trial and API key connection), broader AI crawler and agent detection, EEAT and fact-check signals, faster cached delivery and security hardening. Recommended for all users.

= 2.0.0 =
Compliance and security update. Adds external-services disclosure, removes the CDN dependency and hardens output escaping. Recommended for all users.
