/seo-ecommerce

name: seo-ecommerce
description: Conditionally audit and generate e-commerce structured data and agentic-commerce readiness for product pages — validate Product/Offer (price, priceCurrency, availability), AggregateRating/Review, faceted-navigation canonicalization and variant/ProductGroup handling, cross-check page-to-schema-to-feed consistency, and assess whether shopping agents can read the store (UCP merchant profile, catalog eligibility, ACP feed hygiene). Module M18. Feeds both the Search SEO and AI Visibility scores.
allowed-tools: Read, Grep, Glob, WebFetch, Bash

seo-ecommerce (M18)

Conditional commerce module: it runs only when commerce signals are detected, then audits (a) product structured data for Search and (b) whether an AI shopping agent can actually read and act on the store. Reference: `references/schema-tier1.md` (Product + Offer, Review/AggregateRating rows). Platform-specific ids — Shopify's Catalog and UCP defaults among them — live in `references/platforms/shopify.md` and are emitted by the platform-conditional checks, not from here.

Inputs

Work from the PageSnapshot named in your dispatch envelope: read `parsed` from `<run_dir>/pages/<slug>.json` (`jsonld[]`, `metas[]`, `text_sample`) and `vertical` from the envelope — the commerce gate is decided there; `<run_dir>/site/discovery.json` carries the probes for `/.well-known/ucp` and `/api/ucp/mcp` (status, content-type, body); `<run_dir>/profile.json` names the platform. Grep `pages/<slug>.html` for verbatim evidence; site artifacts live in `<run_dir>/site/{robots.json,sitemaps.json,discovery.json}`. Deterministic findings already emitted by `audit.mjs` are listed in `<run_dir>/findings.deterministic.json` — do not re-emit those ids; add model-judged findings only. If invoked directly with a URL/path and no snapshot exists, first run `node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"` and use the printed snapshot path.

Audits

Working from the PageSnapshot (`parsed_rendered` when `render.used` is not `none`, else `parsed`): 1. **Commerce gate**: detect commerce signals (price/currency text, add-to-cart/buy controls, `Product`/`Offer` schema, `og:type=product`). If none, every M18 finding is `not_applicable` (severity 0) — do not force product schema onto non-commerce pages. 2. **Product + Offer**: `Product` has `name`, `image`; `Offer` has `price`, `priceCurrency`, `availability` (`schema.org/InStock` etc.). Per `references/schema-tier1.md`. 3. **AggregateRating / Review**: if ratings are visibly shown, expect `AggregateRating` (`ratingValue`, `reviewCount`/`bestRating`) and/or `Review` (`author`). Never mark up ratings that are not visible on the page. 4. **Page → schema → feed consistency**: schema `price`/`priceCurrency`/`availability` must match the visible on-page values and the merchant feed. Mismatches risk disapproval and lost rich results. 5. **Faceted navigation**: filter/sort URLs (`?color=`, `?sort=`) should canonicalize to the clean product/category URL or be `noindex`, to avoid index bloat and duplicate-content dilution. 6. **Variants / ProductGroup**: multi-variant products should use `ProductGroup` with `hasVariant` and `variesBy`, not duplicate standalone `Product` blocks per SKU.

Agentic commerce readiness (ecommerce only)

Shopping agents do not read a product page the way a shopper does: they look for a machine-readable merchant profile, a catalog they are allowed to enumerate, and a feed whose fields parse. These checks run **only** when the ecommerce vertical is active, and they populate the conditional **AI** category for M18 (weight 6) alongside the Search category.

7. **UCP merchant profile** — `/.well-known/ucp` must be publicly reachable (200, no auth), valid JSON, with `ucp.version` as `YYYY-MM-DD` and `services`/`capabilities` as objects keyed by reverse-DNS names mapping to arrays of `{version, spec, transport?, endpoint?, schema}`. When the store is not an ecommerce vertical this file is M21's (`seo-ai-discovery`); on a store, M18 owns it. 8. **Catalog eligibility** — for each sampled product, check the properties a catalog needs to list it at all: a title, at least one image, a price greater than zero, a stable identifiable product URL, and a product that is not hidden/unavailable in the storefront. Report per-product results, not a single verdict. 9. **Agentic-checkout feed (ACP)** — when the user supplies a feed with `--feed <path>`, lint it: the required fields, a price written as an amount plus a currency code (`"79.99 USD"`), an availability value from the allowed enum, GTINs that pass the mod-10 check, absolute URLs, and no duplicate `item_id`. With no feed supplied the finding is `needs_api` — never a pass. 10. **Feed ↔ page price** — where a feed is available, compare its price and availability against the rendered page and the schema. Three sources, one truth. 11. **Merchant Center / platform hints** — a verified merchant feed is how Google receives authoritative product data; note whether one is plausibly present (structured data alone is not a feed) and whether the platform declares a catalog integration.

Fixes

• **AUTO** (`fixable: auto`): generate complete, valid `Product`/`Offer`/`AggregateRating` JSON-LD inferred from the DOM (name, image, price, currency, availability, visible rating) inside a single `@graph` with a stable `@id`. The block is a diff for `fix`.
• **PROPOSED** (`fixable: proposed`): canonical/`noindex` tags for faceted URLs, `ProductGroup` restructuring, and feed-field corrections — drafts requiring per-item accept.
• **ADVISORY** (`fixable: advisory`): price/availability mismatches between page, schema, and feed; UCP profile publication; catalog enrolment. The store backend, the feed, and the platform are the sources of truth, so the tool never writes these. **Never invent** prices, currencies, availability, ratings, GTINs, or endpoints — ask the user or leave a clearly-marked `TODO`