claude-plugin-wordpress-manager 2.2.1 → 2.3.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "wordpress-manager",
-  "version": "2.2.1",
-  "description": "Unified WordPress management plugin for Claude Code. Orchestrates Hostinger MCP (infrastructure), WP REST API bridge (85 tools incl. WooCommerce + Multisite + Webhooks), and WordPress.com MCP (hosted sites) with 11 specialized agents, 30 skills, and security hooks. Includes fleet monitoring, content repurposing, webhook propagation, site monitoring (uptime, performance baseline, security scanning, content integrity, alerting), CI/CD pipeline automation (GitHub Actions, GitLab CI, Bitbucket), WordPress Multisite network management, WooCommerce store management, local dev environment support, development, testing, security, i18n, accessibility, headless, and operations.",
+  "version": "2.3.0",
+  "description": "Unified WordPress management plugin for Claude Code. Orchestrates Hostinger MCP (infrastructure), WP REST API bridge (85 tools incl. WooCommerce + Multisite + Webhooks), and WordPress.com MCP (hosted sites) with 11 specialized agents, 33 skills, and security hooks. Includes programmatic SEO, content-commerce attribution, multi-language network, fleet monitoring, content repurposing, webhook propagation, site monitoring (uptime, performance baseline, security scanning, content integrity, alerting), CI/CD pipeline automation (GitHub Actions, GitLab CI, Bitbucket), WordPress Multisite network management, WooCommerce store management, local dev environment support, development, testing, security, i18n, accessibility, headless, and operations.",
   "author": {
     "name": "vinmor",
     "email": "morreale.v@gmail.com"

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to the WordPress Manager plugin for Claude Code.
 
+## [2.3.0] - 2026-02-28
+
+### Added
+- **Programmatic SEO skill** (`wp-programmatic-seo`) — template-based scalable page generation via headless WordPress + multisite
+  - 5 reference files: `template-architecture.md`, `location-seo.md`, `product-seo.md`, `data-sources.md`, `technical-seo.md`
+  - Detection script: `programmatic_seo_inspect.mjs` (headless frontend, SEO plugins, CPTs, WPGraphQL)
+  - Agent updated: Programmatic SEO Workflow + example in `wp-content-strategist`
+- **Content-Commerce Attribution skill** (`wp-content-attribution`) — link WooCommerce sales data to content that drives conversions
+  - 5 reference files: `utm-tracking-setup.md`, `conversion-funnels.md`, `attribution-models.md`, `roi-calculation.md`, `reporting-dashboards.md`
+  - Detection script: `attribution_inspect.mjs` (WooCommerce, analytics plugins, UTM tracking, order meta)
+  - Agent updated: Content Attribution Workflow + example in `wp-ecommerce-manager`
+- **Multi-Language Network skill** (`wp-multilang-network`) — multisite multi-language orchestration with hreflang and content sync
+  - 5 reference files: `network-architecture.md`, `hreflang-config.md`, `content-sync.md`, `language-routing.md`, `seo-international.md`
+  - Detection script: `multilang_inspect.mjs` (multisite status, multilingual plugins, language patterns, hreflang)
+  - Agent updated: Multi-Language Network Management + example in `wp-site-manager`
+
+### Changed
+- Router decision-tree.md upgraded to v10 with programmatic SEO, content attribution, and multi-language network keywords and routing
+- Cross-references added: `wp-headless` → wp-programmatic-seo, `wp-woocommerce` → wp-content-attribution, `wp-content` → wp-content-attribution, `wp-multisite` → wp-multilang-network, `wp-i18n` → wp-multilang-network
+- Plugin now has 33 skills, 11 agents, and 85 MCP tools
+
 ## [2.2.1] - 2026-02-28
 
 ### Changed

package/agents/wp-content-strategist.md

@@ -31,6 +31,13 @@ description: |
   assistant: "I'll use the wp-content-strategist agent to extract key insights from your posts and generate platform-specific social content."
   <commentary>Content repurposing requires selecting source content and applying platform templates.</commentary>
   </example>
+
+  <example>
+  Context: User wants to generate hundreds of location-based landing pages.
+  user: "Generate 200 city pages for our plumbing service"
+  assistant: "I'll use the wp-content-strategist agent to design the template, set up the data source, and bulk-generate the city pages."
+  <commentary>Programmatic SEO at scale requires structured data, URL design, and bulk content creation via REST API.</commentary>
+  </example>
 model: inherit
 tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
 ---
@@ -176,6 +183,23 @@ When repurposing existing WordPress content into multi-channel formats:
 
 See the `wp-content-repurposing` skill for detailed templates and platform specifications.
 
+## Programmatic SEO Workflow
+
+When generating large-scale pages from structured data (city pages, product variants, comparison pages):
+
+1. **Assess data source**: Use `discover_content_types` to find what structured data exists (products, locations, categories). Run `programmatic_seo_inspect.mjs` for readiness assessment.
+2. **Design URL pattern**: Define the template — `/{service}/{city}` or `/{product}/{variant}`. Keep to max 3 levels, include primary keyword in first path segment.
+3. **Create CPT or taxonomy**: If no suitable CPT exists, create one in WordPress with `show_in_rest: true` for headless access. Define custom fields for template variables.
+4. **Build page template**: Map CPT fields to page elements — title, meta description, H1, body sections, schema markup. Ensure 300+ words of unique content per page.
+5. **Generate content in bulk**: Loop via `create_content` MCP tool:
+   - Create as `status: "draft"` first for review
+   - Process in batches of 10, report progress
+   - Assign taxonomies via `assign_terms_to_content`
+6. **Configure headless frontend**: Reference `wp-programmatic-seo` skill for ISR/SSG setup (Next.js `revalidate`, Nuxt `routeRules`, Astro hybrid mode).
+7. **Submit sitemap**: Verify XML sitemap includes all programmatic pages, submit to Google Search Console.
+
+See the `wp-programmatic-seo` skill for reference files on template architecture, location SEO, product SEO, data sources, and technical SEO.
+
 ## Multilingual Content
 
 When creating content for multilingual sites:
@@ -194,3 +218,4 @@ When creating content for multilingual sites:
 - **`wp-content` skill** — content lifecycle management, editorial workflows
 - **`wp-i18n` skill** — internationalization and localization procedures
 - **`wp-content-repurposing` skill** — content transformation for multi-channel distribution
+- **`wp-programmatic-seo` skill** — scalable page generation from structured data (city pages, product variants, comparison pages)

package/agents/wp-ecommerce-manager.md

@@ -26,6 +26,13 @@ description: |
   <commentary>Sales analytics combining multiple report endpoints requires the WooCommerce agent.</commentary>
   </example>
 
+  <example>
+  Context: User wants to know which blog posts are driving sales.
+  user: "Which blog posts are driving the most sales?"
+  assistant: "I'll use the wp-ecommerce-manager agent to analyze order attribution data and identify top converting content."
+  <commentary>Content-commerce attribution requires correlating WooCommerce order UTM meta with content data.</commentary>
+  </example>
+
 model: inherit
 tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
 ---
@@ -93,6 +100,21 @@ For cross-referencing with WordPress content:
 3. Shipping: `wc_list_shipping_zones` (verify zone coverage)
 4. Tax: `wc_get_tax_classes` (verify tax configuration)
 
+### Content Attribution Workflow
+
+When analyzing which content drives WooCommerce sales:
+
+1. **Verify setup**: Run `attribution_inspect.mjs` to check WooCommerce + content + UTM tracking readiness
+2. **Check UTM tracking**: Is the UTM capture mu-plugin installed? If not, guide setup from `wp-content-attribution` skill → `references/utm-tracking-setup.md`
+3. **Pull sales data**: `wc_get_sales_report` for the reporting period (default: last 30 days)
+4. **Pull order details**: `wc_list_orders` with `status=completed` — check `_last_utm_campaign` and `_first_utm_campaign` meta on each order
+5. **Pull content data**: `list_content` for the same period to map campaign slugs back to post titles
+6. **Correlate**: Match order UTM campaign values with content piece slugs; aggregate revenue per content piece
+7. **Apply attribution model**: Default to last-touch (`_last_utm_campaign`); reference `wp-content-attribution` skill for other models
+8. **Generate attribution report**: Top converting content pieces, revenue by content category, CAC by source, recommendations
+
+See the `wp-content-attribution` skill for reference files on UTM setup, attribution models, ROI calculation, and reporting dashboards.
+
 ## Report Format
 
 ```
@@ -134,3 +156,4 @@ For cross-referencing with WordPress content:
 - `wp-deploy` — Deploy store changes to production
 - `wp-backup` — Backup store database before bulk operations
 - `wp-audit` — Security and performance audit for WC stores
+- `wp-content-attribution` — Content-commerce attribution, UTM tracking, ROI calculation

package/agents/wp-site-manager.md

@@ -24,6 +24,13 @@ description: |
   assistant: "I'll use the wp-site-manager agent to handle multi-site operations."
   <commentary>Multi-site coordination is a core capability of this agent.</commentary>
   </example>
+
+  <example>
+  Context: User wants to set up a multilingual multisite network.
+  user: "Set up Italian and Spanish versions of our site"
+  assistant: "I'll use the wp-site-manager agent to create language-specific sub-sites and configure the multi-language network."
+  <commentary>Multi-language network setup requires creating sub-sites, configuring hreflang, and establishing content sync — all multisite operations.</commentary>
+  </example>
 model: inherit
 tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
 ---
@@ -127,6 +134,20 @@ For WordPress Multisite networks (sites with `is_multisite: true` in WP_SITES_CO
 - ALWAYS confirm before network-activating plugins (affects ALL sites)
 - Announce which network you're operating on when multiple multisite networks are configured
 
+### Multi-Language Network Management
+
+When setting up or managing a multi-language WordPress Multisite network:
+
+1. **Assess current network**: Use `ms_list_sites` to list existing sub-sites. Run `multilang_inspect.mjs` for readiness assessment (multisite status, multilingual plugin, language patterns, hreflang).
+2. **Create language sub-sites**: Use `ms_create_site` for each target language. Use ISO 639-1 codes as slugs (e.g., `/it/`, `/de/`, `/fr/`). Title format: `{Brand} - {Language Name}`.
+3. **Configure multilingual plugin**: Network-activate the chosen plugin (WPML, Polylang, or MultilingualPress) via `ms_network_activate_plugin`. Assign language to each sub-site in plugin settings.
+4. **Set up hreflang**: If using MultilingualPress or WPML, hreflang is auto-generated. Otherwise, install the hreflang mu-plugin from `wp-multilang-network` skill → `references/hreflang-config.md`.
+5. **Establish content sync workflow**: Define whether content is manually replicated, semi-auto (plugin-assisted), or fully synced. See `wp-multilang-network` skill → `references/content-sync.md`.
+6. **Configure language routing**: Set up language switcher widget and optional browser detection redirect. See `references/language-routing.md`.
+7. **Verify international SEO**: Check hreflang reciprocal links, per-language sitemaps, GSC properties per language. See `references/seo-international.md`.
+
+See the `wp-multilang-network` skill for detailed reference files on network architecture, hreflang, content sync, language routing, and international SEO.
+
 ### Safety Rules
 - NEVER delete content without explicit user confirmation
 - NEVER deactivate plugins without listing dependencies first
@@ -150,3 +171,8 @@ For domain-specific tasks, delegate to specialized agents:
 | Multisite network management | `wp-site-manager` (this agent) | Sub-sites, network plugins, Super Admin — see section above |
 | CI/CD pipeline setup and troubleshooting | `wp-cicd-engineer` | GitHub Actions, GitLab CI, Bitbucket, quality gates |
 | Site monitoring and health reports | `wp-monitoring-agent` | Uptime, performance trends, security scanning, content integrity |
+
+## Related Skills
+
+- **`wp-multisite` skill** — multisite network management with 10 MCP tools
+- **`wp-multilang-network` skill** — multi-language network orchestration (hreflang, content sync, international SEO)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-plugin-wordpress-manager",
-  "version": "2.2.1",
-  "description": "Unified WordPress management and development plugin for Claude Code. Orchestrates Hostinger MCP, WP REST API bridge (85 tools incl. 30 WooCommerce + 10 Multisite + 4 Webhooks), and WordPress.com MCP with 30 skills, 11 agents, and security hooks. v2.2.0 adds fleet monitoring, content repurposing skill, and webhook propagation (WooCommerce webhook MCP tools + mu-plugin patterns).",
+  "version": "2.3.0",
+  "description": "Unified WordPress management and development plugin for Claude Code. Orchestrates Hostinger MCP, WP REST API bridge (85 tools incl. 30 WooCommerce + 10 Multisite + 4 Webhooks), and WordPress.com MCP with 33 skills, 11 agents, and security hooks. v2.3.0 adds programmatic SEO, content-commerce attribution, and multi-language network skills.",
   "author": {
     "name": "vinmor",
     "email": "morreale.v@gmail.com"
@@ -36,7 +36,12 @@
     "health-check",
     "webhook",
     "content-repurposing",
-    "fleet-monitoring"
+    "fleet-monitoring",
+    "programmatic-seo",
+    "attribution",
+    "multilingual",
+    "hreflang",
+    "international-seo"
   ],
   "repository": {
     "type": "git",

package/skills/wordpress-router/references/decision-tree.md

@@ -1,4 +1,4 @@
-# Router decision tree (v9 — development + local environment + operations + multisite + CI/CD + monitoring + webhooks + content repurposing)
+# Router decision tree (v10 — development + local environment + operations + multisite + CI/CD + monitoring + webhooks + content repurposing + programmatic SEO + content attribution + multi-language network)
 
 This routing guide covers WordPress **development**, **local environment**, and **operations** workflows.
 
@@ -14,7 +14,7 @@ Keywords that indicate **local environment**:
 local site, Studio, LocalWP, Local by Flywheel, wp-env, local WordPress, start site, stop site, create local site, local development, symlink plugin, local database, switch PHP version, localhost, local preview, detect environment, WASM, SQLite local
 
 Keywords that indicate **operations**:
-deploy, push to production, audit, security check, backup, restore, migrate, move site, create post, manage content, site status, check plugins, performance check, SEO audit, WooCommerce, prodotto, ordine, coupon, negozio, catalogo, inventario, vendite, carrello, multisite, network, sub-site, sub-sito, domain mapping, super admin, network activate, monitor, uptime, health report, trend, scansione periodica, alerting, performance baseline, fleet, all sites, network health, cross-site, webhook, outbound notification, event propagation, Zapier, content sync, repurpose content, social posts from blog, content atomization, newsletter from posts, content distribution
+deploy, push to production, audit, security check, backup, restore, migrate, move site, create post, manage content, site status, check plugins, performance check, SEO audit, WooCommerce, prodotto, ordine, coupon, negozio, catalogo, inventario, vendite, carrello, multisite, network, sub-site, sub-sito, domain mapping, super admin, network activate, monitor, uptime, health report, trend, scansione periodica, alerting, performance baseline, fleet, all sites, network health, cross-site, webhook, outbound notification, event propagation, Zapier, content sync, repurpose content, social posts from blog, content atomization, newsletter from posts, content distribution, programmatic SEO, template pages, city pages, location pages, bulk page generation, scalable landing pages, content ROI, attribution, which content drives sales, conversion tracking, UTM tracking, revenue per post, multilingual, multi-language, hreflang, international SEO, translate site, language sites, localize content
 
 Keywords that indicate **development**:
 create block, block.json, theme.json, register_rest_route, plugin development, hooks, PHPStan, build, test, scaffold, i18n, translation, accessibility, a11y, headless, decoupled, WPGraphQL, CI, CD, pipeline, GitHub Actions, GitLab CI, deploy automatico, workflow, quality gate
@@ -98,6 +98,12 @@ Priority: `gutenberg` > `wp-core` > `wp-site` > `wp-block-theme` > `wp-block-plu
   → `wp-webhooks` skill + `wp-site-manager` agent
 - **Repurpose content / social posts from blog / newsletter from content / atomize / content distribution / turn blog into social**
   → `wp-content-repurposing` skill + `wp-content-strategist` agent
+- **Programmatic SEO / template pages / city pages / bulk page generation / scalable landing pages / location-based SEO / product variant pages**
+  → `wp-programmatic-seo` skill + `wp-content-strategist` agent
+- **Content attribution / ROI / conversion tracking / UTM / revenue per post / which content drives sales**
+  → `wp-content-attribution` skill + `wp-ecommerce-manager` agent
+- **Multi-language / multilingual / hreflang / international SEO / language sites / translate network**
+  → `wp-multilang-network` skill + `wp-site-manager` agent
 
 ## Step 2c: route by local environment intent (keywords)
 

package/skills/wp-content/SKILL.md

@@ -104,3 +104,4 @@ Tool: assign_terms_to_content — assign terms to content
 
 ### Related Skills
 - **`wp-content-repurposing`** — transform existing content for social media, email, and multi-channel distribution
+- **`wp-content-attribution`** — measure which content drives WooCommerce sales (UTM tracking, attribution models, ROI)

package/skills/wp-content-attribution/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: wp-content-attribution
+description: |
+  This skill should be used when the user asks to "track content ROI",
+  "attribute sales to content", "measure content performance", "conversion tracking",
+  "UTM tracking setup", "which content drives sales", "content attribution",
+  "revenue per post", "customer acquisition source", "marketing attribution",
+  or mentions connecting WordPress content metrics with WooCommerce sales data.
+version: 1.0.0
+---
+
+## Overview
+
+Content-Commerce Attribution measures which WordPress content pieces drive WooCommerce conversions, enabling data-driven content strategy. By linking UTM-tracked traffic to order data, you can calculate ROI per content piece — answering "which blog posts actually generate revenue?"
+
+This skill orchestrates existing MCP tools — WooCommerce reports, content CRUD, order management — into attribution workflows. No new tools or custom plugins are required; UTM capture uses lightweight mu-plugin patterns.
+
+## When to Use
+
+- User has a WooCommerce store plus blog/content and wants to understand content ROI
+- "Which of my blog posts are driving the most sales?"
+- "How do I track which content leads to purchases?"
+- "Set up UTM tracking for my WooCommerce store"
+- "Calculate revenue per blog post"
+- "Build a content attribution dashboard"
+- "What's my customer acquisition cost by content type?"
+
+## Attribution vs Analytics
+
+| Aspect | Attribution | Analytics |
+|--------|------------|-----------|
+| Measures | Contribution to conversion | Traffic and engagement |
+| Answer | "This post generated $5,000 in revenue" | "This post got 10,000 visits" |
+| Data source | Order meta + UTM params | Page views + sessions |
+| Granularity | Revenue per content piece | Visitors per content piece |
+| Action | Invest more in high-ROI content | Invest in high-traffic topics |
+
+## Prerequisites / Detection
+
+```bash
+node skills/wp-content-attribution/scripts/attribution_inspect.mjs --cwd=/path/to/wordpress
+```
+
+The script checks WooCommerce presence, analytics plugins, UTM tracking setup, content/product volume ratio, and existing order meta with source fields.
+
+## Content Attribution Operations Decision Tree
+
+1. **What attribution task?**
+
+   - "UTM tracking" / "campaign tracking" / "source tracking"
+     → **UTM Setup** — Read: `references/utm-tracking-setup.md`
+
+   - "conversion funnel" / "customer journey" / "touchpoints"
+     → **Funnel Analysis** — Read: `references/conversion-funnels.md`
+
+   - "attribution model" / "first touch" / "last touch" / "multi-touch"
+     → **Attribution Models** — Read: `references/attribution-models.md`
+
+   - "content ROI" / "revenue per post" / "cost per acquisition"
+     → **ROI Calculation** — Read: `references/roi-calculation.md`
+
+   - "dashboard" / "report" / "analytics setup"
+     → **Reporting** — Read: `references/reporting-dashboards.md`
+
+2. **Common workflow (first-time setup):**
+   1. Verify WooCommerce + content setup (run `attribution_inspect.mjs`)
+   2. Install UTM capture mu-plugin (see `utm-tracking-setup.md`)
+   3. Tag internal links from content → product pages with UTM parameters
+   4. Wait for data accumulation (minimum 2–4 weeks)
+   5. Pull sales data: `wc_get_sales_report` for period
+   6. Pull content data: `list_content` for same period
+   7. Correlate: match order UTM sources with content pieces
+   8. Apply attribution model (default: last-touch)
+   9. Generate attribution report with top converting content
+
+## Recommended Agent
+
+`wp-ecommerce-manager` — handles WooCommerce data, sales reports, and order analysis with attribution context.
+
+## Additional Resources
+
+### Reference Files
+
+| File | Description |
+|------|-------------|
+| **`references/utm-tracking-setup.md`** | UTM parameter design, mu-plugin for capture, naming conventions |
+| **`references/conversion-funnels.md`** | Funnel stages, drop-off analysis, cart abandonment metrics |
+| **`references/attribution-models.md`** | First-touch, last-touch, linear, time-decay, position-based models |
+| **`references/roi-calculation.md`** | Revenue per post, content ROI formula, CAC, LTV by source |
+| **`references/reporting-dashboards.md`** | GA4 integration, MonsterInsights setup, dashboard KPIs |
+
+### Related Skills
+
+- `wp-woocommerce` — WooCommerce store management and reporting tools
+- `wp-content` — content management and editorial workflows
+- `wp-monitoring` — ongoing site performance and health tracking
+- `wp-content-repurposing` — transform high-ROI content into multi-channel formats

package/skills/wp-content-attribution/references/attribution-models.md

@@ -0,0 +1,189 @@
+# Attribution Models
+
+Use this file when selecting and implementing an attribution model — first-touch, last-touch, linear, time-decay, and position-based approaches for WordPress + WooCommerce content attribution.
+
+## Model Overview
+
+| Model | Credit Distribution | Best For | Complexity |
+|-------|-------------------|----------|------------|
+| **First-Touch** | 100% to first interaction | Brand awareness measurement | Low |
+| **Last-Touch** | 100% to last interaction before purchase | Direct conversion analysis | Low |
+| **Linear** | Equal across all touchpoints | Balanced view of journey | Medium |
+| **Time-Decay** | More to recent touchpoints | Short sales cycles | Medium |
+| **Position-Based (U-shaped)** | 40% first, 40% last, 20% middle | Full journey with key moments | High |
+
+## First-Touch Attribution
+
+Credit goes entirely to the first content interaction that brought the customer.
+
+**Logic:**
+```
+Customer journey: Blog Post A → Product Page → Blog Post B → Purchase
+Attribution:      Blog Post A = 100%
+```
+
+**WordPress implementation:**
+- Uses the `_first_utm_source` and `_first_utm_campaign` order meta fields
+- Captured via the first-visit cookie in the UTM mu-plugin
+
+**When to use:**
+- You want to understand which content attracts new customers
+- Evaluating top-of-funnel content effectiveness
+- Measuring brand awareness investment ROI
+
+**Limitation:** Ignores all subsequent interactions that nurtured the conversion.
+
+## Last-Touch Attribution
+
+Credit goes entirely to the last content interaction before purchase.
+
+**Logic:**
+```
+Customer journey: Blog Post A → Product Page → Blog Post B → Purchase
+Attribution:      Blog Post B = 100%
+```
+
+**WordPress implementation:**
+- Uses the `_last_utm_source` and `_last_utm_campaign` order meta fields
+- Captured via the always-updated last-touch cookie
+
+**When to use:**
+- Default starting model (simplest, most actionable)
+- Identifying content that directly triggers purchases
+- Short sales cycles where one touchpoint dominates
+
+**Limitation:** Ignores the content that initially attracted the customer.
+
+## Linear Attribution
+
+Equal credit distributed across all touchpoints in the journey.
+
+**Logic:**
+```
+Customer journey: Blog Post A → Product Page → Blog Post B → Purchase
+Attribution:      Blog Post A = 33.3%, Product Page = 33.3%, Blog Post B = 33.3%
+```
+
+**WordPress implementation:**
+Requires tracking all touchpoints, not just first and last. Options:
+1. **Session tracking:** Store each page view with UTM in a user session log (more complex mu-plugin)
+2. **GA4 integration:** Use Google Analytics 4's exploration reports for multi-touch paths
+3. **Simplified approach:** Split credit between first-touch and last-touch (50/50)
+
+**When to use:**
+- All content in the journey contributes equally
+- Long sales cycles with many touchpoints
+- Content team needs validation that middle-of-funnel content matters
+
+**Limitation:** Overvalues low-impact touchpoints (e.g., accidental page views).
+
+## Time-Decay Attribution
+
+More credit to touchpoints closer in time to the conversion.
+
+**Logic (example decay: 7-day half-life):**
+```
+Day 1:  Blog Post A (30 days before purchase) = 6%
+Day 15: Product Page (15 days before)         = 18%
+Day 25: Blog Post B (5 days before)           = 31%
+Day 29: Email Link (1 day before)             = 45%
+```
+
+**Formula:**
+```
+Credit = 2^(-(time_before_purchase / half_life))
+Normalize all credits to sum to 100%
+```
+
+**When to use:**
+- Sales cycle is short (< 30 days)
+- Recent interactions are more influential than early ones
+- Evaluating promotional/seasonal content effectiveness
+
+**Limitation:** Undervalues brand awareness content that starts the journey.
+
+## Position-Based (U-shaped) Attribution
+
+40% to first touch, 40% to last touch, 20% distributed across middle touchpoints.
+
+**Logic:**
+```
+Customer journey: Blog Post A → Product Page → Comparison → Blog Post B → Purchase
+Attribution:      Blog Post A = 40%, Product Page = 10%, Comparison = 10%, Blog Post B = 40%
+```
+
+**When to use:**
+- Both acquisition (first touch) and conversion (last touch) are strategically important
+- Multi-step customer journeys with clear awareness and decision phases
+- Most balanced model for content strategy decisions
+
+**Limitation:** Requires full journey tracking; arbitrary 40/40/20 split.
+
+## Choosing the Right Model
+
+```
+Start here:
+    │
+    ├─ "I just need something simple to start"
+    │   → Last-Touch Attribution
+    │
+    ├─ "I want to know what content attracts new customers"
+    │   → First-Touch Attribution
+    │
+    ├─ "My sales cycle is short (< 7 days)"
+    │   → Last-Touch Attribution
+    │
+    ├─ "My sales cycle is medium (7-30 days)"
+    │   → Time-Decay Attribution (7-day half-life)
+    │
+    ├─ "My sales cycle is long (30+ days, many touchpoints)"
+    │   → Position-Based (U-shaped)
+    │
+    └─ "I want to validate all content stages equally"
+        → Linear Attribution
+```
+
+## WordPress-Specific Implementation
+
+### Building Attribution from Order Meta
+
+With the UTM mu-plugin capturing first-touch and last-touch data:
+
+```bash
+# Pull orders with attribution data
+wc_list_orders(status="completed", per_page=100)
+
+# For each order, check meta fields:
+# _first_utm_source, _first_utm_campaign → first-touch attribution
+# _last_utm_source, _last_utm_campaign   → last-touch attribution
+# _landing_page                          → first page visited
+```
+
+### Attribution Report Query
+
+```
+For each unique utm_campaign value in completed orders:
+  1. Count orders with this campaign (first-touch)
+  2. Count orders with this campaign (last-touch)
+  3. Sum revenue for each
+  4. Map campaign name back to content piece (campaign = post slug)
+  5. Rank by revenue
+```
+
+### Simplified Multi-Touch (50/50 First/Last)
+
+When full journey tracking is not available, split attribution between first and last touch:
+
+```
+Revenue per content piece =
+  (orders where _first_utm_campaign = post_slug × order_total × 0.5) +
+  (orders where _last_utm_campaign = post_slug × order_total × 0.5)
+```
+
+## Decision Checklist
+
+1. What is the average sales cycle length? → Short = last-touch; Long = position-based
+2. Is full journey tracking available (all touchpoints)? → No = use first/last touch only
+3. Is the goal to optimize acquisition or conversion content? → Acquisition = first-touch; Conversion = last-touch
+4. Does the team need a simple, actionable model first? → Start with last-touch, evolve later
+5. Are UTM cookies capturing first and last touch? → Verify mu-plugin is installed

package/skills/wp-content-attribution/references/conversion-funnels.md

@@ -0,0 +1,137 @@
+# Conversion Funnels
+
+Use this file when analyzing the content-to-commerce funnel — mapping funnel stages, measuring drop-off, and correlating WooCommerce events with content interactions.
+
+## Content-to-Commerce Funnel Stages
+
+```
+Awareness → Consideration → Decision → Purchase → Retention
+   │              │              │           │           │
+   Blog post      Product page   Cart        Checkout    Re-order
+   Social share   Comparison     Wishlist    Payment     Review
+   SEO landing    Category page  Pricing     Confirm     Referral
+```
+
+### Stage Definitions
+
+| Stage | User Intent | Content Type | WooCommerce Event |
+|-------|------------|--------------|-------------------|
+| **Awareness** | "I have a problem" | Blog posts, guides, educational content | Page view (no WC interaction) |
+| **Consideration** | "What are my options?" | Product pages, comparisons, reviews | Product view, add to wishlist |
+| **Decision** | "I'm choosing this one" | Product detail, pricing, testimonials | Add to cart |
+| **Purchase** | "I'm buying now" | Cart, checkout | Checkout initiated → Order placed |
+| **Retention** | "I'll come back" | Thank-you page, follow-up emails | Re-order, review submitted |
+
+## Funnel Metrics per Stage
+
+| Metric | Formula | Target | Data Source |
+|--------|---------|--------|-------------|
+| **Awareness rate** | Unique blog visitors / Total visitors | > 40% | Google Analytics |
+| **Content→Product rate** | Product page views from blog / Blog page views | > 5% | UTM tracking |
+| **Add-to-cart rate** | Add-to-cart events / Product page views | > 8% | WooCommerce analytics |
+| **Cart→Checkout rate** | Checkout initiated / Add-to-cart events | > 50% | WooCommerce analytics |
+| **Checkout conversion** | Orders placed / Checkout initiated | > 60% | `wc_get_sales_report` |
+| **Overall content→sale** | Orders from blog / Blog visitors | > 0.5% | UTM + order correlation |
+
+## WordPress Content Mapping to Funnel Stages
+
+### Awareness Content (Top of Funnel)
+
+- **Blog posts** — educational, informational, SEO-targeted
+- **Guides/tutorials** — how-to content solving user problems
+- **Infographics/media** — shareable, high-reach content
+- **SEO landing pages** — targeting informational keywords
+
+Query awareness content:
+```bash
+# List recent blog posts (awareness stage content)
+list_content(type="post", status="publish", per_page=50, orderby="date")
+```
+
+### Consideration Content (Middle of Funnel)
+
+- **Product pages** — detailed product information
+- **Category pages** — curated product collections
+- **Comparison posts** — "Product A vs Product B"
+- **Case studies/reviews** — social proof content
+
+### Decision Content (Bottom of Funnel)
+
+- **Product detail with CTA** — pricing, buy button, urgency
+- **Testimonials/reviews** — conversion reinforcement
+- **FAQ pages** — objection handling
+- **Pricing/plans pages** — clear value proposition
+
+## Funnel Drop-Off Analysis
+
+### Identifying Drop-Off Points
+
+```
+Stage               Visitors    Drop-off    Rate
+─────────────────────────────────────────────────
+Blog post view      10,000      -           100%
+Click to product     500        9,500       5.0%
+Add to cart          80         420         16.0%
+Begin checkout       50         30          62.5%
+Complete purchase    35         15          70.0%
+─────────────────────────────────────────────────
+Overall conversion: 35 / 10,000 = 0.35%
+```
+
+### Common Drop-Off Causes and Fixes
+
+| Drop-Off Point | Common Cause | Fix |
+|----------------|-------------|-----|
+| Blog → Product | Weak CTA in blog post | Add prominent product CTA with UTM |
+| Product → Cart | Missing social proof | Add reviews, ratings, trust badges |
+| Cart → Checkout | Unexpected costs (shipping) | Show shipping calculator earlier |
+| Checkout → Purchase | Complex checkout form | Simplify, enable guest checkout |
+| Purchase → Re-order | No follow-up engagement | Set up post-purchase email sequence |
+
+## WooCommerce Cart Abandonment as Funnel Metric
+
+Cart abandonment rate = (Carts created - Orders completed) / Carts created
+
+### Measuring with WooCommerce
+
+```bash
+# Get total orders in period
+wc_get_sales_report(period="month")
+# Returns: total_orders, total_sales, etc.
+
+# Compare with add-to-cart events (requires analytics plugin or custom tracking)
+```
+
+### Abandonment Recovery Strategies
+
+1. **Abandoned cart emails** — send 1h, 24h, 72h after abandonment
+2. **Exit-intent popup** — offer discount at checkout page exit
+3. **Retargeting ads** — Facebook/Google remarketing to cart abandoners
+4. **Simplified checkout** — reduce form fields, add payment options
+
+## Cross-Referencing Sales with Content Dates
+
+Correlate content publication with sales spikes:
+
+```bash
+# Get sales by date range
+wc_get_sales_report(date_min="2025-01-01", date_max="2025-01-31")
+
+# Get content published in same period
+list_content(type="post", status="publish", after="2025-01-01", before="2025-01-31")
+```
+
+**Analysis pattern:**
+1. Pull monthly sales report from WooCommerce
+2. Pull content published that month
+3. Identify sales spikes after content publication
+4. Match spikes with UTM source data on orders
+5. Calculate correlation: content publish date → sales uplift window (typically 1–7 days)
+
+## Decision Checklist
+
+1. Are funnel stages defined and mapped to content types? → Use table above as starting point
+2. Are drop-off rates measured at each stage? → Set up analytics tracking if not
+3. Is cart abandonment rate tracked? → Check WooCommerce reports or analytics plugin
+4. Are content publish dates correlated with sales data? → Cross-reference monthly
+5. Are recovery strategies in place for the biggest drop-off point? → Prioritize highest-impact fix