@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/resources/rp-target-wix/domains/stores/entities/product-tag.json

@@ -3,6 +3,7 @@
   "domain": "stores",
   "entity": "product-tag",
   "displayName": "Stores Product Tag",
+  "capability": "commerce.catalog-product-tag",
   "target": {
     "classification": "native",
     "nativeEntity": "Wix Tag",
@@ -10,28 +11,69 @@
     "idPolicy": "server-assigned",
     "crosswalkRequired": true
   },
+  "dependsOn": [],
   "sourceAliases": [
-    { "sourceSystem": "woocommerce", "sourceEntity": "product_tag", "routes": ["/wc/v3/products/tags"], "confidence": "high" },
-    { "sourceSystem": "wix", "sourceEntity": "productTag", "routes": ["Tags API scoped to product FQDN"], "confidence": "high" }
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "product_tag",
+      "routes": [
+        "/wc/v3/products/tags"
+      ],
+      "confidence": "high"
+    },
+    {
+      "sourceSystem": "wix",
+      "sourceEntity": "productTag",
+      "routes": [
+        "Tags API scoped to product FQDN"
+      ],
+      "confidence": "high"
+    }
   ],
   "preferredWrite": {
     "surface": "Tags",
     "endpoint": "POST /tags/v1/tags",
     "writerId": null,
-    "verification": "unverified",
+    "verification": "verified-live",
     "importSafe": true,
     "bulk": false
   },
   "fallbacks": [
-    { "classification": "cms", "when": "Use only for source tag metadata not represented by Wix Tags." }
+    {
+      "classification": "cms",
+      "when": "Use only for source tag metadata not represented by Wix Tags."
+    }
   ],
-  "reliability": { "status": "partially-reliable", "flags": [] },
+  "reliability": {
+    "status": "partially-reliable",
+    "flags": []
+  },
   "pitfalls": [
-    { "code": "fqdn-required", "severity": "blocker", "summary": "Use the verified product FQDN and resolve tag IDs before attaching them to products." }
+    {
+      "code": "fqdn-required",
+      "severity": "blocker",
+      "summary": "Use the verified product FQDN and resolve tag IDs before attaching them to products."
+    }
+  ],
+  "mappingGuidance": [
+    "Create tags via the Tags API (product FQDN), then assign IDs on the product's tags.publicTags for a public source taxonomy (WooCommerce product tags are public) or tags.privateTags for internal-only tags.",
+    "Source tag-archive URLs have no Wix equivalent; record each in the URL-preservation map with a redirect decision (category/search target or drop)."
+  ],
+  "setupRequirements": [
+    "Wix Stores app"
   ],
-  "mappingGuidance": ["Create tags before products; attach tag IDs through product publicTags when supported."],
-  "setupRequirements": ["Wix Stores app"],
   "evidence": [
-    { "type": "repo-research", "path": "research/import-api-suitability/stores-catalog-inventory.md" }
-  ]
+    
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/product-object",
+      "note": "Catalog V3 product object fields for publicTags and privateTags."
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Verified live: create + query-back readback, safe mode on — tags created via POST /tags/v1/tags + attach to variable product verified; the fqdn-required pitfall reproduced live (400 without fqdn) before the fix"
+    }
+  ],
+  "notes": "The Catalog V3 product object carries tags.publicTags, visible to site members and visitors, and tags.privateTags, which are permission-gated and merchant-side. A public source taxonomy maps to publicTags; internal or organizational tags map to privateTags. Tag-archive pages and URLs do not exist on Wix by default, so only per-product tag visibility carries over."
 }

package/skills/wix-replatform/resources/rp-target-wix/domains/stores/entities/product.json

@@ -3,6 +3,7 @@
   "domain": "stores",
   "entity": "product",
   "displayName": "Stores Product",
+  "capability": "commerce.catalog-product",
   "target": {
     "classification": "native-plus-cms",
     "nativeEntity": "Stores Product",
@@ -10,9 +11,31 @@
     "idPolicy": "server-assigned",
     "crosswalkRequired": true
   },
+  "dependsOn": [
+    "stores/category",
+    "stores/brand",
+    "stores/product-tag",
+    "media/media-file",
+    "stores/product-customization"
+  ],
   "sourceAliases": [
-    { "sourceSystem": "woocommerce", "sourceEntity": "product", "routes": ["/wc/v3/products"], "confidence": "high" },
-    { "sourceSystem": "wix", "sourceEntity": "storesProduct", "routes": ["Stores Catalog V1 Products", "Stores Catalog V3 Products"], "confidence": "high" }
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "product",
+      "routes": [
+        "/wc/v3/products"
+      ],
+      "confidence": "high"
+    },
+    {
+      "sourceSystem": "wix",
+      "sourceEntity": "storesProduct",
+      "routes": [
+        "Stores Catalog V1 Products",
+        "Stores Catalog V3 Products"
+      ],
+      "confidence": "high"
+    }
   ],
   "preferredWrite": {
     "surface": "Stores Catalog V3 Products",
@@ -31,7 +54,7 @@
       "path": "product.subscriptionDetails",
       "verificationLevel": "live-create-and-readback",
       "lastVerified": "2026-07-26",
-      "verifiedBy": "migration-20260726-01",
+      "verifiedBy": "live-verification",
       "requiredPaths": [
         "product.subscriptionDetails.allowOneTimePurchases",
         "product.subscriptionDetails.subscriptions[]",
@@ -49,7 +72,12 @@
         },
         {
           "path": "product.subscriptionDetails.subscriptions[].frequency",
-          "enum": ["DAY", "WEEK", "MONTH", "YEAR"],
+          "enum": [
+            "DAY",
+            "WEEK",
+            "MONTH",
+            "YEAR"
+          ],
           "source": "live-create"
         },
         {
@@ -71,20 +99,123 @@
     }
   ],
   "fallbacks": [
-    { "classification": "cms", "when": "Use for plugin rules, source-only metadata, or catalog semantics that do not fit product extended fields." }
+    {
+      "classification": "cms",
+      "when": "Use for plugin rules, source-only metadata, or catalog semantics that do not fit product extended fields."
+    }
   ],
-  "reliability": { "status": "partially-reliable", "flags": [] },
+  "reliability": {
+    "status": "partially-reliable",
+    "flags": []
+  },
   "pitfalls": [
-    { "code": "catalog-v3-normalization", "severity": "blocker", "summary": "Normalize V1/simple product fields into Catalog V3 product and variant shapes before create." },
-    { "code": "variant-matrix-two-pass", "severity": "warning", "summary": "Full variable product matrices require a post-create option-choice and variant pass." }
+    {
+      "code": "catalog-v3-normalization",
+      "severity": "blocker",
+      "summary": "Normalize V1/simple product fields into Catalog V3 product and variant shapes before create."
+    },
+    {
+      "code": "variant-matrix-two-pass",
+      "severity": "warning",
+      "summary": "Full variable product matrices require a post-create option-choice and variant pass."
+    },
+    {
+      "code": "empty-source-slug-derives-and-can-collide",
+      "severity": "warning",
+      "summary": "VERIFIED LIVE: a source product carrying an EMPTY slug is not rejected -- Wix derives one from the product name instead. That derived slug competes in the same namespace as every slug the import supplies, so it can collide with another product's decoded source slug or with a second product whose name slugifies the same way, and the losing write comes back as a duplicate-slug conflict. Empty source slugs are not rare. Resolve them BEFORE the write -- mint an explicit, catalog-unique slug per affected product and record it against the source id -- so which product owns the name is decided by the mapping, not by write order. A conflict resolved by appending a numeric suffix, whether the platform did it or a repair pass did, is a DEVIATION from the source value and not a preserved slug: report it as an exception on the run's faithfulness ledger rather than counting it as correct."
+    },
+    {
+      "code": "media-source-resolution",
+      "severity": "blocker",
+      "summary": "media.itemsInfo.items[] takes ONE url per image and the destination copies exactly that file, generating every derivative from it with no way to raise quality afterwards -- so the url sent is that image's permanent ceiling. Never map a single named source image field: a source image reference usually carries several urls for the same picture at different sizes, and the field holding the original differs between routes of the SAME source. Resolve to the original, maximum-resolution candidate before building the item. Also: altText (1-1000 chars) and displayName (max 80, url-set items only) are writable per item and must not be flattened away; thumbnail is destination-generated output, never an input."
+    },
+    {
+      "code": "wordpress-percent-encoded-slug",
+      "severity": "blocker",
+      "summary": "product.slug is user-visible URL, not internal state -- and Wix slug sanitizing silently turns literal '%' characters into dashes rather than erroring. A WooCommerce source stores a non-Latin (e.g. Hebrew) post_name percent-encoded and its REST API (wc/v3) returns it undecoded; passing that raw value straight through as product.slug produces a garbled hex-with-dashes URL (e.g. '.../product-page/d7-90-d7-99-d7-a0-d7-98-d7-a0-d7-a1-d7-95') instead of the real slug. Nothing fails -- no 400 and no warning -- so only a check that compares the stored slug against the DECODED source value catches it; comparing against the raw source field or against what the writer sent calls it correct. Decode with decodeURIComponent BEFORE the slug coercion runs (decoding afterwards is too late: sanitizing has already consumed the '%'), guarded in a try/catch so a slug that was never percent-encoded passes through unchanged and a malformed escape falls back to the raw value instead of throwing. The decoded Unicode slug is then writable as-is: the standard coercion (`coerce: 'slug'`, i.e. toWixSlug) lowercases and keeps letters, combining marks and digits in any script, so do not replace a non-Latin slug with a transliterated or invented one. Confirm on the FIRST product that the decoded slug read back intact; missing it costs a repair pass over every product already created. Confirmed live on non-Latin WooCommerce catalogs. See rp-source-wordpress/SKILL.md and rp-import-codegen/SKILL.md's 'Never hand-write slug sanitizing' section."
+    },
+    {
+      "code": "seo-data-only-for-proven-overrides",
+      "severity": "blocker",
+      "summary": "Write product.seoData only for per-field SEO overrides the source proves (see rp-source-wordpress wordpress-seo product-seo-meta). Rendered Yoast output would turn an inherited pattern into a hard per-product override. [UNVERIFIED as of 2026-09-29] Create-time persistence of seoData on the create-with-inventory call has not been live-verified: the throwaway-site canary (create one product with inventory plus title and description seoData, read it back, observe both tags resolve TAG_SOURCE_ITEM, delete it) is still pending. Until it is recorded here, product-seo.js reads every product back after create and, if seoData was dropped, writes it with a revision-protected PATCH and verifies that. A PATCH of seoData with the saved revision is live-observed (2026-08-27, resolved TAG_SOURCE_ITEM). tags[] is replaced whole: send current non-import-owned tags back unchanged."
+    }
   ],
   "mappingGuidance": [
-    "Create categories, tags, and media references before products when the source uses them.",
-    "Preserve recurring offers natively via product.subscriptionDetails.subscriptions[] when the source exposes clear cadence data; live create coverage was verified on July 26, 2026, while patch/update coverage remains unverified."
+    "Create categories, brands, tags, and media references before products when the source uses them; assign brands by crosswalked brand.id, never by name (see stores/brand).",
+    "Preserve recurring offers natively via product.subscriptionDetails.subscriptions[] when the source exposes clear cadence data; live create coverage was verified on July 26, 2026, while patch/update coverage remains unverified.",
+    "Plan the slug for the WHOLE catalog before writing the first product, not per record. Two source shapes decide the target slug and neither is visible one record at a time: a percent-encoded non-Latin slug must be tolerantly percent-decoded first and then kept as the decoded Unicode value (see wordpress-percent-encoded-slug), and an empty source slug must be filled in rather than left for the platform to derive (see empty-source-slug-derives-and-can-collide). Build the source-slug -> planned-target-slug map up front, assert it is unique across the catalog after coercion, and carry the ORIGINAL source slug beside the planned one so a later URL-preservation report can tell a faithful slug from a deviated one.",
+    "Product images: pass every candidate url the source record offers to the source adapter's image resolver and use its result, never a hardcoded field such as src. Carry altText and displayName through to the media item. When the resolver reports that only a downscaled crop existed, record those images in the run's faithfulness ledger rather than importing them silently.",
+    "Product SEO: build seoData with buildProduct(canonical, { seoPlan }) from product-seo.js planProductSeo; never map rendered source SEO into seoTitle/seoDescription for an evidence-contract source."
+  ],
+  "setupRequirements": [
+    "Wix Stores app",
+    "Product data extension schema when source-only product fields are preserved natively.",
+    "Product data extension schema (FQDN wix.stores.catalog.*.product, provision-extended-fields step) before any writer emits product extendedFields values."
   ],
-  "setupRequirements": ["Wix Stores app", "Product data extension schema when source-only product fields are preserved natively."],
   "evidence": [
-    { "type": "repo-research", "path": "research/import-api-suitability/stores-catalog-inventory.md" },
-    { "type": "repo-research", "path": "research/source-entity-import-suitability-wordpress-woocommerce-wix.md" }
-  ]
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/product-object",
+      "note": "object page (docs-survey sweep 2026-08-11)"
+    }
+  ],
+  "extendedFields": {
+    "schemaKind": "data-extension-schema",
+    "definitionSurface": "Data Extension Schema API",
+    "definitionOperation": "Create/Update Data Extension Schema (FQDN wix.stores.catalog.*.product)",
+    "valuePath": "extendedFields.namespaces._user_fields",
+    "namespaceForCreatedFields": "_user_fields",
+    "dataExtensionSchemaBacked": true,
+    "fqdn": "wix.stores.catalog.*.product",
+    "supportsFiltering": true,
+    "nestedSubrecordExtendedFields": "none known",
+    "liveVerification": "UNVERIFIED — offline contract only; disposable-site create and concurrent-edit proof pending.",
+    "admittedFieldTypes": [
+      "string"
+    ],
+    "keyConvention": "sourceProductId for the source product id; plain keys under _user_fields.",
+    "docs": [
+      "https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/introduction"
+    ]
+  },
+  "intendedFields": [
+    {
+      "targetPath": "product.name",
+      "sourcePaths": [
+        "name"
+      ]
+    },
+    {
+      "targetPath": "product.plainDescription",
+      "sourcePaths": [
+        "description"
+      ]
+    },
+    {
+      "targetPath": "product.media.itemsInfo.items[]",
+      "sourcePaths": [
+        "images[]",
+        "media[]"
+      ]
+    }
+  ],
+  "readBackProjection": {
+    "identity": "source-marker-and-variant-id",
+    "serverOwned": [
+      {
+        "path": "product.revision",
+        "reason": "server revision"
+      },
+      {
+        "path": "product.updatedDate",
+        "reason": "server timestamp"
+      }
+    ],
+    "read": "getStoresProductForVerification",
+    "fields": [
+      "MEDIA_ITEMS_INFO",
+      "PLAIN_DESCRIPTION"
+    ],
+    "mediaSettlement": "read-after-60s-unknown-on-exhaustion"
+  }
 }

package/skills/wix-replatform/resources/rp-target-wix/domains/stores/entities/promotion.json

@@ -0,0 +1,84 @@
+{
+  "schemaVersion": 1,
+  "domain": "stores",
+  "entity": "promotion",
+  "displayName": "Stores Promotion (Category Banner)",
+  "capability": "marketing.storefront-banner",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Stores Promotion",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [],
+  "dependsOn": ["stores/category"],
+  "preferredWrite": {
+    "surface": "Stores Catalog V3 Promotions",
+    "endpoint": "POST /stores/v3/promotions",
+    "writerId": null,
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": true
+  },
+  "reliability": {
+    "status": "partially-reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "promotion-is-a-banner-not-a-discount",
+      "severity": "blocker",
+      "summary": "CORRECTED 2026-08-16 (this entity previously claimed the opposite). A Wix Stores promotion is 'a visual banner displayed on store category pages, including their product gallery sections' — it is a MERCHANDISING IMAGE with a name, a required media asset, an optional destinationUrl, and category placements. It carries NO discount, NO percentage, NO scope, NO date window, and NO price effect of any kind; the create schema has no such fields and a body containing them is rejected. Discount-rule plugin campaigns therefore DO NOT map here — route them to stores/coupon, to native discount rules, or to per-product pricing on stores/product. Mapping a source discount campaign to this entity would produce a decorative banner and silently lose the discount."
+    },
+    {
+      "code": "media-is-required-external-url-accepted",
+      "severity": "blocker",
+      "summary": "promotion.media is a REQUIRED create field (verified live 2026-08-16: omitting it → 400 REQUIRED_FIELD on promotion.media). It is a one-of: media.id for an existing Wix Media Manager file, or media.url for an external image that Wix Media Manager imports asynchronously. The external-URL path means NO media pre-import step is needed for this entity (the earlier 'must come from the Media Manager first' claim was wrong) — but see promotion-media-import-fails-silently before relying on it."
+    },
+    {
+      "code": "promotion-media-import-fails-silently",
+      "severity": "blocker",
+      "summary": "The media.url import is asynchronous and its failure mode is destructive and silent. Per the docs, during import the promotion is saved DISABLED regardless of the requested enabled value, and if the import fails 'the promotion's entire media object is cleared and the promotion stays disabled'. VERIFIED LIVE 2026-08-16: of three probe promotions, one imported successfully (media resolved to a static.wixstatic.com id with width/height/filename), one was still pending after 12s (media.url and uploadId still present, no image yet), and one came back with NO media object at all and revision bumped to 2 — a failed import, reported by nothing but the absence of a field. A create returning 200 does NOT mean the banner has an image. Any import of these must poll GET /stores/v3/promotions/{id} until media.image is populated, and treat a cleared media object as a per-record failure needing a retry with new media."
+    },
+    {
+      "code": "category-assignment-needs-explicit-position",
+      "severity": "warning",
+      "summary": "categories[] entries require an explicit position starting from 1 — omitting it fails validation (docs, read 2026-08-16). appliedToSubcategories (default false) controls inheritance, and an inherited placement keeps the same position. A promotion created without categories[] (as the probe was) exists but appears nowhere, so a category crosswalk must be resolved before this write is worth making."
+    }
+  ],
+  "mappingGuidance": [
+    "Dependencies: stores/category is required when category placements are mapped, because the promotion must use the category crosswalk; media URLs are imported asynchronously and do not require media/media-file.",
+    "Only author this from source data that is genuinely a storefront BANNER — a category-page hero/promo image from a theme or a banner plugin. Never from discount data.",
+    "Explicit non-targets, to stop the same source record importing twice: per-product sale prices belong to stores/product pricing; coupon codes belong to stores/coupon; discount-rule plugin campaigns (bulk/tiered/BOGO) have no import path as rules and are reconfigure-in-wix (see ecom/order-applied-discount, which carries only the historical applied-discount RECORDS on past orders).",
+    "Create promotions after categories exist and resolve placements through the category crosswalk, supplying categories[].position from the source ordering (1-based).",
+    "Prefer media.url with the publicly reachable source image URL over a Media Manager pre-import — then poll the created promotion until media.image is populated, and fail the record loudly if media comes back cleared.",
+    "Set enabled deliberately: it is false by default, and with media.url it only takes effect after the import completes."
+  ],
+  "setupRequirements": [
+    "Wix Stores app",
+    "SCOPE.STORES.CATALOG_WRITE"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/promotions-v3/promotion-object",
+      "note": "object page: id/revision/name/media + category placements"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/promotions-v3/create-promotion",
+      "note": "full request schema read 2026-08-16: required promotion.name + promotion.media; media one-of id|url with async import semantics; destinationUrl, categories[].position, enabled (default false), tags; errors MEDIA_NOT_FOUND, DUPLICATE_CATEGORY_ASSIGNMENT, PROMOTIONS_LIMIT_EXCEEDED. No discount, scope, or date fields exist on this entity."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/promotions-v3/bulk-create-promotions"
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Verified live: a first create modelled on this entity's old discount-campaign framing ({ discount: { percentage }, scope, status }) was rejected — 400 REQUIRED_FIELD promotion.media — which is what exposed the model error. Corrected creates with { name, media: { url, altText, displayName }, destinationUrl, enabled: false } → 200 on three probe promotions; readback showed one media import succeeding (image id/url/width/height/filename populated on static.wixstatic.com), one still pending, and one with the media object cleared entirely after a failed import. All three deleted via DELETE /stores/v3/promotions/{id} → 200. Not exercised: media.id (Media Manager) attachment, categories[] placement, bulk create."
+    }
+  ],
+  "notes": "Authored 2026-08-11 from the docs-survey gap (Promotions V3). SUBSTANTIALLY CORRECTED 2026-08-16 by a live probe: the previous version modelled this as a catalog-level DISCOUNT campaign entity (capability commerce.promotions, pitfall 'promotion-model-mismatch', mappingGuidance 'author from discount-rule campaign data'). That was wrong — Promotions V3 is a category-page banner surface with no discount semantics whatsoever, so the capability was renamed to marketing.storefront-banner and the discount-campaign guidance replaced with explicit non-targets. Now verified-live for the create/readback/delete path; reliability is partially-reliable because the async media import failed on one of three probes with no error surfaced, and category placement was never exercised. There is still no profiled source-side population for this entity."
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/stores/entities/review.json

@@ -0,0 +1,178 @@
+{
+  "schemaVersion": 1,
+  "domain": "stores",
+  "entity": "review",
+  "displayName": "Product Review",
+  "capability": "commerce.product-reviews",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Review",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "dependsOn": [
+    "stores/product",
+    "crm/contact"
+  ],
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "product_review",
+      "routes": [
+        "/wc/v3/products/reviews"
+      ],
+      "confidence": "high"
+    }
+  ],
+  "preferredWrite": {
+    "surface": "Wix Reviews",
+    "endpoint": "POST /reviews/v1/bulk/reviews/create",
+    "writerId": null,
+    "verification": "docs",
+    "importSafe": false,
+    "bulk": true
+  },
+  "alternateWrites": [
+    {
+      "surface": "Wix Reviews",
+      "endpoint": "POST /reviews/v1/reviews",
+      "when": "Single-review create. Use for retries of bulk failures and for the tail of a batch; the required-parameter sets differ (see the required-field-asymmetry pitfall)."
+    },
+    {
+      "surface": "Wix Reviews",
+      "endpoint": "POST /reviews/v1/bulk/reviews/moderate",
+      "when": "Second pass after create, to force the imported moderation state (APPROVED / REJECTED). moderation.moderationStatus is read-only on create."
+    },
+    {
+      "surface": "Wix Reviews",
+      "endpoint": "PATCH /reviews/v1/reviews/{reviewId}/reply",
+      "when": "Third pass, only if the source carries merchant replies to reviews; reply is read-only on create."
+    }
+  ],
+  "fallbacks": [
+    {
+      "classification": "cms",
+      "when": "Use for review facts the native object cannot carry — the verified-purchase badge, ratings of 0, over-length bodies, and the source review ID/author email when no contact is created. Native reviews stay the primary record; the CMS shadow is evidence, not display."
+    }
+  ],
+  "reliability": {
+    "status": "unknown",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "contact-required-per-review",
+      "severity": "blocker",
+      "summary": "Every review needs a contact: Bulk Create requires reviews.author.contactId, and the Create Review introduction states the single-create method requires a contact ID too. Importing reviews therefore CREATES OR RESOLVES A CONTACT PER DISTINCT REVIEWER — a CRM side effect well beyond the catalog, and reviewers are frequently not customers. Resolve each reviewer by email through Query Contacts first, create only on miss, and disclose the contact count at the execution gate."
+    },
+    {
+      "code": "moderation-status-read-only-on-create",
+      "severity": "warning",
+      "summary": "moderation.moderationStatus is read-only on create; a created review starts as SUBMITTED and is then moved by the site's moderation rules to APPROVED / IN_MODERATION / REJECTED. Source approval state (WooCommerce approved vs hold vs spam vs trash) survives only via a second pass — Bulk Update Moderation Status (POST /reviews/v1/bulk/reviews/moderate), whose status enum accepts APPROVED or REJECTED only (not IN_MODERATION), is filter-based, and returns a jobId (asynchronous — completion is not observable in the create response)."
+    },
+    {
+      "code": "verified-badge-not-writable",
+      "severity": "warning",
+      "summary": "review.verified (the verified-owner/verified-purchase badge) is read-only on create and has no documented import path. WooCommerce's per-review `verified` flag CANNOT CARRY — this is a reportable faithfulness loss on every imported review, not a rounding error, because the badge is the trust signal shoppers read."
+    },
+    {
+      "code": "rating-1-to-5-only",
+      "severity": "warning",
+      "summary": "content.rating is an integer with Min 1 / Max 5, and it is required on single create. WooCommerce permits rating 0 (\"no rating\" — a review with text and no stars), which cannot be created natively. A run must pick a policy per source site: drop those rows to the CMS shadow, or coerce to a rating the merchant approves. Never silently coerce."
+    },
+    {
+      "code": "one-review-per-author-per-entity",
+      "severity": "warning",
+      "summary": "\"A review author is limited to 1 review per entity. Duplicate reviews receive an error response.\" WooCommerce permits many reviews by the same author (same email) on the same product, so a collision policy is required BEFORE the write: keep newest / keep highest-rated / merge bodies / spill the losers to the CMS shadow. Detect collisions during mapping by grouping source reviews on (reviewer_email, product_id) — an anonymized verification environment had 0 collisions across 120 reviews, which makes this easy to miss on a first run."
+    },
+    {
+      "code": "body-plain-text-3000",
+      "severity": "warning",
+      "summary": "content.body is plain text with maxLength 3000 (content.title also maxLength 3000, author.authorName maxLength 100, content.media maxItems 10, entityId maxLength 36). WooCommerce review bodies are HTML — strip tags before the write, and ledger every review whose stripped body exceeds 3000 characters with the chosen policy (truncate or divert to the CMS shadow)."
+    },
+    {
+      "code": "stores-namespace-only",
+      "severity": "warning",
+      "summary": "namespace supports \"stores\" only — \"Currently, only Wix Stores is fully integrated with the Wix Reviews app.\" entityId must be the Wix Stores PRODUCT ID (maxLength 36), so the product crosswalk must be complete and the products must already exist before any review write. Reviews of non-product entities (WordPress post/page comments) have no home here; they belong to blog/comment."
+    },
+    {
+      "code": "required-field-asymmetry",
+      "severity": "warning",
+      "summary": "The two create surfaces do not require the same fields. Create Review requires review.namespace, review.entityId, review.content, review.content.rating (author.contactId is not in its required list despite the prose). Bulk Create requires reviews.namespace, reviews.entityId, reviews.content, reviews.author, reviews.author.contactId — but NOT reviews.content.rating. Send the full set on both paths rather than relying on either list."
+    },
+    {
+      "code": "docs-endpoint-path-inconsistency",
+      "severity": "warning",
+      "summary": "The Create Review and Set Reply reference pages print two different base paths: the Schema \"URL:\" line says https://www.wixapis.com/reviews/api/v1/reviews while the curl example on the same page says https://www.wixapis.com/reviews/v1/reviews. Bulk Create is consistent at /reviews/v1/bulk/reviews/create. This entity records the /reviews/v1/... form (the executable examples); confirm live before promoting verification above docs."
+    },
+    {
+      "code": "bulk-batch-100",
+      "severity": "warning",
+      "summary": "Bulk Create takes minItems 1 / maxItems 100 reviews per call and returns per-item results with originalIndex and a success flag (entities only when returnEntity is true). Chunk at 100, always request returnEntity so the crosswalk can record server-assigned review IDs, and treat partial failure as normal — the call succeeds while individual items fail."
+    }
+  ],
+  "mappingGuidance": [
+    "Import order: products first (entityId is a Wix product ID), then contacts for reviewers, then reviews. Write via POST /reviews/v1/bulk/reviews/create in chunks of 100 with returnEntity=true, recording sourceReviewId -> Wix review ID in the crosswalk.",
+    "REVIEWER CONTACTS ARE A SIDE EFFECT THE USER MUST APPROVE AT THE REVIEW GATE. Every imported review needs author.contactId, so importing reviews grows the site's CRM by one contact per distinct reviewer email, including reviewers who are not customers and would otherwise never appear in Contacts. Present the run-specific distinct-reviewer count, state that these contacts are created by the review import, and let the user choose whether to import or skip reviews.",
+    "Carry the original review date with review.reviewDate (writable at create, format date-time) — the docs designate it as the import path: \"This should match createdDate, except for reviews imported from another system.\" createdDate is read-only and will be the import timestamp, so reviewDate is the only faithful date.",
+    "Approval state needs a second pass. Create everything, then group the created review IDs by the source status and call POST /reviews/v1/bulk/reviews/moderate once per target status (APPROVED for WooCommerce approved, REJECTED for spam/trash). WooCommerce `hold` has no exact native equivalent — IN_MODERATION is not settable through the bulk moderate enum — so decide with the user whether held reviews are left to the site's moderation rules, rejected, or skipped entirely.",
+    "Map author.authorName from the WooCommerce reviewer display name (maxLength 100) and author.contactId from the resolved contact. If authorName is omitted, Wix falls back to the member name for members and to null otherwise — always send it explicitly so anonymous reviewers do not lose their display name.",
+    "Record in the faithfulness ledger, per run: reviews whose `verified` badge was lost, reviews with source rating 0, reviews whose stripped body exceeded 3000 characters, and reviews dropped by the one-per-author-per-entity collision policy."
+  ],
+  "setupRequirements": [
+    "Wix Reviews app",
+    "Wix Stores app (Reviews is only integrated with Wix Stores, and the products must already exist)",
+    "SCOPE.DC-REVIEWS.MANAGE-REVIEWS",
+    "Contacts write access (SCOPE.DC-CONTACTS.MANAGE-CONTACTS) — every review requires a contact ID",
+    "User approval at the review gate for the reviewer-contact side effect"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/community/feedback-moderation/reviews/reviews/review-object",
+      "note": "object page, fetched 2026-08-16. DOC TREE LOCATION: the Reviews API lives under CRM > Community > Feedback & Moderation, NOT under business-solutions/stores — which is why the 2026-08-11 stores docs-survey sweep (docsRoots api-reference/business-solutions/stores) missed it entirely. This entity is filed in the stores domain because namespace supports \"stores\" only and entityId is a Stores product ID; the survey row that claims it lives in the crm domain. Do not 'rediscover' this."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/community/feedback-moderation/reviews/reviews/introduction",
+      "note": "fetched 2026-08-16. Verbatim: \"The Wix Reviews API allows you to: Import reviews from other sites and export reviews to other sites.\" Also: namespace \"stores\" only; \"Every review needs a contact\" (resolve via Query Contacts by email); \"A review author is limited to 1 review per entity. Duplicate reviews receive an error response.\"; rating 1-5."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/community/feedback-moderation/reviews/reviews/create-review",
+      "note": "fetched 2026-08-16. Scope SCOPE.DC-REVIEWS.MANAGE-REVIEWS. Required: review, review.namespace, review.entityId, review.content, review.content.rating. curl example POSTs https://www.wixapis.com/reviews/v1/reviews (the Schema URL line on the same page prints /reviews/api/v1/reviews). Validations: entityId maxLength 36, content.title maxLength 3000, content.body maxLength 3000, content.media maxItems 10, author.contactId format GUID + immutable, authorName maxLength 100, reviewDate format date-time (WRITABLE at create). Read-only on the response: id, createdDate, updatedDate, reply, foundHelpful, foundUnhelpful, helpfulness, moderation (whole object), revision, verified, origin, relevanceScore, publishCount."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/community/feedback-moderation/reviews/reviews/bulk-create-review",
+      "note": "fetched 2026-08-16. POST https://www.wixapis.com/reviews/v1/bulk/reviews/create; reviews array minItems 1, maxItems 100; required reviews, reviews.namespace, reviews.entityId, reviews.content, reviews.author, reviews.author.contactId (content.rating is NOT in the bulk required list). returnEntity flag; results carry itemMetadata {id, originalIndex, success, error}."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/community/feedback-moderation/reviews/reviews/bulk-update-moderation-status",
+      "note": "fetched 2026-08-16. POST https://www.wixapis.com/reviews/v1/bulk/reviews/moderate; filter + status; status enum is UNKNOWN / APPROVED / REJECTED only; returns jobId (asynchronous)."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/community/feedback-moderation/reviews/reviews/set-reply",
+      "note": "fetched 2026-08-16. PATCH /reviews/v1/reviews/{reviewId}/reply, required message — replies are a separate call because review.reply is read-only on create."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/community/feedback-moderation/reviews-moderation-business-flow",
+      "note": "fetched 2026-08-16. \"To import or migrate multiple reviews, call Bulk Create Review.\" Created reviews land at moderationStatus SUBMITTED and are then moved by moderation rules. Prerequisites stated: Wix Stores must be installed, the products must exist, and each review requires a contact ID."
+    },
+    {
+      "type": "review-decision",
+      "path": "internal design decision, 2026-07-30",
+      "note": "added specifically so mapper/codegen stop reporting 'No verified native Wix product-review primitive was identified for this workflow'. Broader mapper/codegen/execution support for reviews may still need follow-up work."
+    },
+    {
+      "type": "live-run",
+      "path": "tests/fixtures/wordpress/rest-index-scope.json",
+      "note": "Live source verification established that /wc/v3/products/reviews exposes review status and reviewer email and is classified backend_data/sample by the /wc/v3/products* catch-all rule in lib/wp-route-classifier.js. The fixture pins that classification so future narrowing cannot silently drop reviews."
+    }
+  ],
+  "notes": "Authored 2026-08-16. Before this file no domain entity claimed a product-review capability, so every run dropped its source reviews into a pending row despite Wix having a native, explicitly import-oriented API. Docs-verified only — nothing here has been exercised live, hence verification=docs / reliability=unknown / importSafe=false. importSafe is false because a review import writes into CRM (a contact per distinct reviewer) as well as the catalog, which is a side effect a user must accept at the gate, not a silent consequence. Promote verification after a live subset write that exercises bulk create + the moderation second pass."
+}