=== Agentic Optimization - SEO for AI Agents ===
Contributors: videowhisper
Tags: llms.txt, mcp, ai seo, ai agents, llm optimization
Requires at least: 6.9
Tested up to: 7.1
Stable tag: trunk
Requires PHP: 8.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Plugin URI: https://promptaur.com/wordpress/agentic-optimization/


Adds agent-friendly discovery, markdown, search, and read-only MCP access for public WordPress content, like SEO for AI agents and assistants.

== Description ==

Agentic Optimization helps WordPress sites expose public content to AI agents in a safer, WordPress-native way.

If SEO helped search engines discover, index, and understand websites, Agentic Optimization does something similar for AI agents, assistants, and LLM-powered tools. It gives public WordPress content clearer discovery files, cleaner read-only endpoints, and structured access paths that are easier for agentic systems to use responsibly.

Instead of trying to make AI tools scrape full themes, shortcodes, and plugin output blindly, this plugin helps site owners publish a more intentional agent-facing layer for public content.

Features in the free plugin:

* Root-level `llms.txt`
* Optional root-level `llms-full.txt`
* Optional `/.well-known/ai.txt` and `/ai.txt` guidance for AI-agent discovery
* Root-level `agent-sitemap.xml`
* Optional WordPress `robots.txt` enhancement with discovery hints
* Optional AI-agent user-agent routing from public content pages to the markdown view
* Optional public URL format switcher with `?vwao_view=markdown`, `json`, `html`, or `clean`
* Optional agent sitemap mode that lists public markdown variant URLs such as `?vwao_agent=1`
* Public REST search, content, markdown, comments, categories, tags, and site info endpoints
* Read-only MCP endpoint with search, content, comments, taxonomy, and site info tools
* Optional WordPress 6.9+ Abilities for public search, markdown, site info, public taxonomy/comments, and discovery endpoint reads
* Optional exposure of those abilities through the official WordPress MCP Adapter when installed separately
* Hard request caps and transient-based rate limiting
* Privacy-friendly analytics with aggregate counts and hashed IP logs only
* Admin-managed site description and site details for llms.txt context
* SEO-aware content exclusion hooks for common noindex patterns
* Extension points for future add-ons and custom integrations
* Formatter and admin hooks for add-ons that extend post type coverage or editorial agent overrides

The plugin is intentionally conservative:

* Read-only only
* Public content only
* No drafts, private content, or pending comments
* Comments exposure disabled by default
* MCP disabled by default
* WordPress Abilities registration and MCP Adapter exposure disabled by default
* Analytics disabled by default

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`.
2. Activate **VideoWhisper Agentic Optimization** in the WordPress admin.
3. Go to `Settings > Agentic Optimization`.
4. Enable the discovery outputs and APIs you want to expose.
5. Save settings to publish your selected endpoints.

== Frequently Asked Questions ==

= Which SEO plugins can it read? =

It reads WordPress search visibility and per-item/inherited robots settings from Yoast SEO, Rank Math, All in One SEO and SEOPress. Known noindex and unavailable supported-provider states are excluded while Respect noindex rules is enabled. Multiple providers are combined conservatively. Historical noindex flags are retained when no supported provider is active. Private, unpublished and password-protected content is always excluded, even if noindex protection is turned off.

The additive JSON `seo` context identifies its provider, resolution status and `provider_settings` scope. Titles, descriptions and canonical URLs use provider data where supported, otherwise editorial/permalink fallbacks. AIOSEO and SEOPress expose explicit fields rather than simulating all frontend templates. This is not a complete SEO suite or an exact simulation of arbitrary theme/frontend robots filters, redirects, headers or paginated URLs. It adds no competing SEO tags and never writes provider metadata. Review custom integrations separately.

Discovery caches reuse formatting only after checking current eligible items and SEO state. Metadata/settings edits invalidate caches, and stale in-flight builds cannot replace a newer generation. External caches that ignore no-cache headers must be purged separately. No indexing or ranking outcome is guaranteed.


= What URLs does the plugin create? =

When enabled, the plugin publishes:

* `/llms.txt`
* `/llms-full.txt`
* `/.well-known/ai.txt`
* `/ai.txt`
* `/agent-sitemap.xml`
* `/robots.txt` (enhanced virtual output when enabled)
* `/wp-json/videowhisper-agentic-optimization/v1/search`
* `/wp-json/videowhisper-agentic-optimization/v1/content`
* `/wp-json/videowhisper-agentic-optimization/v1/markdown/<id>`
* `/wp-json/videowhisper-agentic-optimization/v1/comments/<post_id>`
* `/wp-json/videowhisper-agentic-optimization/v1/site-info`
* `/wp-json/videowhisper-agentic-optimization/v1/mcp`

= Does the free plugin allow writes? =

No. The free plugin only exposes read-only access to public content.

= Does this replace the REST or MCP endpoints? =

No. WordPress Abilities are optional and additive. Existing REST, MCP, discovery, and OpenAPI-style integration surfaces remain available for clients that use them.

= Does the plugin include the WordPress MCP Adapter? =

No. If you want WordPress Abilities exposed to MCP clients through the official adapter, install and configure the WordPress MCP Adapter separately, then enable the Abilities settings in this plugin.

= How can I test AI-agent routing? =

Enable AI-agent routing on the Robots tab, then open any public post or page with `?vwao_agent=1` appended to the URL. The parameter name can be changed in settings.

= Can agents access the normal human page? =

Yes. Markdown responses include a human page URL with `?vwao_human=1`, which bypasses AI-agent redirects and returns the normal theme-rendered page.

= What does the URL view parameter do? =

When enabled, public single content URLs can render alternate views with `?vwao_view=markdown`, `?vwao_view=json`, `?vwao_view=html`, or `?vwao_view=clean`. Explicit view requests bypass AI-agent redirects.

= Does it track visitors? =

Analytics are disabled by default. When enabled, the plugin stores aggregate counters and recent event logs with hashed IP values only.

= Where do I report security bugs found in this plugin? =

Please report security bugs found in the source code of the undefined plugin through the [Patchstack Vulnerability Disclosure  Program](https://patchstack.com/database/vdp/abd3f058-724d-4545-8db5-868336e78a55). The Patchstack team will assist you with verification, CVE assignment, and notify the developers of this plugin.


== Screenshots ==

1. Overview tab showing public endpoints and feature status.
2. Discovery and MCP settings tabs.
3. Analytics tab with aggregate request counts and recent events.

== External Services ==

This plugin generates agent-optimized discovery files and sitemaps using standard XML formats.

= Sitemaps.org XML Schema =

The `agent-sitemap.xml` output uses the standard sitemap XML namespace (`http://www.sitemaps.org/schemas/sitemap/0.9`) and a custom extension URN namespace (`urn:videowhisper:agentic:1.0`). These are identifier strings embedded in locally generated XML documents only. No data is transmitted to external services when the sitemap file is generated or served.

* sitemaps.org protocol reference: https://www.sitemaps.org/protocol.html

== Changelog ==

= 1.3.0 =
* Read supported SEO provider robots settings, including inherited noindex rules, and WordPress search visibility.
* Add bounded read-only SEO context to public JSON summaries and content, preserving editorial titles and URLs.
* Recheck discovery eligibility before cache reuse; invalidate metadata/settings changes and reject stale cache writers.
* Require WordPress 6.9+ and PHP 8.2+; optional Abilities/MCP and public-only defaults remain unchanged.


= 1.2.1 =
* Remove legacy/current public caches on uninstall for each network site.
* Security: exclude password-protected content from public responses and shared caches even when the requester has unlocked it.

= 1.2.0 =
* Added optional WordPress 6.9+ Abilities for read-only public content, markdown, site info, taxonomy/comment, and agentic discovery endpoint access.
* Added settings to register WordPress Abilities and mark them public for the official WordPress MCP Adapter without replacing existing REST or MCP endpoints.

= 1.1.2 =
* Synchronized plugin version metadata and updated WordPress.org support requirements.

= 1.0.8 =

* Added optional `/.well-known/ai.txt` and `/ai.txt` discovery guidance for AI agents.
* Added configurable AI-agent user-agent routing from public single content pages to the markdown view.
* Added configurable `vwao_agent` and `vwao_human` URL parameters for agent markdown and human page variants.
* Added optional `vwao_view=markdown|json|html|clean` public URL view switching.
* Added optional agent sitemap mode that lists agent-view markdown URLs.
* Improved robots.txt recommendations with agent API allow lines when related endpoints are enabled.

= 1.0.4 =

* Added endpoint-specific public content matrices with per-endpoint discovery exposure and per-type discovery limits.
* Added grouped discovery output for `llms.txt`, `llms-full.txt`, and `agent-sitemap.xml` with improved page, post, and custom post type ordering.
* Improved agent markup conversion and fixed plain-text discovery output so markdown blockquotes and other characters are not HTML-escaped.
* Improved admin Discovery reporting and external integration hooks.

= 1.0.3 =

* Added: `vwao_post_summary` and `vwao_admin_tab_label` hooks so add-ons can extend summaries and admin navigation safely.
* Changed: the built-in post type chooser now focuses on posts and pages, while extensions can add custom post type exposure through hooks.
* Bumped stable tag to 1.0.3.

= 1.0.2 =

* Changed: REST namespace is now plugin-prefixed as `/wp-json/videowhisper-agentic-optimization/v1/...` for WordPress.org compliance.
* Bumped stable tag to 1.0.2.

= 1.0.1 =

* Fixed: Active settings tab now passed through the Settings API `$input` array, removing direct POST reads inside the sanitize callback.
* Added: `== External Services ==` section in readme.txt documenting XML namespace usage for `agent-sitemap.xml`.
* Changed: Custom `agent-sitemap.xml` extension namespace from URL form to URN (`urn:videowhisper:agentic:1.0`) to avoid implying any external service call.
* Bumped stable tag to 1.0.1.

= 1.0.0 =

* Initial release.
* Added root-level `llms.txt`, `llms-full.txt`, and `agent-sitemap.xml`.
* Added admin-managed llms.txt context fields and optional robots.txt enhancement.
* Added public REST endpoints for search, content, markdown, comments, terms, and site info.
* Added a read-only HTTP JSON-RPC MCP endpoint.
* Added rate limiting, analytics, settings UI, and extension hooks for future add-ons.

== Upgrade Notice ==

= 1.2.1 =
Security update for protected content exports and public cache invalidation.


= 1.2.0 =

Adds optional WordPress Abilities integration for sites using WordPress 6.9+ and the separately installed WordPress MCP Adapter.

= 1.0.8 =

Adds experimental ai.txt discovery, optional AI-agent routing, human-view escape URLs, and public URL view switching.

= 1.0.3 =

Adds extension hooks for editorial agent overrides and reserves custom post type exposure for hook-based add-ons.

= 1.0.2 =

Compatibility update for WordPress.org review: the public REST namespace is now plugin-prefixed.

= 1.0.1 =

Security hardening: settings sanitize callback no longer reads directly from POST; active tab is now passed via the Settings API input array.

= 1.0.0 =

Initial public release.
