claude-plugin-wordpress-manager 2.2.0 → 2.3.0

package/skills/wp-programmatic-seo/references/location-seo.md

@@ -0,0 +1,134 @@
+# Location-Based SEO
+
+Use this file when creating city/location pages at scale — service-area combinations, LocalBusiness schema, geo-targeting, and NAP consistency.
+
+## City/Location Page Patterns
+
+Location pages combine a service or product with a geographic area:
+
+| Pattern | Template | Scale |
+|---------|----------|-------|
+| Service + City | "Plumbing in {city}" | services × cities |
+| Store + City | "{brand} Store in {city}" | stores × locations |
+| Restaurant + Area | "Best {cuisine} in {neighborhood}" | cuisines × neighborhoods |
+| Real estate + City | "Homes for Sale in {city}" | property types × cities |
+
+**Content formula for each page:**
+1. H1: `{Service} in {City}`
+2. Intro paragraph (50–80 words) with local context
+3. Service details section (150–200 words)
+4. Local information (population, area facts, nearby landmarks)
+5. FAQ section (3–5 questions) with local keywords
+6. CTA with phone number and address
+
+## LocalBusiness Schema Markup
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "LocalBusiness",
+  "name": "{business_name} — {city}",
+  "description": "{service_description} in {city}",
+  "url": "https://example.com/{service}/{city}",
+  "telephone": "{phone}",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "{street}",
+    "addressLocality": "{city}",
+    "addressRegion": "{state}",
+    "postalCode": "{zip}",
+    "addressCountry": "{country_code}"
+  },
+  "geo": {
+    "@type": "GeoCoordinates",
+    "latitude": "{lat}",
+    "longitude": "{lng}"
+  },
+  "openingHoursSpecification": [
+    {
+      "@type": "OpeningHoursSpecification",
+      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+      "opens": "09:00",
+      "closes": "17:00"
+    }
+  ],
+  "areaServed": {
+    "@type": "City",
+    "name": "{city}"
+  }
+}
+```
+
+**Schema variations by business type:**
+- `@type: "Restaurant"` — add `servesCuisine`, `menu`, `priceRange`
+- `@type: "MedicalBusiness"` — add `medicalSpecialty`
+- `@type: "Store"` — add `paymentAccepted`, `currenciesAccepted`
+
+## Geo-Targeting Configuration
+
+### Google Search Console
+1. Set geographic target per property (if using country-specific domains)
+2. Submit location-specific sitemap: `/sitemap-locations.xml`
+3. Monitor "Search results" by country/city in Performance report
+
+### WordPress Implementation
+- Use ACF or custom fields for lat/lng storage
+- Store city, state, zip as separate meta fields (not combined string)
+- Create a `location` taxonomy for hierarchical grouping (country → state → city)
+
+## NAP Consistency
+
+**NAP = Name, Address, Phone** — must be identical across all location pages.
+
+| Element | Rule | Example |
+|---------|------|---------|
+| Name | Exact legal business name | "Smith Plumbing LLC" (not "Smith's Plumbing") |
+| Address | USPS-standardized format | "123 Main St, Ste 100" (not "123 Main Street Suite 100") |
+| Phone | E.164 format in schema, formatted for display | `+15551234567` schema, `(555) 123-4567` display |
+
+**Verification:** Cross-check NAP against Google Business Profile, Yelp, and BBB listings.
+
+## Local Keyword Research Methodology
+
+1. **Seed keywords:** core service terms (plumbing, dentist, attorney)
+2. **Location modifiers:** city names, neighborhoods, zip codes, "near me"
+3. **Intent modifiers:** "best", "affordable", "emergency", "24/7"
+4. **Combine:** `{intent} {service} in {location}` → "emergency plumber in Miami"
+5. **Validate:** Check search volume via keyword tools; prioritize cities with volume > 100/mo
+6. **Cluster:** Group by parent topic to avoid cannibalization
+
+## WordPress CPT for Locations
+
+```php
+// fields: city, state, zip, lat, lng, population, local_description
+register_post_type('service_location', [
+    'public'       => true,
+    'show_in_rest' => true,
+    'supports'     => ['title', 'editor', 'custom-fields', 'thumbnail'],
+    'taxonomies'   => ['service_type', 'region'],
+    'rewrite'      => ['slug' => 'services'],
+]);
+
+// Expose custom fields via REST API
+register_rest_field('service_location', 'location_meta', [
+    'get_callback' => function ($post) {
+        return [
+            'city'       => get_post_meta($post['id'], 'city', true),
+            'state'      => get_post_meta($post['id'], 'state', true),
+            'zip'        => get_post_meta($post['id'], 'zip', true),
+            'lat'        => get_post_meta($post['id'], 'lat', true),
+            'lng'        => get_post_meta($post['id'], 'lng', true),
+            'population' => get_post_meta($post['id'], 'population', true),
+        ];
+    },
+    'schema' => ['type' => 'object'],
+]);
+```
+
+## Decision Checklist
+
+1. Does the business serve multiple geographic areas? → Yes = location pages justified
+2. Is there search volume for `{service} in {city}` queries? → Validate before building
+3. Are NAP details consistent across all listings? → Audit before publishing
+4. Does each location page have 300+ words of unique content? → Avoid thin pages
+5. Is LocalBusiness schema valid per Google's Rich Results Test? → Test before deploy

package/skills/wp-programmatic-seo/references/product-seo.md

@@ -0,0 +1,147 @@
+# Product Programmatic SEO
+
+Use this file when generating product variant pages, comparison pages, or category landing pages at scale using WooCommerce product data as the SEO content source.
+
+## Product Variant Pages
+
+Generate pages for every meaningful combination of product attributes:
+
+| Attribute Combination | URL Pattern | Example |
+|----------------------|-------------|---------|
+| Product + Size | `/{product}/{size}` | `/running-shoes/size-10` |
+| Product + Color | `/{product}/{color}` | `/t-shirt/navy-blue` |
+| Product + Size + Color | `/{product}/{size}-{color}` | `/dress/medium-red` |
+| Brand + Category | `/{brand}/{category}` | `/nike/running-shoes` |
+| Product + Material | `/{product}/{material}` | `/jacket/leather` |
+
+**When to create variant pages (vs single page with selector):**
+- Each variant has unique search volume (e.g., "red Nike Air Max")
+- Variants differ significantly in content/images
+- Variants target different buyer intents
+
+**When NOT to create variant pages:**
+- Variants are trivial (only size differs, no unique content)
+- Low search volume for specific combinations
+- Risk of thin content / doorway pages
+
+## WooCommerce Product Data as SEO Source
+
+Pull product attributes via WooCommerce REST API:
+
+```bash
+# List products with attributes — use wc_list_products MCP tool
+wc_list_products(per_page=100, status="publish")
+
+# Get product variations
+wc_list_product_variations(product_id=123)
+```
+
+**Useful WooCommerce fields for programmatic pages:**
+- `name`, `description`, `short_description` → page content
+- `attributes` → variant dimensions (color, size, material)
+- `categories`, `tags` → taxonomy clustering
+- `regular_price`, `sale_price` → pricing content
+- `average_rating`, `rating_count` → social proof
+- `images` → product visuals
+- `stock_status` → availability signals
+
+## Comparison Pages
+
+Generate "Product A vs Product B" pages from product pairs:
+
+**Template structure:**
+```
+Title: "{Product A} vs {Product B} — Which Is Better?"
+H1:    "{Product A} vs {Product B}"
+
+Comparison table:
+| Feature       | Product A     | Product B     |
+|---------------|---------------|---------------|
+| Price         | {price_a}     | {price_b}     |
+| Rating        | {rating_a}/5  | {rating_b}/5  |
+| {attribute_1} | {value_a}     | {value_b}     |
+
+Summary: "Choose {Product A} if... Choose {Product B} if..."
+```
+
+**Scale calculation:** N products → N×(N-1)/2 comparison pages. 50 products = 1,225 pages.
+
+**Quality gate:** Only generate comparisons where products share a category and have meaningful differences.
+
+## Category/Tag Landing Pages
+
+Programmatic category pages aggregate products with editorial content:
+
+```
+Title: "Best {Category} in {Year} — Top {count} Picks"
+H1:    "Best {Category}"
+
+Content:
+- Category introduction (100–150 words)
+- Top products grid (from WooCommerce query)
+- Buying guide section (200–300 words, template with dynamic fields)
+- FAQ (3–5 questions from keyword research)
+```
+
+**Implementation:**
+1. Query WooCommerce categories via `wc_list_products(category=ID)`
+2. Sort by `average_rating` or `total_sales` for "top picks"
+3. Generate buying guide from category attributes
+
+## Product Schema Markup
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "{product_name}",
+  "description": "{product_description}",
+  "image": "{image_url}",
+  "brand": {
+    "@type": "Brand",
+    "name": "{brand_name}"
+  },
+  "sku": "{sku}",
+  "offers": {
+    "@type": "Offer",
+    "url": "{page_url}",
+    "priceCurrency": "{currency}",
+    "price": "{price}",
+    "availability": "https://schema.org/{InStock|OutOfStock}",
+    "seller": {
+      "@type": "Organization",
+      "name": "{store_name}"
+    }
+  },
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "{avg_rating}",
+    "reviewCount": "{review_count}"
+  }
+}
+```
+
+## Canonical URL Strategy
+
+Prevent duplicate content across variant and comparison pages:
+
+| Scenario | Canonical Rule |
+|----------|---------------|
+| Color variants with same content | Canonical → parent product page |
+| Size variants with unique content | Self-canonical (each variant is canonical) |
+| Comparison A vs B and B vs A | Canonical → alphabetically first (A vs B) |
+| Category + filtered view | Canonical → unfiltered category page |
+| Paginated category pages | `rel="next"` / `rel="prev"` + canonical to page 1 |
+
+**Implementation in headless frontend:**
+```html
+<link rel="canonical" href="{computed_canonical_url}" />
+```
+
+## Decision Checklist
+
+1. Do product variants have unique search volume? → Yes = variant pages; No = single page
+2. Is comparison data meaningful (shared category, different attributes)? → Yes = comparison pages
+3. Does each generated page have 300+ words of unique content? → Verify template output
+4. Are canonical URLs set correctly to avoid duplicate indexing? → Test with Google URL Inspection
+5. Is Product schema valid? → Test with Rich Results Test

package/skills/wp-programmatic-seo/references/technical-seo.md

@@ -0,0 +1,197 @@
+# Technical SEO for Programmatic Pages
+
+Use this file when managing sitemaps, crawl budget, canonicals, internal linking, and Core Web Vitals for large-scale programmatic page generation.
+
+## XML Sitemap Generation
+
+### Yoast SEO Integration
+
+Yoast auto-generates sitemaps for all public post types:
+- Main sitemap index: `/sitemap_index.xml`
+- Post type sitemaps: `/post_type-sitemap.xml` (paginated at 1000 URLs per file)
+
+**Configure for programmatic CPTs:**
+```php
+// Ensure CPT appears in Yoast sitemap
+register_post_type('location', [
+    'public'       => true,
+    'show_in_rest' => true,
+    // Yoast auto-includes public CPTs in sitemap
+]);
+```
+
+### Rank Math Integration
+
+Rank Math uses similar auto-generation. Configure via:
+- Settings → Sitemap → enable the CPT
+- Pagination: 200 URLs per sitemap file (configurable)
+
+### Dynamic Sitemap Index for 1000s+ Pages
+
+For very large sites, create a custom sitemap index:
+
+```php
+// Custom sitemap for programmatic pages (mu-plugin)
+add_filter('wp_sitemaps_post_types', function ($post_types) {
+    $post_types['location'] = get_post_type_object('location');
+    return $post_types;
+});
+
+// Custom max URLs per sitemap page
+add_filter('wp_sitemaps_max_urls', function () {
+    return 2000; // Default is 2000, reduce if pages are slow to crawl
+});
+```
+
+**Sitemap submission:**
+1. Submit sitemap index URL in Google Search Console
+2. Reference sitemap in `robots.txt`: `Sitemap: https://example.com/sitemap_index.xml`
+3. Monitor "Sitemaps" report in GSC for errors
+
+## Crawl Budget Optimization
+
+Crawl budget = how many pages Googlebot will crawl per session. Critical for 1000s+ pages.
+
+### Pages to Index (doindex)
+
+- Programmatic pages with unique, valuable content (300+ words)
+- Category landing pages with editorial content
+- Comparison pages with meaningful differentiation
+
+### Pages to Noindex
+
+| Page Type | Action | Reason |
+|-----------|--------|--------|
+| Thin variant pages (< 300 words) | `noindex, follow` | Low content value |
+| Paginated archives (page 2+) | `noindex, follow` | Duplicate of page 1 |
+| Faceted navigation results | `noindex` or block via `robots.txt` | Parameter-based duplicates |
+| Internal search results | `noindex` | Dynamic, low SEO value |
+| Tag pages with < 3 posts | `noindex, follow` | Thin taxonomy pages |
+
+### Implementation
+
+```html
+<!-- Noindex via meta tag (headless frontend) -->
+<meta name="robots" content="noindex, follow" />
+
+<!-- Or via X-Robots-Tag HTTP header -->
+X-Robots-Tag: noindex, follow
+```
+
+## Canonical URL Management
+
+### Headless Architecture Canonicals
+
+In headless setups, the canonical must point to the frontend URL, not the WordPress admin URL:
+
+```html
+<!-- Frontend page canonical -->
+<link rel="canonical" href="https://www.example.com/services/miami" />
+
+<!-- NOT the WordPress REST source -->
+<!-- Wrong: https://wp.example.com/wp-json/wp/v2/location/123 -->
+```
+
+**Configuration in headless frontend:**
+```javascript
+// Next.js metadata
+export function generateMetadata({ params }) {
+  return {
+    alternates: {
+      canonical: `https://www.example.com/${params.service}/${params.city}`,
+    },
+  };
+}
+```
+
+### Canonical Rules for Programmatic Pages
+
+| Scenario | Canonical Target |
+|----------|-----------------|
+| Standard programmatic page | Self-canonical |
+| Variant with identical content to parent | Parent product page |
+| Paginated series | Page 1 of the series |
+| HTTP vs HTTPS | HTTPS version |
+| www vs non-www | Preferred domain version |
+| Trailing slash vs no trailing slash | Consistent chosen format |
+
+## robots.txt Configuration
+
+```
+# robots.txt for headless WordPress
+User-agent: *
+Allow: /
+
+# Block WordPress admin (if exposed)
+Disallow: /wp-admin/
+Allow: /wp-admin/admin-ajax.php
+
+# Block faceted navigation / filter parameters
+Disallow: /*?filter=
+Disallow: /*?sort=
+Disallow: /*?page=
+
+# Sitemap reference
+Sitemap: https://www.example.com/sitemap_index.xml
+```
+
+## Internal Linking Strategy
+
+Programmatic pages need structured internal linking for crawlability and authority flow:
+
+### Hub-and-Spoke Model
+
+```
+Category hub page (e.g., /plumbing/)
+  ├── /plumbing/miami
+  ├── /plumbing/orlando
+  ├── /plumbing/tampa
+  └── /plumbing/jacksonville
+```
+
+**Implementation:**
+- Hub page links to all spoke pages (or top N by relevance)
+- Each spoke page links back to hub + 3–5 related spokes
+- Breadcrumbs: Home → Service → City
+
+### Cross-Linking Between Clusters
+
+```
+/plumbing/miami ←→ /electrical/miami    (same city, different service)
+/plumbing/miami ←→ /plumbing/fort-lauderdale  (same service, nearby city)
+```
+
+**Automated linking (template-based):**
+```html
+<!-- Related services in {city} -->
+<h2>Other Services in {city}</h2>
+<ul>
+  {for service in other_services}
+    <li><a href="/{service.slug}/{city.slug}">{service.name} in {city.name}</a></li>
+  {/for}
+</ul>
+```
+
+## Core Web Vitals for Template Pages
+
+| Metric | Target | Programmatic Page Risk |
+|--------|--------|----------------------|
+| LCP | < 2.5s | Large hero images from WP media library |
+| INP | < 200ms | Heavy JS for dynamic content |
+| CLS | < 0.1 | Late-loading images without dimensions |
+
+**Optimizations:**
+1. **LCP:** Preload hero image, use `next/image` or equivalent with width/height
+2. **INP:** Minimize client-side JS; SSG/ISR means most content is pre-rendered
+3. **CLS:** Set explicit `width` and `height` on all images; use CSS `aspect-ratio`
+4. **Font loading:** `font-display: swap` for web fonts
+5. **Third-party scripts:** Defer analytics/tracking below the fold
+
+## Decision Checklist
+
+1. Is the sitemap index submitted and error-free in GSC? → Monitor weekly
+2. Are thin pages noindexed to preserve crawl budget? → Audit monthly
+3. Do all programmatic pages have correct self-canonicals? → Verify in bulk
+4. Is robots.txt blocking faceted navigation and parameters? → Test with robots.txt tester
+5. Does every page link to its hub and 3–5 related pages? → Template includes these links
+6. Are Core Web Vitals passing for template pages? → Test with PageSpeed Insights on sample

package/skills/wp-programmatic-seo/references/template-architecture.md

@@ -0,0 +1,125 @@
+# Template Architecture
+
+Use this file when designing page templates for headless WordPress programmatic SEO — custom post types as data source, URL structure, ISR/SSG configuration, and bulk content creation.
+
+## Custom Post Types as Data Source
+
+WordPress CPTs are the ideal data backbone for programmatic pages:
+
+```php
+// Register a CPT for programmatic content (e.g., locations)
+register_post_type('location', [
+    'public'       => true,
+    'show_in_rest' => true,  // Required for headless access
+    'supports'     => ['title', 'editor', 'custom-fields', 'thumbnail'],
+    'rewrite'      => ['slug' => 'locations'],
+    'has_archive'  => true,
+]);
+```
+
+**Required CPT fields for programmatic SEO:**
+- Title → H1 and `<title>` tag
+- Custom fields → template variables (city, service, price, etc.)
+- Taxonomy → category/tag for clustering
+- Featured image → OG image
+
+## URL Structure Design
+
+| Pattern | Example | Use Case |
+|---------|---------|----------|
+| `/{service}/{city}` | `/plumbing/miami` | Service-area pages |
+| `/{product}/{variant}` | `/shoes/red-size-10` | Product variants |
+| `/{category}/{item}` | `/restaurants/joes-pizza` | Directory listings |
+| `/{brand}/{model}/{year}` | `/toyota/camry/2024` | Multi-attribute pages |
+| `/{topic}/{subtopic}` | `/learn/react-hooks` | Educational content |
+
+**URL rules:**
+- Lowercase, hyphenated slugs
+- Max 3 levels deep (SEO best practice)
+- Include primary keyword in first path segment
+- Avoid query parameters for indexable pages
+
+## ISR Configuration (Headless Frontend)
+
+### Next.js (App Router)
+
+```javascript
+// app/[service]/[city]/page.js
+export async function generateStaticParams() {
+  const res = await fetch(`${WP_API}/wp/v2/location?per_page=100`);
+  const locations = await res.json();
+  return locations.map((loc) => ({
+    service: loc.acf.service_slug,
+    city: loc.slug,
+  }));
+}
+
+export const revalidate = 3600; // ISR: revalidate every hour
+```
+
+### Nuxt
+
+```javascript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/services/**': { isr: 3600 },
+  },
+});
+```
+
+### Astro
+
+```javascript
+// astro.config.mjs — hybrid mode for ISR-like behavior
+export default defineConfig({
+  output: 'hybrid',
+  adapter: node({ mode: 'standalone' }),
+});
+```
+
+**Revalidate intervals by content type:**
+
+| Content Type | Interval | Reason |
+|-------------|----------|--------|
+| Location pages | 3600s (1h) | Rarely change |
+| Product pages | 900s (15m) | Price/stock updates |
+| Blog/guides | 86400s (24h) | Stable content |
+| Comparison pages | 3600s (1h) | Data-driven, periodic |
+
+## Template Variables
+
+A programmatic page template maps CPT fields to HTML:
+
+```
+Title:       "{service_name} in {city_name} — {brand}"
+Meta desc:   "Professional {service_name} in {city_name}. {unique_selling_point}."
+H1:          "{service_name} in {city_name}"
+Body:        Template paragraph using {city_population}, {service_details}, {local_info}
+Schema:      LocalBusiness JSON-LD with {name}, {address}, {phone}, {geo}
+```
+
+**Anti-pattern:** Avoid thin content — each page must have enough unique value to justify indexing. Minimum 300 words of meaningful, varied content per page.
+
+## Bulk Content Creation Workflow
+
+1. **Prepare data:** CSV or JSON with one row per page (city, service, attributes)
+2. **Create CPT entries:** Loop via WordPress REST API:
+
+```bash
+# Using wp-rest-bridge create_content tool
+for each row in data:
+  create_content(type="location", title=row.title, content=row.body, meta=row.fields)
+```
+
+3. **Assign taxonomies:** Tag each entry with relevant terms for clustering
+4. **Generate frontend paths:** Run `generateStaticParams` or equivalent build step
+5. **Verify:** Spot-check 5–10 pages for content quality and schema validity
+
+## Decision Checklist
+
+1. Is the data structured and repeatable? → Yes = proceed with CPT
+2. Will each page have unique, valuable content? → Yes = proceed; No = consolidate
+3. Is the URL pattern SEO-friendly and max 3 levels? → Verify before building
+4. Is ISR/SSG configured with appropriate revalidation? → Match to content freshness
+5. Are sitemaps generated for all programmatic pages? → See `technical-seo.md`