=== TWT AEO Ultimate ===
Contributors: jadeslair
Tags: woocommerce, answer engine optimization, llms.txt, schema, ai citation
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.22.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

AEO plugin: get cited by ChatGPT, Perplexity, Gemini & Google AI Overviews. Connected schema, llms.txt, E-E-A-T + enhanced WooCommerce AEO.

== Description ==

**AEO Ultimate** AEO Ultimate is a fully modular optimization engine built to make your WordPress site discoverable, readable, and highly citable by AI search engines and LLM agents. As search evolves from traditional links to AI-generated answers, the plugin prepares your site by delivering connected @graph JSON-LD schema, explicit publisher/author identity (E-E-A-T), and dedicated AI-agent discovery files (like llms.txt). Designed to run smoothly alongside your existing SEO setup, AEO Ultimate lets you toggle only the features you need—ensuring you never duplicate schema or cause plugin conflicts.

Fully modular: enable only what your site needs. Every feature toggles independently.

= 🛒 WooCommerce AEO =

Built for stores: every commerce feature exists so an answer engine can quote your catalogue accurately.

* **Product Schema Engine** — every product publishes a connected Product or ProductGroup @graph with per-variant offers, identifiers, images, reviews, shipping from your live zones, and your return policy.
* **Extension-Aware Pricing** — products from Bookings, Subscriptions, Bundles and similar extensions publish "From" prices or ranges, never a definite price their own page contradicts.
* **Product FAQs** — every FAQ source on a product page is assembled into one FAQPage node, with free and AI generators for the questions shoppers actually ask.
* **Products Dashboard** — walks your whole catalogue with search and pagination, names exactly what each product is missing, and generates schema in bulk.
* **Google Merchant Center** — compares your catalogue against what Google actually lists, surfacing missing products, rejected items, and price mismatches.
* **Bing Merchant Center** — the same catalogue comparison for Microsoft's shopping index.
* **Smart Collections** — publishes your "Starter Kit" and "Under $500" style categories as real Collections with structured data an AI assistant can quote.
* **Promotions & Price Rules** — quantity breaks and member prices published as honest price specifications, with coupon codes sent to Merchant Center.
* **AI Image Alt Text** — fills missing product image alt text in bulk, one AI call per image, so every product image is content an answer engine can use.
* **Plays Nicely** — WooCommerce's own Product schema is only replaced with your one-click consent, and if AEO Ultimate for WooCommerce runs alongside, this plugin stands down automatically so nothing publishes twice.

= 🔍 Schema Markup & Structured Data =

The core engine. It detects the schema already on each page, classifies page intent (homepage, service page, blog post, location page, or product), and outputs clean JSON-LD **only where it's missing** — never duplicating what your SEO plugin already provides. Structured data includes Organization, Article, NewsArticle, Person (author), FAQPage, Service, Product (with Brand and Offer), LocalBusiness, ContactPoint, Event, Review, AggregateRating, and BreadcrumbList. The Command Center gives you a live readiness score, duplicate-schema conflict alerts, and real-time AI-crawler activity. When a page carries more than one schema type, they're automatically woven into a single connected `@graph` — one identity spine (WebSite → Organization → WebPage) with every entity cross-referenced by `@id` — so AI crawlers read your site as one web of facts instead of scattered fragments.

= 🤖 AI Ready: llms.txt & Crawler Control =

`llms.txt` and `llms-full.txt` endpoints, Markdown content negotiation for AI agents, Content-Signal headers, semantic Breadcrumb signals, RFC 8288 Link headers for agent discovery, an Agent Skills Index (`/.well-known/agent-skills/`), an Agent Search REST API, MCP/WebMCP discovery, OAuth/OIDC discovery, an RFC 9727 API catalog, and per-bot rate limiting and blocking for 20+ AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, and more). The plugin can create the `/.well-known/` agent-discovery files for you so your site reads as "agent ready" — verify it with a checker like isitagentready.com. Automatic setup needs server write access; where that's unavailable, you get copy-and-paste instructions to add the files by hand. You decide exactly which AI systems may read, cite, or train on your content.

* **Open Knowledge Format (OKF) bundle** — your site as a machine-readable knowledge directory at /okf/, on by default, linked from llms.txt.
* **AI Visibility — citation engine** — asks ChatGPT, Gemini, Claude, Perplexity, Grok and Le Chat the questions shoppers ask, on your own keys, and shows whether your site was cited, named or absent — and who was cited instead.

= 🏢 Company & Publisher Identity =

Organization JSON-LD (legal name, logo, contact points, sameAs), an explicit `article:publisher` / `article:author` Open Graph split, a sitewide `fb:app_id` for Meta Domain Insights, and one-click import from Yoast or Rank Math.

= ✍️ Author & Company E-E-A-T =

An E-E-A-T scorecard for both your author and company (publisher) entities. Author profiles output as Person schema with EducationalOccupationalCredential and sameAs — job titles, credentials, expertise areas, years of experience, and social links — alongside your organization details. The plugin suggests the missing trust items and applies them semi-automatically. Includes optional author boxes and hover cards, plus a completeness score across every author.

= 🖼️ Image SEO & Open Graph =

Generate image alt text and Open Graph titles, descriptions, and share images — **automatically from your content or with AI**. A unified Open Graph and Twitter/X Card manager scans every page for coverage and lets you edit `og:title`, `og:description`, `og:image`, `og:type`, `twitter:card`, and `twitter:creator` from one screen. Everything works in bulk: fill every missing social description, every missing alt text, and every missing FAQ, Service, or Contact schema across the whole site with one click — AI-powered bulk actions always show the billed call count and ask for confirmation first, and content-based ones are free.

= 🛒 WooCommerce & Shopping =

Automatic Product schema built from your product attributes (Brand, Offer, price, availability, GTIN/MPN/SKU), optional AI product-description enrichment, and live sync against your Google Merchant Center and Bing Merchant Center feeds — tracking price and availability mismatches, identifier gaps, and item-level rejection codes.

= 📍 Local SEO =

Build LocalBusiness schema with a predictive business-type picker, opening hours, service area, and geo coordinates. Audit NAP (name, address, phone) consistency against Google Knowledge Graph, Google Business Profile, and Bing Maps — and get a list of the directories and citation sites you should be listed on, tailored to your industry.

= 🗺️ Sitemaps, Indexing & News =

A cached XML sitemap at `/aeo-sitemap.xml` with per-post-type controls and collision protection against Yoast, Rank Math, and AIOSEO. IndexNow instantly pings Bing, Yandex, and other engines on publish. A Google News sitemap with NewsArticle schema kicks in when your content qualifies as news. And a **Not Indexed** report uses the Google Search Console URL Inspection API to find pages that are published but missing from Google's index, then flags likely causes — thin content, keyword stuffing, missing heading hierarchy — so you know what to update.

= 📊 Command Center: Analytics & Performance =

Connect Google Search Console, Google Analytics 4, and Bing Webmaster Tools for a single AEO performance view. Run Google PageSpeed Insights audits — the Lighthouse score plus the Core Web Vitals (LCP, CLS, FCP, TBT) that affect both ranking and how cleanly AI crawlers render your pages, cached for six hours. A traffic-leak scan cross-references GA4 (last 28 days) with PageSpeed to surface your highest-traffic pages that also bounce hard on slow mobile loads, and a content scan flags on-page anti-patterns — inline scripts, external scripts in content, base64 images, and iframes — that page builders and AI-pasted code often introduce. When Google and Bing surface their AI search reports (AI Mode and AI Overviews), the Command Center links you straight to them.

= 🛠️ More Tools =

Customer Reviews with context-aware AggregateRating/Review schema, display shortcodes, and industry-based suggestions for where to collect more reviews. A "Last Updated" freshness badge. PR Bridge AI, which detects press-release intent in your posts and offers ways to distribute them. And an AI Prompt Rate Limiter to protect your API budget.

= External Services & TWT Agency =

Optional AI features connect to Anthropic Claude, OpenAI, Google Gemini, and Perplexity using your own API keys. Other optional integrations cover Google and Microsoft APIs, IndexNow, and PR wire services. Nothing is sent anywhere until you configure a feature and explicitly trigger it — see the FAQ for the full list with terms and privacy links, and the bundled EXTERNAL-SERVICES.md for the complete outbound-link inventory. Optional TWT Agency connectivity is available; the plugin is fully functional standalone.

== Installation ==

= Automatic installation (recommended) =

1. In your WordPress dashboard, go to **Plugins → Add New Plugin**.
2. Search for **TWT AEO Ultimate**.
3. Click **Install Now**, then **Activate** once installation finishes.

You can also install from a downloaded ZIP: on the **Plugins → Add New Plugin** screen, click **Upload Plugin**, choose the `twt-aeo-ultimate.zip` file, then **Install Now** and **Activate**.

= Manual installation (FTP) =

1. Upload the entire `twt-aeo-ultimate` folder to your `/wp-content/plugins/` directory.
2. Activate the plugin via the **Plugins** screen in your WordPress dashboard.

= After activating =

1. Go to **TWT AEO → Modules** to review and enable the features you want.
2. Set up your publisher identity under **TWT AEO → E-E-A-T** (the **Company** tab).
3. Complete each author's E-E-A-T data on their profile under **Users → All Users**.
4. Configure bot visibility and access controls at **TWT AEO → AI Ready**.

**Important:** After activating, go to **Settings → Permalinks** and click **Save Changes** once. This flushes rewrite rules so the virtual routes for `/llms.txt`, `/llms-full.txt`, and `/aeo-sitemap.xml` resolve correctly.

== Frequently Asked Questions ==

= Which schema types (structured data) does this plugin generate? =
JSON-LD for Organization, Article, NewsArticle, Person/author (with EducationalOccupationalCredential and sameAs), FAQPage, Service, Product (with Brand and Offer), LocalBusiness (with opening hours and geo coordinates), ContactPoint, Event, Review and AggregateRating, and BreadcrumbList. Each type is added only when it suits the page and isn't already present.

= Does it support llms.txt and AI search engines like ChatGPT and Perplexity? =
Yes. It serves `/llms.txt` and `/llms-full.txt`, offers Markdown content negotiation for AI agents, sends Content-Signal headers, and gives you per-bot rate limiting and blocking for 20+ AI crawlers — the signals that help ChatGPT, Claude, Perplexity, and Google AI Overviews discover and cite your content.

= Does this plugin conflict with Yoast SEO or Rank Math? =
No. AEO Ultimate detects active SEO suites and steps back from any metadata they already output (Organization, Article, Open Graph). It acts as an enhancement layer, adding the signals those suites typically miss — `article:publisher`, rate-limit controls for 20+ AI agents, author credential schema, and `llms.txt` processing.

= What is llms.txt and why do I need it? =
`llms.txt` is an emerging standard (see llmstxt.org) that gives AI systems a clean, machine-readable summary of what your site contains and how to access it. Think of it as a `robots.txt` written for language models. The companion endpoint `/llms-full.txt` serves your content as clean Markdown so crawlers can ingest it without parsing token-heavy HTML.

= What is the OKF bundle? =
Google's Open Knowledge Format (v0.2) publishes your organization, products, categories, posts and policies as markdown concept files AI systems can ingest. TWT AEO Ultimate serves it at /okf/ automatically — nothing to configure.

= Why does the publisher/author Open Graph split matter? =
Standard social tags often blur authorship by failing to separate your brand from the individual writer. AEO Ultimate keeps them distinct: `article:publisher` establishes the company identity, while `article:author` links to the individual author. AI models use this split to assess authority and attribute content accurately.

= What does the Meta Business Sync do? =
It adds the sitewide `fb:app_id` tag, which links your domain to your Meta Developer App. That unlocks the Meta Domain Insights dashboard and helps Meta attribute your content correctly across its ad and AI systems. Most SEO plugins don't output this tag.

= Can I block specific AI bots or engines safely? =
Yes. Under **TWT AEO → AI Ready → Security & Rate Limiting**, each of 20+ known AI crawlers has a Block toggle and a custom rate-limit override. Blocking a bot writes a `Disallow` entry to your virtual `robots.txt` and returns a 403 on its requests — both advisory and hard enforcement.

= Will the rate limiter affect my human visitors? =
No. The filter matches requests by User-Agent against the known AI crawler list only. Regular browsers, ordinary visitors, and traditional search engines (like Googlebot) pass through unaffected.

= Will this add overhead or slow down my site? =
No. Frontend metadata, schema, and virtual assets are served from the WordPress Transients API with a 1-hour cache. Heavier work runs only when a post is saved or settings change. The crawler rate limiter adds a single transient read per page load, and only for known AI agents.

= Does it monitor site performance and analytics? =
Yes. The Command Center connects Google Search Console, Google Analytics 4, and Bing Webmaster Tools in one view, and runs Google PageSpeed Insights audits (the Lighthouse score plus Core Web Vitals — LCP, CLS, FCP, TBT), cached for six hours. A traffic-leak scan combines GA4 and PageSpeed to surface high-traffic pages that bounce hard on slow mobile loads, and a content scan flags performance anti-patterns like inline scripts and base64 images. Everything is optional and stays off until you connect the relevant service with your own credentials.

= Which AI agent-discovery standards does it support? =
It can serve an Agent Skills Index (`/.well-known/agent-skills/`), an MCP server card and WebMCP context injection, OAuth/OIDC discovery, an RFC 9727 API catalog, RFC 8288 Link headers, Content-Signal headers, and semantic Breadcrumb signals — alongside `llms.txt`, `llms-full.txt`, and Markdown content negotiation. Each endpoint toggles independently, and where automatic `/.well-known/` file creation needs server write access you'll get copy-and-paste instructions instead.

= What are the system requirements? =
PHP 7.4 or higher (PHP 8.0+ recommended) and WordPress 6.2+. For full functionality on WordPress 7.0 and its modern data views, MySQL 8.0 and a PHP memory limit of at least 256MB are recommended.

= What external services does this plugin connect to? =
Only the ones you configure, and only when you trigger them:

* **Anthropic Claude** — AI writing and enrichment. [Terms](https://www.anthropic.com/legal/aup) | [Privacy](https://www.anthropic.com/legal/privacy)
* **OpenAI** — descriptions, OG images, image analysis. [Terms](https://openai.com/policies/terms-of-use) | [Privacy](https://openai.com/policies/privacy-policy)
* **Google Gemini** — descriptions, vision, grounded lookups. [Terms](https://policies.google.com/terms) | [Privacy](https://policies.google.com/privacy)
* **Perplexity** — brand authority and gap research. [Terms](https://www.perplexity.ai/hub/legal/terms-of-service) | [Privacy](https://www.perplexity.ai/hub/legal/privacy-policy)
* **Google APIs** — Search Console, Analytics, Knowledge Graph, Business Profile, Merchant Center. [Terms](https://policies.google.com/terms) | [Privacy](https://policies.google.com/privacy)
* **Microsoft / Bing APIs** — Webmaster Tools, Merchant Center, Maps Local Search. [Terms](https://www.microsoft.com/en-us/servicesagreement) | [Privacy](https://www.microsoft.com/en-us/privacy/privacystatement)
* **IndexNow** — URL submission on publish. [Terms & Privacy](https://www.indexnow.org/terms)
* **EIN Presswire** — press-release distribution. [Terms](https://www.einpresswire.com/legal/terms) | [Privacy](https://www.einpresswire.com/legal/privacy)
* **EasyPRwire** — press-release distribution. [Terms](https://easyprwire.com/terms-and-condition) | [Privacy](https://easyprwire.com/privacy-policy)
* **TWT Agency** (optional) and opt-in token telemetry. [Terms](https://tampawebtech.com/plugin-terms/) | [Privacy](https://tampawebtech.com/plugin-privacy-policies/)

Each request sends only the data needed for that action, using your own API key. No site-visitor personal data is ever transmitted. The plugin also displays outbound links to industry directories and documentation sites — no data is sent to those; the complete inventory with each site's terms and privacy policy ships in EXTERNAL-SERVICES.md inside the plugin folder.

== Screenshots ==

1. **AEO Score** — Your site graded 0–100, with the site-wide breakdown of where points are lost, the site-setup checklist, your score over time, and a per-page status table below — every point named, every gap linked to its fix.
2. **AI Visibility — who gets cited instead** — Ask ChatGPT, Gemini, Claude, Perplexity, Grok and Le Chat the questions your customers actually ask, then see per engine whether your site was cited, named without a link, or absent — and exactly which competitors were cited in your place. Shown here with one-click sample data, built from your own catalogue so you can see the board before a single API call is spent.
3. **AI Visibility — every question, every engine** — The full grid: each question against each engine, with the verdict and an accuracy check against your real prices, stock levels and policies. Open any row to read what the engine said and which sources it leaned on.
4. **Command Center** — Real-time AI Crawler Watch monitor and bot traffic breakdown.
5. **AI Ready Configuration** — Per-bot rate limits and block toggles for 20+ AI agents.
6. **Company Profile Manager** — Brand identity fields and Meta Business integration.
7. **Author Profile Extensions** — Custom fields on the WordPress user profile for certifications and credentials.
8. **Schema Detector** — Auto-detects FAQ, Service, and Contact pages, fills in missing JSON-LD, and flags duplicate-schema conflicts.
9. **Image SEO** — Finds images missing alt text across your posts and pages and generates descriptive, AEO-friendly alt attributes.
10. **Modules Screen** — Enable or disable each feature independently.
11. **WooCommerce AEO** — Product schema with one-click sync to Google and Bing Merchant Center, integrity scoring, and rejection logs.
12. **Not Indexed** — Uses Google Search Console to surface published pages missing from Google's index and flags likely causes: thin content, high keyword density, and missing heading hierarchy.

== Changelog ==

= 2.22.0 =
* New: AI Visibility now records WHERE each answer named you. Every check stores the passage surrounding each mention of your company or tracked brands — on cited answers too, since a link and a prose mention are different exposures. The check drawer shows "Where the answer named you" with your name highlighted, so being one of five shops in a recommendation list is something you can read, not just a "named" verdict. A cited answer with no prose mention now says that too.
* Fixed: stored AI Visibility checks were silently dropping owned-profile citation data (owned domains, citation surface, per-brand hits) on save, so brand rollups and trends computed from stored runs undercounted owned-profile citations. Re-run a visibility run to repopulate.

= 2.21.0 =
* New: Bot View module. Fetches any page exactly the way no-JavaScript AI crawlers (GPTBot, ClaudeBot, PerplexityBot) do and reports what they can actually see: static JSON-LD and Product-node completeness, schema that only exists after JavaScript runs (Google Tag Manager tags, theme scripts), review widgets whose stars never reach the raw HTML (with the compliant first-party fix spelled out), social embeds with and without crawlable fallback text (X/Twitter, Instagram, Facebook, TikTok), video embeds missing VideoObject schema, JS-lazy-loaded images with no real src, empty client-rendered app shells, AJAX-loaded content, external iframes, a noindex check on the bot copy, and missing meta description/og:image fallbacks. Pure PHP, no headless browser; on by default under TWT AEO → Bot View.
* New: every Bot View audit fetches the page twice — once as GPTBot, once as a normal browser — and compares the two, exposing firewalls that refuse AI crawlers outright, bot-challenge pages served with HTTP 200 that silently replace your content, and setups serving bots a drastically smaller page.
* New: Bot View lists machine-readable data hiding inside scripts — dataLayer pushes, Next.js/Nuxt hydration state, WooCommerce variation JSON, product state objects — that ships in the HTML but is ignored by crawlers, flagging safe candidates to lift into server-rendered schema.
* New: weekly site-wide Bot View scan over the homepage and recently updated posts, pages and products (WooCommerce/EDD transactional pages excluded), with a regression flag when a page gets worse since the previous scan and a "Run site scan now" button.
* Fixed: AI Crawler Watch no longer counts Bot View self-audits as real crawler visits.

The complete changelog for every release ships in the changelog.txt file bundled with the plugin.

== Upgrade Notice ==

= 2.22.0 =
AI Visibility now shows the exact passage where each engine named your company or brands — see how you were mentioned, not just that you were. Also fixes stored checks dropping owned-profile citation data; re-run a visibility run after updating.

= 2.21.0 =
New Bot View screen: see any page the way no-JS AI crawlers (GPTBot, ClaudeBot, PerplexityBot) see it — what schema is visible, what is JavaScript-locked, and what hidden script data could be promoted into server-rendered schema.

= 2.20.1 =
Recommended for all sites: fixes FAQ schema publishing headings as fake questions, unicode corruption in stored schema, and a robots.txt issue that could make Google reject indexing requests. Adds duplicate meta description detection with an inline AI fix.

= 2.20.0 =
Adds machine-readable trust signals for AI search: per-post content provenance (digitalSourceType), ProfilePage schema on author archives, AI-drafted contextual authority statements for authors, and correct per-language schema on WPML/Polylang sites.

= 2.19.0 =
Critical for WooCommerce stores connected to Google Merchant Center: Google retired the Content API on August 18, 2026, breaking all Merchant Center features; this release moves to the Merchant API. Also adds machine-recognizable author credentials and citation-board fixes.

= 2.17.0 =
Adds AI Visibility, a citation engine that asks ChatGPT, Gemini, Claude, Perplexity, Grok and Le Chat what shoppers ask and records whether you were cited, named or absent. Adds an OKF bundle at /okf/. Fixes an upgrade bug that left new default-on modules switched off.

= 2.12.1 =
Fixes a critical error on servers without the PHP libsodium extension, where storing or reading a saved key or token could take a page down. Also fixes a fatal error on the Not Indexed page. Recommended for all sites.

= 2.12.0 =
Fixes a PHP fatal error that could prevent the Author Entity (E-E-A-T) admin page from loading. Recommended for all sites using author profiles.

= 2.11.0 =
Adds the unified Knowledge Graph: pages that output multiple schema types now ship one connected `@graph` (a cross-referenced entity spine) instead of scattered JSON-LD blocks, with duplicate Organization output consolidated. Single-schema pages are unchanged.

= 2.10.0 =
Adds the Smart 404 Rescue module: self-healing internal links, hacker-probe filtering, and Gemini-grounded external-link detection that auto-creates 301s — all without a bloated 404 log table.

= 2.9.1 =
Adds Google's newly recommended merchant-listing fields (priceValidUntil, sale validFrom/validThrough, and product category) plus a one-click AI resolver for the official Google Product Category (CategoryCode) to WooCommerce Product schema.

= 2.9.0 =
Initial public release on WordPress.org.
