=== Answer Pilot ===
Contributors: sanderversluys
Tags: ai, llms.txt, geo, chatgpt, perplexity
Requires at least: 6.4
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Bring-your-own-API-key AI search visibility for WordPress: track brand citations in ChatGPT/Perplexity/Claude, generate llms.txt, log AI bots.

== Description ==

**Answer Pilot is the bring-your-own-API-key AI search visibility plugin.** Dedicated AI-visibility tools charge €49 to €199 per month — mostly because they bundle the LLM API costs you would otherwise pay directly. Answer Pilot orchestrates the queries; you keep the bill. Typical cost on a small site: under €1/month, paid to Perplexity directly.

Beyond citation tracking, the plugin handles the full AI-readiness checklist most WordPress sites are missing:

* **Citation tracking** — runs your keywords against Perplexity on a schedule, looks for your brand in the response and the cited sources, stores results locally. Multilingual prompt templates (English, Dutch, French, German, Spanish) so multilingual sites get answers in their actual language.
* **`llms.txt` and `llms-full.txt`** generators following the proposed standard, rebuilt automatically on content change.
* **AI-bot crawl analytics** — detects 19 known crawlers (OpenAI GPTBot/ChatGPT-User/OAI-SearchBot, Anthropic ClaudeBot/Claude-Web, Perplexity, Apple Applebot-Extended, Meta, ByteDance, Amazon, Common Crawl, Cohere, Mistral and more) and logs each visit with daily pruning.
* **Robots.txt analyzer** — flags AI bots accidentally blocked by your security plugin, per crawler.
* **Per-post extractability scoring** — 0–100 grade across 9 LLM-readiness heuristics with concrete suggestions in the editor sidebar.
* **FAQ schema auto-emission** — detects question-style H2/H3 headings and adds `FAQPage` JSON-LD.
* **Admin dashboard** — metric cards, hits-per-bot, top crawled pages, extractability rankings, robots.txt analysis, citation history with sources.

The plugin only contacts an external service (Perplexity) **on explicit user action**, only when a Perplexity API key + brand name + keywords have been configured. See "External services" below for full disclosure.

= Why this and not the other llms.txt plugins? =

Three concrete differences from the existing field:

1. **Citation tracking is core, not promised "soon".** The plugin actually queries Perplexity, parses the response, and tells you whether your brand appears — not just a generator with "citation tracking coming soon" stickers.
2. **Bring your own API key.** You pay LLM providers directly. No SaaS markup. No subscription needed for the core experience.
3. **Multilingual prompts.** Citation queries are phrased in the language of your site (en/nl/fr/de/es), so non-English sites get AI answers in their actual language instead of artificially-translated English ones.

= Features =

* **`llms.txt` and `llms-full.txt` generators** — AI-readable index of your site, with smart caching that auto-invalidates on content change.
* **AI-bot crawl analytics** — automatic detection of 19 known AI crawlers (OpenAI GPTBot/ChatGPT-User/OAI-SearchBot, Anthropic ClaudeBot/Claude-Web, Perplexity, Apple Applebot-Extended, Meta, ByteDance, Amazon, Common Crawl, Cohere, Mistral and more) with daily pruning.
* **Robots.txt analyzer** — see at a glance which AI crawlers your robots.txt blocks vs allows.
* **Content extractability scoring** — per-post score 0–100 with grade A–F across 9 LLM-readiness heuristics, plus actionable suggestions in the editor sidebar.
* **FAQ schema auto-emission** — detects question-style H2/H3 headings and adds `FAQPage` JSON-LD to boost AI-citation likelihood.
* **AI citation tracking (BYO Perplexity API key)** — track whether Perplexity cites your brand for the queries that matter, in your site's language. Your API key never leaves your server.
* **Admin dashboard** — metric cards, hits-per-bot, top crawled pages, extractability rankings, robots.txt analysis, citation history with sources.
* **Settings** — retention 7–365 days, per-bot-type logging toggles, post-type whitelist, FAQ toggle, citation language override.

= Privacy =

* **No human visitor tracking.** AI-bot hits are stored locally with no IP addresses.
* **No external services called on our behalf.** The robots.txt analyzer fetches *your own* robots.txt. The citation tracker uses *your* API keys and talks only to the AI engines you enabled (see "External services").
* **GDPR-friendly.** No PII collected, no cookies set, no telemetry sent.
* All data is stored in your WordPress database in two custom tables (`*_answer_pilot_bot_hits`, `*_answer_pilot_citations`) and dropped if you uninstall.

= How AI citation tracking works (BYO API key) =

1. Get a Perplexity API key at perplexity.ai/settings/api (a few cents per query at the time of writing).
2. Paste the key in the plugin settings along with your brand name and a list of keywords.
3. Daily (or on demand), the plugin queries Perplexity in your site's language, parses the response, and records whether your brand appears.
4. The dashboard shows citation rate over 30 days, latest result per keyword, sources cited, and the full AI response.

Typical cost for a small site (10 keywords × 30 days): **less than €1/month**, paid directly to Perplexity. No middleman markup.

= Pro =

An optional Pro subscription (see the Pro features page inside the plugin) unlocks:

* **OpenAI and Anthropic citation engines** alongside Perplexity — same BYO-API-key model, you bring the keys.
* **Daily automatic citation runs** (Free runs weekly + on demand).
* **Competitor tracking** — up to 5 competitor brands with a share-of-voice table on the AI Citations page.
* **Email alerts** when a keyword starts or stops citing your brand.
* **Agency tier** with multi-site licensing.

Licenses are verified offline with public-key cryptography: the plugin never phones home, and Pro features keep working without any connection to our servers.

= Coming soon =

* Gutenberg sidebar with live extractability scoring

== Installation ==

1. Upload the `answer-pilot` folder to `/wp-content/plugins/`, or install via the Plugins screen.
2. Activate the plugin.
3. Visit Settings → Permalinks and click Save (this flushes the rewrite rules for `/llms.txt`).
4. Open `https://yourdomain.com/llms.txt` to verify the generator works.
5. To enable citation tracking, go to Answer Pilot → Settings, add your Perplexity API key, brand name, and 1-25 keywords. Then click **Run citations now** under Answer Pilot → AI Citations.

== External services ==

This plugin can connect to **three** external services — Perplexity always, OpenAI and Anthropic only when enabled with a Pro license — and only as part of the AI Citations feature. None of them is contacted on install, activation, or page loads. Every service is called with **your own** API key; billing is between you and the provider directly, and Answer Pilot does not proxy, broker, or charge for API calls.

= Perplexity API (api.perplexity.ai) =

**What the service is and what it is used for**: Perplexity is an AI answer engine. Answer Pilot uses the Perplexity Chat Completions API to ask Perplexity questions about the keywords you configure, then parses the response to detect whether your brand was cited.

**When data is sent**:

* When you click **"Run citations now"** on the AI Citations admin page.
* When the daily (Pro) or weekly (Free) cron event fires — but **only if** you have configured a Perplexity API key, a brand name, and at least one keyword on the Settings page. Without those three values configured, no cron call is ever made.

**What data is sent**: a JSON request body containing your configured keyword (phrased as a prompt in your site's locale, e.g. "Answer this question in detail and cite specific brands, websites and sources where relevant: best wordpress seo plugin 2026") and an `Authorization: Bearer <your-api-key>` header. The plugin does not send your site URL, user data, or anything you have not explicitly configured as a keyword.

**Where**: requests go to `https://api.perplexity.ai/chat/completions` via `wp_remote_post()`. Responses are stored locally in the `*_answer_pilot_citations` custom database table.

**Authentication**: the plugin uses **your own** Perplexity API key, which you obtain at [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api) and paste into the plugin Settings page. Billing for API usage is between you and Perplexity directly. Answer Pilot does not proxy, broker, or charge for API calls.

**Service terms**: by configuring a Perplexity API key in this plugin you agree to Perplexity's [Terms of Service](https://www.perplexity.ai/hub/legal/terms-of-service) and [Privacy Policy](https://www.perplexity.ai/hub/legal/privacy-policy).

= OpenAI API (api.openai.com) — Pro, opt-in =

**What the service is and what it is used for**: OpenAI operates ChatGPT. When you enable the OpenAI engine (Pro), Answer Pilot uses the OpenAI Responses API with web search to ask ChatGPT your configured keywords and detect whether your brand is mentioned or cited.

**When and what data is sent**: identical to Perplexity above — only on manual runs or the citation cron, only when the engine is enabled and an OpenAI API key is configured; the request contains your keyword phrased as a prompt and your own `Authorization: Bearer` API key. Requests go to `https://api.openai.com/v1/responses` via `wp_remote_post()`; responses are stored locally.

**Service terms**: by configuring an OpenAI API key you agree to OpenAI's [Terms of Use](https://openai.com/policies/terms-of-use/) and [Privacy Policy](https://openai.com/policies/privacy-policy/).

= Anthropic API (api.anthropic.com) — Pro, opt-in =

**What the service is and what it is used for**: Anthropic operates Claude. When you enable the Anthropic engine (Pro), Answer Pilot uses the Anthropic Messages API with the web search tool to ask Claude your configured keywords and detect whether your brand is mentioned or cited.

**When and what data is sent**: identical to Perplexity above — only on manual runs or the citation cron, only when the engine is enabled and an Anthropic API key is configured; the request contains your keyword phrased as a prompt and your own `x-api-key` header. Requests go to `https://api.anthropic.com/v1/messages` via `wp_remote_post()`; responses are stored locally.

**Service terms**: by configuring an Anthropic API key you agree to Anthropic's [Consumer Terms of Service](https://www.anthropic.com/legal/consumer-terms) / [Commercial Terms](https://www.anthropic.com/legal/commercial-terms) and [Privacy Policy](https://www.anthropic.com/legal/privacy).

== Frequently Asked Questions ==

= Does this replace Yoast or RankMath? =

No. Answer Pilot focuses on AI search engines (ChatGPT, Perplexity, Claude, Gemini) and runs alongside your existing SEO plugin. The FAQ schema emitter can be disabled if your SEO plugin already produces FAQ markup.

= Why "bring your own API key" instead of including one? =

Three reasons. (1) Privacy: your queries never pass through our servers. (2) Cost transparency: you see exactly what you're paying — typically under €1/month at modest usage instead of €49-199/month with bundled-cost competitors. (3) Sustainability: we don't have to charge a subscription to cover provider costs.

= Which AI engines are supported for citation tracking? =

Free supports Perplexity (which provides citation URLs natively in API responses). Pro adds OpenAI (ChatGPT with web search) and Anthropic (Claude with web search) — all three with your own API keys.

= How accurate is citation detection? =

The plugin reports a citation when your brand name (or one of its aliases) appears in the AI response text *or* in any of the source URLs cited by the engine. The "matched excerpt" column shows you exactly where the match was found so you can verify.

= Does this work with multilingual sites? =

Yes. Citation queries are phrased in your site's locale by default. The plugin includes templates for English, Dutch, French, German and Spanish; other languages fall back to English. You can override the locale in Settings.

= How much storage does this use? =

Bot-hit logs default to a 90-day retention window (configurable 7-365 days). Citation results have a 365-day retention window. Both tables are pruned daily by WP-Cron.

= Will AI engines actually read llms.txt? =

The standard is being adopted incrementally. Major AI labs are running pilots. Having `llms.txt` costs nothing to generate, can't hurt, and positions your site ahead of the curve as adoption grows.

== Changelog ==

= 1.1.0 =
* **Pro: OpenAI and Anthropic citation engines.** Track ChatGPT (Responses API + web search) and Claude (Messages API + web search tool) alongside Perplexity, each with your own API key. Engine models are filterable via `answer_pilot_engine_model`.
* **Pro: competitor tracking.** Up to 5 competitor brands/domains; a new share-of-voice table on the AI Citations page shows how often each one appears in the latest AI answers vs your brand.
* **Pro: email alerts.** Get an email when a keyword starts or stops citing your brand (configurable recipient, defaults to the admin email).
* **Pro licensing is live.** Stripe checkout from the Pro page; licenses are Ed25519-signed keys verified fully offline — the plugin makes zero calls to our servers.
* readme: added External services disclosures for the OpenAI and Anthropic APIs.

= 1.0.1 =
* Documentation: clarified plugin description (no more legacy "LLM SEO" references), added an explicit "External services" section disclosing how Perplexity API is called.
* Refactor: moved inline admin CSS to `wp_enqueue_style` + `wp_add_inline_style` per WordPress best practices.
* readme: fixed Contributors username.

= 1.0.0 =
* **AI citation tracking (BYO API key)**: paste your Perplexity API key, add keywords and a brand, and the plugin tracks whether AI answer engines cite you — without any third-party SaaS in between.
* Locale-aware prompt templates (en, nl, fr, de, es) so multilingual sites get answers in their own language.
* New `*_answer_pilot_citations` table with 365-day retention and daily pruning.
* New AI Citations submenu showing citation rate (30d), latest result per keyword, source URLs, and the full AI response.
* New settings: Perplexity API key (masked in UI), brand name + aliases, keywords list, citation locale override.
* All previous features (llms.txt, bot tracking, robots.txt analyzer, extractability scoring, FAQ schema, meta box) carried over unchanged.

= 0.4.0 =
* Settings page (retention, bot-type filter, post-type whitelist, FAQ toggle).
* Per-post extractability meta box in the editor.
* FAQ schema auto-emission with `FAQPage` JSON-LD on `wp_head`.

= 0.3.0 =
* Content extractability scoring (9 heuristics, grade A-F, suggestions).
* Robots.txt analyzer.
* Lowest-scoring posts table on dashboard.

= 0.2.0 =
* AI-bot detection across 19 crawlers / 12 vendors.
* Custom bot-hits table with daily pruning, dashboard, CSV export.

= 0.1.0 =
* Initial release with llms.txt and llms-full.txt generators.

== Upgrade Notice ==

= 1.1.0 =
Pro launch: OpenAI + Anthropic engines, competitor share-of-voice, and email alerts. Free features unchanged.

= 1.0.0 =
First stable release. Adds Perplexity citation tracking using your own API key — no third-party SaaS or recurring plugin fee.
