=== CloudScale SEO AI Optimizer ===
Contributors: andrewbaker007
Tags: seo, meta description, ai, opengraph, schema
Requires at least: 6.0
Tested up to: 6.9
Stable tag: 4.8.1
Requires PHP: 8.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

100% free, no upsells, no licence keys, no restrictions. Lightweight AI-powered SEO with meta description generation via the Anthropic Claude API.

== Description ==

CloudScale SEO AI Optimizer is a completely free, no-limits SEO plugin built for technical bloggers and site owners who want full control without the overhead of Yoast or RankMath. There is no Pro version, no upsells, no feature gates, and no licence keys — everything is included.

It handles the essentials cleanly — canonical URLs, OpenGraph and Twitter Card tags, JSON-LD structured data, and custom meta titles and descriptions per post — and adds an AI Meta Writer that uses the Anthropic Claude API to generate, fix, and bulk-process meta descriptions across your entire site directly from WP Admin.

**Core SEO Features**

* Custom meta title and description per post and page
* Canonical URL output on every page
* OpenGraph tags (title, description, image, type, locale)
* Twitter/X Card tags
* JSON-LD structured data: Person schema for author pages, Article schema for posts, WebSite schema for the homepage
* Configurable site name, locale, Twitter handle, and default OG image
* Scheduled batch generation via WP-Cron

**AI Meta Writer**

* Generate meta descriptions for individual posts or in bulk across your entire site
* Fix existing descriptions that are too short or too long — sends them back to Claude with the original article context and an exact character count correction
* Configurable character range (min/max) — the range is injected into the prompt automatically, so the settings and the AI are always in sync
* Automatic retry: if Claude returns a description outside your target range, the plugin sends a correction request with the exact character count before saving
* Rate limit handling: backs off automatically on HTTP 429 responses
* Model selector: Claude Sonnet or Haiku
* Fully editable system prompt with reset to default
* Live progress log with timestamps during bulk runs
* Stop button for interrupting bulk runs

**What this plugin does not do**

* No XML sitemaps (use a dedicated sitemap plugin)
* No redirect management
* No keyword analysis or readability scoring
* No paid tiers, no upsells, no tracking

== External Services ==

This plugin connects to the Anthropic Claude API to generate and fix meta descriptions. The API is called in two ways: manually, when you use the AI Meta Writer buttons in WP Admin; and automatically, when the optional Scheduled Batch feature is enabled and runs at midnight on your chosen days. The scheduled batch only processes posts that do not yet have a meta description — it never overwrites existing ones. If you disable the schedule, the API is never called without your direct action.

**Service:** Anthropic PBC (https://anthropic.com)
**Endpoint:** https://api.anthropic.com/v1/messages
**Data sent:** Post title and post content (up to 6,000 characters), plus your configured system prompt
**When data is sent:** Only when you click Generate, Fix Descriptions, or the Generate with Claude button in the post editor
**API key:** You must supply your own Anthropic API key. The key is stored in your WordPress database and is never transmitted anywhere except directly to api.anthropic.com

Anthropic Privacy Policy: https://www.anthropic.com/privacy
Anthropic Terms of Service: https://www.anthropic.com/terms
Anthropic API documentation: https://docs.anthropic.com

== Installation ==

1. Upload the plugin zip via Plugins > Add New > Upload Plugin, or extract to wp-content/plugins/cloudscale-seo-ai-optimizer/
2. Activate the plugin through the Plugins menu
3. Go to Settings > CloudScale SEO to configure your site name, OG image, and Person schema
4. To use the AI Meta Writer, go to the AI Meta Writer tab and enter your Anthropic API key (obtain one at https://console.anthropic.com)
5. Click Test Key to verify your key, then Load Posts to see your site's description status
6. Use Generate Missing to generate descriptions for posts that have none, or Fix Descriptions to correct any that are outside your configured character range

**Important:** Deactivate any other SEO plugins (Yoast, RankMath, All in One SEO) before using this plugin to avoid duplicate meta tags in your page output.

== Frequently Asked Questions ==

= Do I need an Anthropic API key? =
Only if you want to use the AI Meta Writer features. The core SEO functionality (canonical URLs, OpenGraph, Twitter Cards, structured data, custom titles and descriptions) works without any API key.

= How much does the Anthropic API cost? =
Generating descriptions for a typical 200-post blog costs approximately $1.20 to $1.50 using Claude Sonnet. Anthropic charges per token — roughly $3 per million input tokens. You control your own API key and billing directly with Anthropic.

= Will this conflict with Yoast or RankMath? =
Yes — running two SEO plugins simultaneously produces duplicate meta tags. Deactivate your existing SEO plugin before activating this one.

= Where are my meta descriptions stored? =
In WordPress post meta, using the key _cs_seo_desc. Titles use _cs_seo_title. These are standard post meta fields.

= Can I use a custom system prompt? =
Yes. The AI Meta Writer tab includes a fully editable system prompt. The character range you configure in the min/max fields is injected automatically at call time — you do not need to include it in your prompt.

= What happens if the generated description is the wrong length? =
The plugin measures the returned description before saving it. If it is outside your configured range, it automatically sends a correction request to Claude with the exact character count and direction (too short or too long). The corrected version is what gets saved.

== Screenshots ==

1. SEO Settings tab — configure site identity, OG tags, and schema
2. AI Meta Writer tab — API key, model, character range, and system prompt configuration
3. Generate Descriptions panel — summary cards, bulk action buttons, and live log
4. Post table — per-post description status badges and individual Generate buttons
5. Post editor metabox — custom title, description field, and Generate with Claude button

== Changelog ==

= 4.2.3 =
* Fix Descriptions now retries up to 3 times if Claude returns a result still outside the configured range, passing the exact character count each time
* Log shows a warning instead of a green tick when a description is saved but still out of range after all retries

= 4.2.2 =
* Added Fix Descriptions button — sends out-of-range descriptions back to Claude with exact character count and post context for targeted correction
* Badge logic now uses configured min/max values rather than hardcoded 140/160
* min/max character range now passed to JS for consistent display

= 4.2.1 =
* Increased request gap to 2,500ms to stay under Anthropic 30k token/min rate limit
* Added automatic server-side retry on HTTP 429 rate limit responses (10 second back-off)
* Increased error back-off in JS from 2,000ms to 12,000ms

= 4.2.0 =
* Character range decoupled from system prompt — range is now injected dynamically from min/max settings at call time
* Default system prompt no longer contains hardcoded character numbers
* Settings page description updated to explain automatic range injection

= 4.1.0 =
* Added automatic correction pass: if Claude returns a description outside the configured range, a follow-up correction request is sent with the exact character count before saving
* Added server-side 429 retry logic

= 4.0.0 =
* Initial release of AI Meta Writer tab
* Bulk generation with live progress log and stop button
* Per-post generation from post editor metabox
* Configurable model, character range, and system prompt
* API key test button
* Summary dashboard cards

== Upgrade Notice ==

= 4.2.2 =
Adds Fix Descriptions button for correcting out-of-range descriptions. Recommended upgrade for all users running bulk generation.
