=== WellCited – GEO & AI Visibility Audit + Fix ===
Contributors: peterbeko
Tags: geo, generative-engine-optimization, ai-visibility, ai-seo, schema
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Audit how AI engines like ChatGPT, Perplexity & Google AI Overviews see your content — then fix it in place. GEO for WordPress, built for agencies.

== Description ==

Classic SEO optimizes for ranking in a list of links. Generative Engine Optimization (GEO) optimizes for being cited: AI answer engines — ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews — read your page, extract the clearest answer they can find and quote it. Content that ranks fine in classic search can still be invisible to them: buried answers, rambling paragraphs, missing structure, no machine-readable signals.

WellCited audits how well each post can be found, understood and cited by AI answer engines — and helps you fix the findings in place, inside WordPress. Every audit runs locally in PHP on your server. No accounts, no API keys, no external services.

= The audit =

Nineteen rules score each post from 0 to 100 across six weighted categories: answer readiness, structure, schema and extractability, freshness, authority and technical. Every finding says what is wrong and exactly how to fix it. Posts too short for a meaningful audit are labeled as such instead of getting a flattering score.

= Fix in place =

* **Editor integration** — audit button, score, category breakdown and the top three fixes right in the block editor sidebar (classic editor gets a meta box).
* **Site dashboard** — average score, score distribution, your ten best and worst posts, and one-click re-audit of everything.
* **Answer Capsule** — a block (and `[wellcited_answer]` shortcode) for a clearly delimited, machine-extractable direct answer near the top of the content.
* **Structured data** — Article, FAQ (built from your question headings), Organization, Author and Breadcrumbs JSON-LD in a single graph. Strictly additive: any type your SEO plugin already outputs is skipped, never duplicated.
* **AI crawler controls** — opt-in robots.txt blocks for GPTBot, ChatGPT-User, OAI-SearchBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, cohere-ai and Meta-ExternalFetcher. Everything stays allowed unless you decide otherwise.
* **llms.txt** — a plain-text content index served at /llms.txt, with automatic deference when another plugin already provides one.
* **Freshness** — an optional machine-readable "Last updated" line.

= Honest by design =

WellCited measures machine-readability signals; nobody can guarantee that any AI engine will cite you, and this plugin does not pretend to. The frontend footprint is a few hundred bytes of structured data and capsule styling, loaded only where needed, with no extra database queries.

= External services =

None. The free plugin makes zero external requests: no API calls, no CDN assets, no telemetry, no update pings.

== Frequently Asked Questions ==

= Does it conflict with Yoast, Rank Math, All in One SEO or SEOPress? =

No — it is built to coexist and is tested alongside each of them. WellCited detects the structured data your SEO plugin already outputs and skips those types instead of duplicating them. FAQ schema is skipped per post, only when that post uses your SEO plugin's own FAQ block.

= Does it slow my site down? =

No. Audits run only in the admin area, on demand. On the frontend the plugin adds no extra database queries and at most a few hundred bytes: the JSON-LD graph, the capsule stylesheet (loaded only on pages that use a capsule) and the optional last-updated line.

= What data leaves my site? =

Nothing. Every audit runs locally in PHP on your server. The plugin makes no external requests of any kind and collects no usage data.

= /llms.txt shows a 404 — why? =

The /llms.txt address needs pretty permalinks (Settings → Permalinks, anything except "Plain"); re-save the permalink settings once after activating the plugin. On plain permalinks the same content is available at /?wellcited_llms=1.

= Where does the score come from? =

From nineteen local, rule-based checks with fixed category weights — no AI call, no black box. Checks that do not apply to a post are excluded instead of counting against it, and the sidebar lists every check behind the score.

== Screenshots ==

1. Audit sidebar in the block editor: score, category breakdown and the top three fixes.
2. Site dashboard: average score, distribution and the best and worst posts.
3. Answer Capsule block in the editor.
4. Answer Capsule on the frontend.
5. Structured data settings with automatic SEO-plugin deduplication.
6. AI crawler controls.

== Changelog ==

= 1.0.0 =
* Initial release: 19-rule GEO audit engine with editor sidebar and classic meta box, site dashboard with batched re-audit, Answer Capsule block and shortcode, additive JSON-LD structured data (Article, FAQ, Organization, Person, Breadcrumbs) with SEO-plugin deduplication, AI crawler controls, llms.txt endpoint and optional last-updated output.
* Fix: stored audit results were corrupted for posts whose audit findings contain double quotes (the saved JSON was unslashed on write); the stored audit is now slashed correctly before saving.
* Developer: the editor sidebar now exposes a `wellcited.editor.fixAction` JavaScript filter (`@wordpress/hooks`) for each failed finding, called as `applyFilters( 'wellcited.editor.fixAction', null, { finding, postId } )`. An add-on can return a React node to attach a per-finding action; the core plugin renders nothing here on its own.
