ThemeMiles SEO Agent Pro
Complete Pro User Guide
ThemeMiles SEO Agent Pro adds a full AI Fix Engine, rollback system, Google Search Console integration, Schema auto-generation, GEO/AEO optimization, Core Web Vitals monitoring, and autonomous nightly mode on top of the free audit engine.
01 — What's New in Pro
ThemeMiles SEO Agent Pro extends the free plugin's audit engine with an AI fix pipeline, rollback safety net, and advanced intelligence features. All features from the free version are included.
🤖 AI Fix Engine
Generate SEO-optimized meta titles, descriptions, alt text, OG tags, and schema markup using your own OpenAI, Anthropic, or Groq API key.
↩️ One-Click Rollback
Revert any individual fix, an entire audit run, or all changes to a post back to its original state — instantly and safely.
📊 Google Search Console
Connect GSC to see real-world impressions, clicks, and position data alongside your SEO issues. Track impact after fixes automatically.
🏗️ Schema Auto-Generator
Automatically detects content type (Article, FAQ, HowTo, Product, Recipe) and generates valid JSON-LD schema markup with AI assistance.
🌐 GEO / AEO Optimization
Score and improve content for AI search engines (ChatGPT, Perplexity, Google SGE) with direct-answer blocks and structured responses.
⚡ Core Web Vitals
Integrates PageSpeed Insights to detect performance bottlenecks and pause content fixes on pages with poor CWV scores.
🌙 Autonomous Nightly Mode
Audits, generates fixes, and applies them automatically overnight — within the safety rules you define. Wakes you up to a healthier site.
🛡️ YMYL Safety Mode
Automatically detects health, finance, and legal content. Requires manual review before applying AI fixes — no surprises on high-stakes pages.
02 — Requirements
| Requirement | Minimum | Recommended |
|---|---|---|
| WordPress | 6.3 | 6.7+ |
| PHP | 8.0 | 8.2+ |
| MySQL | 5.7 / MariaDB 10.4 | 8.0+ |
| WP Cron / Action Scheduler | Required | True WP-Cron or WP-CLI cron |
| AI API key | OpenAI, Anthropic, or Groq | OpenAI GPT-4o-mini (best cost/quality) |
| SEO Plugin | None (writes to custom meta) | Yoast SEO, Rank Math, or AIOSEO |
| ThemeMiles SEO Agent Free | Must NOT be active — Pro replaces it entirely | |
Free plugin conflict
ThemeMiles SEO Agent Pro blocks itself from loading if the free ThemeMiles SEO Agent is also active. Deactivate and delete the free plugin before installing Pro.
03 — Installation & Upgrade
Fresh Install
thememiles-seo-agent-pro.zip.Upgrading from Free
Your data is preserved
Both plugins share the same database tables (wp_thememiles_seo_agent_issues, wp_thememiles_seo_agent_fixes, wp_thememiles_seo_agent_snapshots, wp_thememiles_seo_agent_audit_runs). Switching to Pro keeps your audit history intact.
04 — License Activation
Go to ThemeMiles SEO Agent Pro → License in your WordPress admin.
License page — ThemeMiles SEO Agent Pro → License
05 — Pro Onboarding Wizard
The onboarding wizard launches automatically after license activation. It takes about 3 minutes and configures everything needed to run AI fixes.
06 — AI Engine Setup (BYOK)
ThemeMiles SEO Agent Pro uses a Bring Your Own Key model. You pay your AI provider directly — we never markup the cost or store your key on our servers.
Estimated cost
A typical fix (meta title + description generation) costs ~$0.0003 with GPT-4o-mini. A 500-page site costs roughly $0.15 total to generate all fixes.
Supported Providers
| Provider | Recommended Model | Cost/fix (est.) | Speed |
|---|---|---|---|
| OpenAI | gpt-4o-mini | ~$0.0003 | Fast |
| Anthropic | claude-haiku-4-5 | ~$0.0004 | Fast |
| Groq | llama-3.1-8b-instant | ~$0.0001 | Very fast |
Configure in Settings
Settings → AI Engine
API key security
Your API key is stored encrypted in wp_options and never transmitted to ThemeMiles servers. It is only sent directly to your chosen AI provider when generating fixes.
07 — Audit & SEO Brain
The Pro audit engine runs all free checks plus three additional checks powered by Pro-only modules.
Pro-Only Audit Checks
| Check | Severity | Trigger |
|---|---|---|
| GEO Readiness | Major | GEO score < 50 — content not optimized for AI search engines |
| Entity Schema | Major | Organization JSON-LD not present in site-wide schema |
| Core Web Vitals | Critical | 100+ impressions and PageSpeed score is poor or needs improvement |
SEO Brain Dashboard Widget
The SEO Brain widget on your dashboard shows a smart summary of your site's top priorities — ranked by impact score, not just severity count.
🔴 Fix Immediately
Issues with a Priority Score ≥ 70. Critical severity + high impressions. Address these first for the fastest ranking lift.
🟡 Fix This Week
Priority Score 40–69. Important issues that should be addressed soon but aren't urgent emergencies.
🔵 When Possible
Priority Score < 40. Minor issues, low-traffic pages. Safe to batch and apply during a quiet window.
⚡ Bulk Fix All
One-click button to queue all open AI-fixable issues. Pro users see the full fix queue with approve/reject controls.
08 — Fix Queue
The Fix Queue (ThemeMiles SEO Agent Pro → Fix Queue) is the core of the Pro experience. Every AI-generated fix appears here as a diff card before it's applied to your site.
Fix Queue — diff cards with before/after comparison
Fix Types Generated
| Fix Type | Target Field | Char Limit |
|---|---|---|
| Meta Title | SEO plugin meta title field | 30–65 chars |
| Meta Description | SEO plugin meta description field | 145–160 chars |
| Image Alt Text | wp_postmeta image alt | 5–125 chars |
| OG Title | Open Graph title field | 30–65 chars |
| OG Description | Open Graph description field | 10–200 chars |
| Schema Markup | JSON-LD via SEO plugin or _thememiles_seo_agent_schema_json | Valid JSON-LD |
Per-Fix Actions
09 — Auto-Fix Rules
Auto-Fix Rules let you define conditions under which fixes are applied automatically — without manual approval. Useful when combined with Autonomous Nightly Mode.
Available Rules
YMYL always stays manual
YMYL Safety Mode overrides auto-fix rules. Health, legal, and finance content is always forced to pending status for your review — auto-fix rules cannot override this.
10 — Applying Fixes
When a fix is approved, ThemeMiles SEO Agent Pro follows this sequence to safely write the new value:
meta_title, meta_desc, og_title, og_desc, image_alt, schema_markup) into wp_thememiles_seo_agent_snapshots. One snapshot per post per day.wp_thememiles_seo_agent_issues is updated to status = fixed. The fix row is marked applied.11 — Rollback & Fix History
Every fix can be rolled back at any time. Go to ThemeMiles SEO Agent Pro → Fix History.
Rollback Levels
original_value from the fix record back via FieldWriter. The issue is re-opened.Impact Badges
Each applied fix shows an impact badge after 7 days if GSC is connected:
🟢 Improved
Average position went up (lower number). The fix positively affected rankings.
🟡 Neutral
Position change within ±1. Could be noise — monitor for another week.
🔴 Declined
Position went down after the fix. Consider rolling back and trying a different approach.
⚪ Pending
Not yet 7 days since the fix was applied. Impact data not yet available.
12 — Autonomous Nightly Mode
When enabled, ThemeMiles SEO Agent Pro runs a full audit, generates fixes, and applies them automatically every night — within the safety guardrails you've defined.
Use with care on live sites
Autonomous mode writes to your site without intervention. Always configure Auto-Fix Rules conservatively before enabling, and verify that YMYL Safety Mode is active for any health, legal, or finance content.
What Autonomous Mode Does Nightly
- Runs a full incremental audit (posts modified in the last 7 days + any unaudited posts)
- Re-scores all issues using the Priority Scorer
- Generates AI fixes for all open, AI-fixable issues that pass the priority threshold
- Applies fixes that match your Auto-Fix Rules (YMYL content always stays pending)
- Sends an email summary report if email reports are configured
Enable Autonomous Mode
13 — Google Search Console
Connecting GSC gives ThemeMiles SEO Agent Pro real-world keyword data, impressions, and click-through rates — and enables automatic impact tracking after fixes.
What GSC Data Is Used For
| Data Point | How It's Used |
|---|---|
| Impressions | Priority Scorer weights high-impression pages higher — they get fixed first |
| Average Position | Stored as baseline before each fix for impact comparison after 7 days |
| Clicks / CTR | Shown in Fix History impact cards to measure the full fix effect |
| Top Queries | Provided to AI as context when generating meta descriptions for better keyword alignment |
14 — Schema Auto-Generator
ThemeMiles SEO Agent Pro detects the right schema type for each piece of content and generates valid JSON-LD markup automatically.
Supported Schema Types
📰 Article
Default for blog posts and pages. Includes headline, author, datePublished, and image.
❓ FAQPage
Detected when content contains Q&A formatting. AI extracts individual Q&A pairs for structured markup.
📋 HowTo
Detected when content contains numbered steps. AI extracts each step name and description.
🛍️ Product
Automatically applied to WooCommerce product post types with name, description, and price data.
🍳 Recipe
Detected when content contains ingredient lists. Generates full Recipe schema with ingredients and steps.
🏢 Organization
Site-wide entity schema injected in <head>. Configure your logo and social URLs in Settings → Entity Schema.
Detection Priority
- WooCommerce product → Product schema (always)
- Step-pattern content → HowTo schema
- Q&A pattern → FAQPage schema
- Ingredient-list pattern → Recipe schema
- AI fallback → asks the AI to identify the best schema type
- Default → Article schema
Schema injection method
If Yoast SEO, Rank Math, or AIOSEO is active, schema is written to that plugin's schema field. Otherwise it's stored in _thememiles_seo_agent_schema_json meta and output via a wp_head hook.
15 — GEO / AEO Optimization
Generative Engine Optimization (GEO) and Answer Engine Optimization (AEO) help your content appear in AI-powered search results from ChatGPT, Perplexity, and Google's AI Overviews.
GEO Score Breakdown
| Sub-Score | What It Measures | Weight |
|---|---|---|
| Answer First | Does the content start with a direct, concise answer? | 25% |
| Structure | Are headings, lists, and tables used for scannability? | 20% |
| FAQ Presence | Are specific questions answered in FAQ format? | 20% |
| Definition Block | Are key terms defined clearly at the start? | 20% |
| Citation Signals | Are claims backed by stats, dates, or authoritative sources? | 15% |
GEO Fixes
When a GEO Readiness issue is detected, ThemeMiles SEO Agent Pro can generate two types of AI-powered improvements:
16 — Core Web Vitals
ThemeMiles SEO Agent Pro integrates with Google's PageSpeed Insights API (v5) to monitor Core Web Vitals for your high-traffic pages.
Metrics Tracked
CWV + Content Fix Integration
Pages with a Performance Score below 40, or LCP above 4 seconds and 1,000+ impressions, are automatically excluded from AI content fixes. The logic: fixing meta text won't help if the page is too slow to rank anyway. Address performance first.
CWV checks run weekly
PageSpeed Insights is called weekly for your top 50 posts by impressions. Results are cached for 48 hours. You can trigger a manual check from Settings → Core Web Vitals → Check Now.
17 — Competitor Analysis
Competitor Analysis lets you benchmark your top pages against competing content in the same SERP. Connect a DataForSEO key in Settings → Competitor Analysis.
📈 SERP Position Tracking
See where your page ranks vs. competitors for your target keywords, pulled from DataForSEO's live SERP data.
🔍 Content Gap Analysis
Identify topics your competitors cover that your content misses — a direct input for content improvement suggestions.
🏷️ Schema Gap Detection
Checks whether top-ranking competitors use schema types you don't — triggers a schema issue in the audit queue.
📊 CTR Comparison
Compare your GSC click-through rate against estimated competitor CTR at the same position to gauge title/description effectiveness.
Competitor Analysis requires a DataForSEO API key (separate paid service). Estimated cost: ~$0.002 per keyword per SERP check.
18 — Content Decay Detection
Content Decay Detection monitors your historical GSC data to surface pages whose traffic is steadily declining — before the drop becomes catastrophic.
How It Works
- Pulls 90 days of GSC click and impression data weekly for all indexed posts
- Computes a rolling 30-day vs. prior-30-day change for impressions, clicks, and position
- Flags posts with > 20% decline in impressions over two consecutive 30-day periods
- Creates a content_decay issue in the audit queue with severity based on traffic volume
- Suggests whether the post needs a content refresh, consolidation, or canonical update
What to do with a decay alert
Use the AI fix to generate a fresh meta title and description targeting updated search intent. Then manually refresh the post body — ThemeMiles SEO Agent does not rewrite post content, only SEO meta fields.
19 — YMYL Safety Mode
YMYL (Your Money or Your Life) content — health, finance, legal, and safety topics — requires extra scrutiny before AI-generated SEO changes are applied.
How YMYL Is Detected
- Manual flag: Post has
thememiles_seo_agent_ymyl_manual = 1meta (set via the post editor sidebar) - Taxonomy match: Post is in a category or tag whose name/slug contains YMYL signals (e.g., "health", "legal", "finance")
- URL slug match: Post slug contains YMYL keywords
- Content keyword density: Post body contains 3 or more YMYL signals with high frequency
YMYL Behavior
pending status. An error log entry is recorded.Cannot be disabled for auto-fix
YMYL Safety Mode cannot be turned off for automatic fix application. This is intentional. For edge cases where you want to auto-apply to a specific YMYL page, remove the manual flag and re-queue.
20 — Impact Tracking
Impact Tracking measures whether your AI fixes actually improved rankings — closing the feedback loop between fix and outcome.
How Impact Is Measured
Impact Tracking requires Google Search Console to be connected. Without GSC, fixes still apply and roll back correctly, but the impact badge shows "No GSC data".
21 — Agency Dashboard
The Agency Dashboard provides a high-level overview across multiple client sites — for agencies managing ThemeMiles SEO Agent Pro on several WordPress installs.
Available on Agency license tier
The Agency Dashboard requires an Agency license (unlimited sites) rather than the standard single-site or 5-site licenses. Each site still needs its own active ThemeMiles SEO Agent Pro installation.
🏢 Multi-Site Overview
See all connected sites in one grid — health score, pending fixes, last audit date, and license status at a glance.
📤 Bulk Fix Dispatch
Trigger AI fix generation across multiple sites from a single dashboard. Each site's fixes are queued independently.
📊 Aggregate Reporting
Export a combined CSV of audit issues, fixes applied, and impact metrics across all client sites for monthly reports.
🎨 White-Label Mode
Hide ThemeMiles SEO Agent Pro branding and replace with your agency name and logo in the WordPress admin for client-facing dashboards.
22 — Email Reports
ThemeMiles SEO Agent Pro can send automated email summaries of audit results and fix activity. Configure under Settings → Email Reports.
After autonomous mode runs each night, a summary email is sent if recipients are configured. Use this as a morning briefing — no need to log in daily to check progress.
23 — Settings Reference
All Pro settings live under ThemeMiles SEO Agent Pro → Settings. Below is a complete reference.
General
AI Engine
Autonomous & Auto-Fix Rules
Integrations
24 — FAQ
Does ThemeMiles SEO Agent Pro work without a supported SEO plugin?
Yes. If no SEO plugin is detected, fixes are written to custom post meta fields (_thememiles_seo_agent_meta_title, _thememiles_seo_agent_meta_desc, etc.) and output via wp_head hooks. However, we strongly recommend using Yoast SEO, Rank Math, or AIOSEO so fixes integrate seamlessly with your existing SEO setup.
Can I use ThemeMiles SEO Agent Pro alongside the free plugin?
No. Pro replaces the free plugin entirely. ThemeMiles SEO Agent Pro will not load if ThemeMiles SEO Agent (free) is active — a notice will appear in the admin. Deactivate and delete the free plugin first.
What happens if my AI API key runs out of credits?
Fix generation fails gracefully. A notice appears in the Fix Queue explaining the error. Existing approved fixes are unaffected. Autonomous mode skips the generation step and logs the error.
Will AI fixes overwrite SEO fields I've already manually set?
Only if you approve or auto-apply the fix. Pending fixes never touch your live fields. Auto-fix rules only apply to fields that are currently empty or below the minimum character count for that field type.
Can I roll back multiple months of fixes?
Yes, as long as the snapshot exists. Snapshots are stored indefinitely until you uninstall the plugin. You can roll back any fix or any audit run regardless of how old it is.
Does autonomous mode run if WP-Cron is disabled?
Autonomous mode uses Action Scheduler, which works with both WP-Cron and server-side cron. If you use a server-level cron job (wp-cron.php), autonomous mode fires at the scheduled time reliably.
How does YMYL detection handle edge cases?
The detector is conservative — it errs on the side of flagging content as YMYL. If a post is incorrectly flagged, you can remove the manual YMYL flag via the post editor sidebar or adjust the categories/tags that trigger the taxonomy match. You cannot disable YMYL safety for auto-fix.
Can I run ThemeMiles SEO Agent Pro on multiple sites?
Each license covers a set number of site activations (check your license type at purchase). An Agency license covers unlimited site activations. Manage activations at thememiles.com → My Account → Licenses.
What if I deactivate ThemeMiles SEO Agent Pro but want to return later?
Your data remains in the database tables. Reactivating Pro and entering your license key restores full functionality. All audit history, fix records, and snapshots are preserved.
Where can I get support?
Pro license holders receive priority email support at support@thememiles.com. Include your site URL and license key in the subject line for faster routing.