=== CloudScale SEO AI Optimizer === Contributors: andrewjbaker Tags: seo, ai, meta description, opengraph, schema Requires at least: 6.0 Tested up to: 6.9 Stable tag: 4.19.71 Requires PHP: 8.0 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html AI-powered SEO & AEO: meta descriptions, auto linking, category management, ALT text. Bring your own Claude or Gemini API key. Free, open source. == Description == CloudScale SEO AI Optimizer is a completely free 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. It handles the essentials cleanly and adds a full AI toolkit that uses either the Anthropic Claude API or the Google Gemini API to generate meta descriptions, ALT text, summaries, SEO scores, focus keywords, internal links, and related articles — all from WP Admin, with no extra subscriptions required. = 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/BlogPosting schema for posts, WebSite schema for the homepage, Breadcrumb schema * Configurable site name, locale, Twitter handle, and default OG image * XML sitemap generation (sitemap.xml index + child sitemaps) with configurable post types and taxonomy support * Plain-text sitemap at /sitemap.txt (one URL per line) for AI crawlers and simple scrapers * Custom robots.txt editor with AI bot blocking (GPTBot, CCBot, Claude-Web, anthropic-ai and others) * llms.txt support for AI crawler guidance * noindex controls for search results, 404 pages, attachment pages, author archives, and tag archives * UTM parameter stripping in canonical URLs = AI Auto Pipeline = * Automatically runs all AI operations in a separate background process the moment a post is published — no WP-Cron dependency * Steps run per publish: meta description, SEO score, focus keyword, ALT text for all post images, AI-suggested internal links, AI summary box, and Related Articles * Re-run on update toggle: re-triggers the full pipeline whenever a published post is saved * Gutenberg-safe internal link injection using block-level parsing; classic editor fallback via str_replace * Minimum 50-word content guard prevents meaningless output on stub or test posts * HMAC-authenticated async request (120-second TTL) keeps the pipeline secure * "Re-run AI Automation" button in the post metabox with live log output * Auto Pipeline settings live in a dedicated card at the top of the AI Tools tab = AI Meta Writer = * Choose your AI provider: Anthropic Claude or Google Gemini * Model selector: Automatic (always resolves to the current recommended model), Claude 3.5/3.7 Sonnet, Claude Haiku, Gemini 2.0 Flash, Gemini 1.5 Pro, or a Custom model string * Generate meta descriptions for individual posts or in bulk across your entire site * Fix existing descriptions that are too short or too long * Fix titles that are outside the optimal 50 to 60 character range * Inline edit button on each post row — opens a textarea to manually enter or correct a description without leaving the panel * Configurable character range (min/max) injected into the prompt automatically * Automatic retry if the AI returns a description outside your target range * Rate limit handling with automatic backoff on HTTP 429 responses * Fully editable system prompt with reset to default * Sortable post table: sort by title, date, SEO score, description length, title length, or ALT status * Live progress log with timestamps during bulk runs * Stop button for interrupting bulk runs * Scheduled batch generation via WP Cron with per-day scheduling * Test Key button to verify your API key before running = AI SEO Scoring = * AI rates each post from 0 to 100 with a one-sentence strengths or weaknesses note * Calculate SEO Scores button runs a bulk scoring pass across all posts * Generate Missing automatically scores any post that lacks a score after descriptions are written * Per post score badges shown in the AI Tools post table and dashboard widget * Scores stored in post meta (_cs_seo_score, _cs_seo_notes) and survive plugin deactivation = AI Summary Box = * AI-generated article summary box automatically prepended to post content * Three fields generated per post: What it is, Why it matters, Key takeaway * Bulk generation panel with progress tracking, stop button, and paginated post list * Force regenerate option to overwrite all existing summaries * Summary fields written to Article JSON-LD schema: description, abstract, and disambiguatingDescription * Collapsible display with modern card styling including gradient header and drop shadow * Toggle to show or hide the summary box globally without deleting generated content = ALT Text Generator = * Audit all images across your posts for missing ALT text * Generate ALT text using AI with article context for better relevance * Configurable article excerpt length sent to the AI (100 to 2000 characters) * Bulk generation with progress tracking * Show All toggle to display images that already have ALT text = Related Articles = * Automatically injects contextually related post links at the top and bottom of every post * AI-scored candidate pool built across the full post library; top and bottom counts configurable (2 to 5 top, 3 to 10 bottom) * Separate top and bottom toggles — enable or disable each block independently * Generate Missing button runs the scoring pipeline for unprocessed posts * Refresh Stale button re-runs previously completed posts when content has changed * Sync Counts button trims or fills all posts to match updated count settings without full regeneration * Post Status table shows per-post pipeline state (pending, complete, failed) with filter tabs * All injection is block-safe and works with both Gutenberg and classic editor posts * Related Articles links are also generated automatically via the Auto Pipeline on publish = Performance Features = * Font display optimization with font-display: swap to eliminate Flash of Invisible Text (FOIT) * Font metric overrides (size-adjust, ascent-override, descent-override) to reduce Cumulative Layout Shift (CLS) * Defer font CSS loading using media="print" swap technique * Auto-download CDN fonts (Google Fonts) to local server for faster loading and GDPR compliance * Font CSS file scanner with terminal-style console output * Auto-Fix All with backup and undo capability * Defer render-blocking JavaScript with configurable exclusions * HTML, CSS, and JS minification (5 to 15 percent page size reduction) * HTTPS mixed content scanner and one-click fixer across posts, pages, metadata, options, and comments = SEO Health Dashboard = * Dashboard widget shows five health pillars: Posts (meta coverage), SEO (score coverage), Images (ALT coverage), Links (related articles coverage), Summaries (AI summary coverage) * Colour-coded pills: green >= 90%, amber >= 60%, red < 60% * Refresh link rebuilds the health cache on demand; cache auto-rebuilds after any bulk AI run completes * "Posts need AI auto run" and "pipeline jobs queued" counters keep you informed of pending work = Dashboard Integration = * WordPress dashboard widget with SEO health overview and per-pillar coverage pills * Post editor metabox with custom title, description, OG image, and inline AI generation * Gutenberg sidebar panel (CloudScale Meta Boxes) with custom title, description, OG image, AI summary fields, and one-click generation without leaving the editor * Per-post status badges showing description length, title length, SEO score, and ALT status * Tab state persists across page reloads — the settings page returns to your last active tab = Category Fixer = * Scans all published posts and suggests improved category assignments using AI * Uses Claude to analyse post title, slug, tags, and AI summary box against your full category list * Proposes up to four categories per post — only from categories that already exist in WordPress * Never assigns Uncategorized * Colour-coded review table: green for additions, red for removals, grey for kept categories * Per post Apply and Skip buttons, plus bulk Apply All Changed * Filter bar: All, Changed, Unchanged, Low Confidence, Missing * Reload button re-analyses all posts with fresh AI calls * Per row re-analyse button for individual posts * AI analysis badge shows confidence score * No categories are changed until you explicitly click Apply = Category Health and Drift Detection = * Category Health tab shows post counts per category with a pass/fail coverage indicator * Category Drift Detection uses AI to identify categories that have drifted from their original focus or become catch-all buckets * Drift analysis returns a verdict (drifting or catch-all) with a confidence score and AI reasoning for each flagged category * Results sorted by verdict type then confidence so the most actionable items appear first * Elapsed time counter and Stop button during long analysis runs = What This Plugin Does Not Do = * No redirect management * No keyword analysis or readability scoring * No paid tiers, no upsells, no tracking == External Services == This plugin connects to external AI APIs to generate meta descriptions and ALT text. Connections are made when you use the AI Meta Writer or ALT Text Generator buttons in WP Admin, and optionally on a scheduled basis via WP Cron. = Anthropic Claude API = **Service:** Anthropic PBC **Website:** 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, or the Generate with Claude button in the post editor, when the scheduled batch runs for posts without a meta description, or automatically on post publish/update when Auto Pipeline is enabled in AI Tools settings. **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 = Google Gemini API = **Service:** Google LLC **Website:** https://ai.google.dev **Endpoint:** https://generativelanguage.googleapis.com/v1beta/models/ **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, or the scheduled batch runs, when Gemini is selected as your AI provider, or automatically on post publish/update when Auto Pipeline is enabled in AI Tools settings. **API key:** You must supply your own Google AI API key. The key is stored in your WordPress database and is never transmitted anywhere except directly to Google. Google Privacy Policy: https://policies.google.com/privacy Google Terms of Service: https://policies.google.com/terms Gemini API documentation: https://ai.google.dev/docs = Google Fonts CDN = **Service:** Google LLC **Websites:** https://fonts.googleapis.com, https://fonts.gstatic.com **When contacted:** Only when you use the Font Display Optimizer's "Download Fonts" feature in WP Admin (Performance tab). This feature downloads Google Fonts files to your server so they can be served locally. **Data sent:** The URL of the Google Font stylesheet registered on your site. No personal data or post content is transmitted. **Purpose:** To copy font files from Google's CDN to your own server, eliminating the external Google Fonts request from your frontend pages (improves GDPR compliance and Core Web Vitals). Google Privacy Policy: https://policies.google.com/privacy Google Terms of Service: https://policies.google.com/terms == 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 Optimise SEO tab and enter your API key for either Anthropic Claude or Google Gemini 5. Click Test Key to verify your key, then Load Posts to see your site description status 6. Use Generate Missing to create descriptions for posts that have none, or Fix Descriptions to correct any that are outside your configured character range 7. Visit the Performance tab to enable font optimization, JavaScript deferral, and HTML minification **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 API key? = Only if you want to use the AI Meta Writer or ALT Text Generator features. The core SEO functionality (canonical URLs, OpenGraph, Twitter Cards, structured data, custom titles and descriptions) works without any API key. = Which AI provider should I choose? = Both work well. Anthropic Claude tends to produce slightly more nuanced descriptions. Google Gemini Flash is extremely fast and cost effective for large sites. You can switch providers at any time without losing any generated content. = How much does the API cost? = Generating descriptions for a typical 200 post blog costs approximately $1.20 to $1.50 using Claude Sonnet, or under $0.50 using Gemini Flash. Both providers charge per token. You control your own API key and billing directly with each provider. = 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. OG images use _cs_seo_ogimg. These are standard post meta fields that persist if you deactivate the plugin. = Can I use a custom system prompt? = Yes. The AI Meta Writer section includes a fully editable system prompt. The character range you configure in the min/max fields is injected automatically at call time. = 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 the AI with the exact character count and direction. The corrected version is what gets saved. = How does font display optimization work? = The plugin scans your theme and plugin CSS files for @font-face rules and injects font-display: swap to prevent fonts from blocking page rendering. It also adds metric overrides to reduce layout shift when fonts load. All changes create a backup that you can undo with one click. Enable these features in the Performance tab. = How does JavaScript deferral work? = Adding the defer attribute to script tags allows them to download in parallel with HTML parsing and execute only after the document is ready. jQuery and other commonly problematic scripts are excluded automatically. You can add additional exclusions by script handle or URL substring. = Can I schedule automatic description generation? = Yes. The Scheduled Batch tab lets you select which days of the week to run automatic generation. The batch runs at midnight server time and only processes posts that do not yet have a meta description. It never overwrites existing ones. = What does Auto Pipeline do? = Auto Pipeline fires a background process the moment a post is published. It runs every AI step in sequence: meta description, SEO score, focus keyword, ALT text for all post images, AI-suggested internal links, AI summary box, and Related Articles. The process runs in a separate PHP request so it does not slow down the publish action. You can also trigger a re-run manually from the post metabox using the "Re-run AI Automation" button. = What is the Automatic model option? = Selecting Automatic tells the plugin to always use the current recommended model for your chosen provider (currently claude-sonnet-4-6 for Anthropic and gemini-2.0-flash for Google). When Anthropic or Google release a better default model the plugin will automatically switch without any settings change on your part. Users who have already pinned a specific model are not affected. = How does Related Articles work? = The plugin scores all posts against each other using shared categories, tags, and content signals, then stores a ranked candidate pool per post. The top two to five links appear above the post content and three to ten appear below. You control the counts from the Related Articles settings. The Generate Missing button processes unscored posts; Sync Counts adjusts existing results to match updated count settings without running the full pipeline again. == Screenshots == 1. SEO Settings tab showing site identity, OG tags, and schema configuration 2. AI Tools tab with Auto Pipeline card, provider selection, API key, and model chooser 3. Generate Descriptions panel with summary cards, bulk action buttons, and live progress log 4. Post table showing per-post description, title, SEO score, and ALT status badges 5. Post editor metabox with custom title, description field, and Re-run AI Automation button 6. Performance tab with font optimization, JavaScript deferral, and minification settings 7. ALT Text Generator with image audit table and bulk generation 8. Related Articles Post Status table with pipeline state filters and Sync Counts button 9. Category Fixer review table with colour-coded category pills and Apply/Skip controls 10. Dashboard widget showing SEO health pills with colour-coded coverage scores == Changelog == = 4.19.71 = * Update: version bump = 4.19.50 = * Add: "Automatic" model option — new default that always resolves to the current recommended model per provider (claude-sonnet-4-6 / gemini-2.0-flash); existing users with a pinned model are unaffected = 4.19.11 = * Add: sitemap.txt endpoint — plain-text sitemap (one URL per line) served at /sitemap.txt alongside the existing XML sitemap = 4.19.4 = * Fix: debug_log() method added to main class — font optimizer and OG letterbox AJAX handlers threw fatal errors in production; now delegates to Utils::log() for a single logging code path * Fix: orphaned duplicate DocBlocks removed from trait-ai-meta-writer.php * Fix: missing DocBlocks added across main class, trait-ai-meta-writer.php, and trait-settings-assets.php * Fix: @package tag added to trait-settings-assets.php file DocBlock = 4.19.3 = * PCP: moved phpcs:ignore for post__not_in to same line as violation in trait-auto-pipeline.php, trait-ai-meta-writer.php, and trait-sitemap.php — inline suppression is required for PHPCS to recognise it = 4.19.2 = * PCP fix: echoed