@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/resources/rp-target-wix/domains/seo/domain.json

@@ -0,0 +1,73 @@
+{
+  "schemaVersion": 1,
+  "domain": "seo",
+  "dependsOnRequired": true,
+  "docsRoots": [
+    "api-reference/business-management/seo",
+    "api-reference/business-management/marketing/seo",
+    "api-reference/business-management/headless/sitemap",
+    "api-reference/site/viewer/seo-tags"
+  ],
+  "displayName": "Wix SEO",
+  "ownerHint": "SEO (item SEO tags, site SEO tags, SEO patterns, robots.txt/ads.txt/llms.txt) domain owners",
+  "wixAppsRequired": [],
+  "defaultImportOrder": [
+    "site-seo-tags",
+    "seo-pattern",
+    "item-seo-tags"
+  ],
+  "sharedPitfalls": [
+    {
+      "code": "seo-tags-resolve-through-a-precedence-chain",
+      "severity": "warning",
+      "summary": "A rendered tag is not stored in one place. Wix combines, in increasing precedence: site tags -> the Wix default pattern for the page type -> the site's own pattern -> the host page's tags -> the item's own tags. Writing a value at the item level therefore SHADOWS everything below it, and the docs warn explicitly that 'writing the same title onto a thousand items is the same outcome as one pattern, and much harder to undo'. Import at the level that matches the source fact: a WordPress SEO title TEMPLATE belongs in seo/seo-pattern, a per-post override belongs in seo/item-seo-tags."
+    },
+    {
+      "code": "seo-writes-replace-in-full",
+      "severity": "blocker",
+      "summary": "Every SEO write replaces what it targets in full and there is NO revision checking - the last write wins, and a Wix user editing SEO in the dashboard writes the same data. Read immediately before writing, send back the complete tag set (not only the changed tag), and never interleave an import with dashboard editing."
+    },
+    {
+      "code": "coverage-depends-on-installed-business-solutions",
+      "severity": "warning",
+      "summary": "The supported itemType / pageType list is per site: a type provided by a business solution only exists where that solution is installed (UNSUPPORTED_ITEM_TYPE / UNSUPPORTED_PAGE_TYPE list the supported values in the error message, and PAGE_TYPE_NOT_ON_SITE is a distinct 404). Discover the list from a failing call at setup time; never hard-code it."
+    },
+    {
+      "code": "primary-language-only",
+      "severity": "warning",
+      "summary": "Item SEO tags can be written only for the site's primary language: sending `language` fails with LANGUAGE_NOT_SUPPORTED. A multilingual WordPress source cannot carry per-locale SEO meta through this API; ledger the secondary-language tags rather than dropping them silently."
+    },
+    {
+      "code": "url-redirect-api-not-yet-integrated",
+      "severity": "warning",
+      "summary": "Wix publicly documents the SEO Redirects API in Developer Preview for permanent URL rules (seo-redirects-service/v1); the Headless Redirect Sessions API is a different auth/checkout facility. Current method schema: List Redirects is unpaged and takes no filter; Bulk Create accepts 1-100 items and reports each by itemMetadata.originalIndex; writes need Manage SEO Settings through a Wix app or Wix user identity; site-member identity is distinct and is not accepted by the helper. The CLI requires an explicit APP or WIX_USER identity declaration and matching destination site. Single Create resolves a loop by DELETING the loop-closing rule and forceReplace deletes the rule holding the path. Bulk Create fails an item whose path is taken (FROM_URL_EXISTS) or that loops within the same request (REDIRECT_LOOP), but a rule that closes a loop with a rule already on the site is still created and the existing loop-closing rule deleted. The shared helper therefore writes through Bulk Create only, never sends forceReplace, refuses any destination that is an existing rule's source, and stops if an existing rule disappears between batches. An existing rule with the same from/to is reported as success without an id, so outcomes are settled by List Redirects reconciliation, never by HTTP 200. RePlatform's post-build helper (scripts/url-redirects.js plan/apply/verify) applies only exact same-site 301 rules after conflict preflight and verifies old addresses over HTTP. Live API acceptance confirmed site-scoped Wix user List/Bulk Create/read-back, duplicate-create success without an id, and exact-ID cleanup. Bulk maximum remains schema-based, not live stress-tested; frontend serving and full public acceptance remain unverified, so never report a planned or installed rule as a working link and never use the temporary Wix domain as a redirect destination."
+    }
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/introduction",
+      "note": "domain root; menu walked 2026-08-16 (Item SEO Tags V1, Site SEO Tags V1, SEO Pattern V1) plus the second SEO tree under Marketing (robots.txt / ads.txt / llms.txt / keyword SPI / SEO user config), Headless > Sitemap, and Site > Viewer > SEO Tags"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/marketing/seo/introduction",
+      "note": "second docs root: Wix splits SEO across Business Management > SEO (tags) and Business Management > Marketing > SEO (TXT files, keyword SPI, site URL config) — finding one tree does not mean the other does not exist"
+    },
+    {
+      "type": "domain-kb",
+      "path": "skills/wix-replatform/SKILL.md",
+      "note": "URL preservation and redirect planning remain local; the public API has not yet been integrated into an application and verification workflow"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/redirects/redirect-v1/create-redirect",
+      "note": "Public Developer Preview URL-rule API. Documentation establishes the capability, not live verification or integration into this migration workflow."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/redirects/redirect-v1/bulk-create-redirects",
+      "note": "Per-item results and potentially destructive loop/conflict handling; inspect existing rules before creating. Current method documentation says 100 items while the introduction says 500; validate the current schema before selecting a batch limit."
+    }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/seo/entities/item-seo-tags.json

@@ -0,0 +1,148 @@
+{
+  "schemaVersion": 1,
+  "domain": "seo",
+  "entity": "item-seo-tags",
+  "displayName": "Item SEO Tags",
+  "capability": "content.seo-meta",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Item SEO Tags",
+    "verifiedFqdn": null,
+    "idPolicy": "natural-key",
+    "crosswalkRequired": true
+  },
+  "dependsOn": [],
+  "sourceAliases": [
+    {
+      "sourceSystem": "wordpress",
+      "sourceEntity": "yoastHeadJson",
+      "sourcePlugin": "wordpress-seo",
+      "routes": [
+        "/wp/v2/posts",
+        "/wc/v3/products",
+        "/wp/v2/categories"
+      ],
+      "confidence": "high"
+    },
+    {
+      "sourceSystem": "wordpress",
+      "sourceEntity": "rankMathPostMeta",
+      "sourcePlugin": "seo-by-rank-math",
+      "routes": [],
+      "confidence": "medium"
+    }
+  ],
+  "preferredWrite": {
+    "surface": "Item SEO Tags V1",
+    "endpoint": "POST /promote/seo/v1/bulk/item-seo-tags/set",
+    "writerId": null,
+    "verification": "docs",
+    "importSafe": true,
+    "bulk": true
+  },
+  "reliability": {
+    "status": "unknown",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "item-id-is-the-wix-id-not-the-source-id",
+      "severity": "blocker",
+      "summary": "An item is addressed by `{itemType}:{itemId}` where itemId is the WIX GUID of an already-created item (a page, a Blog post, a Stores product). SEO tags therefore import in a SECOND pass, after the owning entity has been written and its id recorded in the crosswalk. There is no create-by-source-id path here, which is why crosswalkRequired is true."
+    },
+    {
+      "code": "one-item-type-per-bulk-call",
+      "severity": "warning",
+      "summary": "Bulk Set Item SEO Tags takes a single `itemType` for the whole request and at most 100 entries (minItems 1, maxItems 100; tags maxItems 100 per item, focusKeywords maxItems 5). Batch by item type, then by 100. An unsupported item type or one that does not support bulk rejects the WHOLE call (UNSUPPORTED_ITEM_TYPE 400, BULK_NOT_SUPPORTED_FOR_ITEM_TYPE 428) with no per-entry results, so handle whole-call failure separately from per-entry failure (itemMetadata.originalIndex / bulkActionMetadata.totalFailures). Per-entry writes are idempotent, so retry only the failures."
+    },
+    {
+      "code": "static-page-publish-flag-hides-the-write",
+      "severity": "warning",
+      "summary": "For an item type that keeps a separate draft and published revision (STATIC_PAGE), an entry with `publish: true` updates only the PUBLISHED revision - Get/List Item SEO Tags keep returning the pre-call values for that item, and publishStatus always reports PUBLISH_STATUS_UNSPECIFIED for STATIC_PAGE because there is no live-revision read path. A verification read that compares what was written will look like a failed write. Verify static pages through Site > Viewer > Resolve Static Page SEO Tags, or accept the read-back gap in the ledger."
+    },
+    {
+      "code": "item-level-write-shadows-the-pattern",
+      "severity": "warning",
+      "summary": "Item tags sit at the TOP of the precedence chain (site -> Wix default pattern -> user pattern -> host page -> item). Materialising a WordPress SEO title that was itself produced by a Yoast/Rank Math TEMPLATE onto every item converts an inherited value into a thousand hard overrides that the Wix user cannot undo from one place. Import per-item tags only where the source proves a genuine per-item override (see the wordpress-seo profile's `post-seo-override-signal` entity); route template-derived values to seo/seo-pattern instead."
+    },
+    {
+      "code": "custom-flag-is-not-an-override-signal",
+      "severity": "warning",
+      "summary": "`tag.custom` marks a tag as an entry from the site's Advanced/Custom Tags list ONLY. Standard tags (title, description, Open Graph) always resolve with `custom: false` even when their content came from a manually saved per-page override, so it cannot be used to verify that a manual SEO edit landed. Worse, when ResolveStaticPageSeoTags is called without `seoData` the per-page data is read only from the Vibe/managed-headless override store, which holds nothing for classic Wix Editor or Wix Studio pages - there `false` means 'this API could not tell'."
+    },
+    {
+      "code": "primary-language-only",
+      "severity": "warning",
+      "summary": "`language` is read-only on a write and sending it fails with LANGUAGE_NOT_SUPPORTED: tags can be written only for the site's primary language. Per-locale SEO meta from a multilingual WordPress source (WPML/Polylang alongside Yoast) has no import path today - ledger it."
+    },
+    {
+      "code": "unsupported-item-type-is-per-site",
+      "severity": "warning",
+      "summary": "Item types documented as examples are STATIC_PAGE, BLOG_POST and STORES_PRODUCT, plus WIX_DATA_PAGE_ITEM-{pageId} for an item on a CMS-driven dynamic page. The real list depends on which business solutions the site has, and the docs say to read it from the UNSUPPORTED_ITEM_TYPE error message rather than hard-coding it. Probe once at setup time; a WordPress taxonomy-term SEO record (category/tag/product-category, all of which carry yoast_head_json) has NO confirmed item type and must not be assumed."
+    },
+    {
+      "code": "bulk-set-silent-success-for-stores-product",
+      "severity": "blocker",
+      "summary": "[LIVE 2026-08-27, one call, dated evidence, not a permanent platform rule] POST /promote/seo/v1/bulk/item-seo-tags/set with itemType STORES_PRODUCT returned per-entry success, yet the read-back showed empty itemSeoTags.tags and every tag still resolving TAG_SOURCE_DEFAULT_PATTERN; the single-item GET returned 404. A PATCH of the product's own seoData then resolved as TAG_SOURCE_ITEM. So Stores product SEO is written only through Catalog V3 product.seoData, and wix-writers' bulkSetItemSeoTags refuses STORES_PRODUCT. Any future probe of this call must treat a success response as untrusted until an independent read-back confirms persistence."
+    },
+    {
+      "code": "historical-request-shape-traps",
+      "severity": "warning",
+      "summary": "From the same 2026-08-27 probe: per-entry fieldMask is a comma-separated string, the payload must be nested under itemSeoTags (a root-level payload returns an HTML error page), and robots values are bare tokens."
+    }
+  ],
+  "mappingGuidance": [
+    "A tag is `{type, props, children, meta, custom, disabled}` where type is one of `title` | `meta` | `script` | `link`. Title -> {type:'title', children:'<the title>'}. Meta description -> {type:'meta', props:{name:'description', content:'...'}}. Canonical -> {type:'link', props:{rel:'canonical', href:'...'}}. Open Graph -> {type:'meta', props:{property:'og:title'|'og:description'|'og:image'|'og:type'|'og:url', content:'...'}}. Twitter -> {type:'meta', props:{name:'twitter:card'|..., content:'...'}}. JSON-LD -> {type:'script', props:{type:'application/ld+json'}, children:'<the JSON>'}.",
+    "From Yoast: yoast_head_json.title -> title tag; .description -> meta description (absent when the post has none - do NOT substitute .og_description, which Yoast derives from the excerpt); .canonical -> link rel=canonical; .og_* / .twitter_* -> the matching meta tags; .robots -> {type:'meta', props:{name:'robots', content:'index, follow, ...'}}; .schema -> a script tag. See the wordpress-seo profile for which of these are genuine overrides versus computed defaults.",
+    "Focus keyphrases map to `focusKeywords[]` ({term, isMain, origin}), max 5, and are NOT rendered on the page - they only feed Wix's SEO tools. Yoast `_yoast_wpseo_focuskw` and Rank Math `rank_math_focus_keyword` land here with isMain: true.",
+    "A write is a full replacement of what the fieldMask names (`tags`, `focusKeywords`), with no revision check. Read the item first (GET /promote/seo/v1/item-seo-tags/{itemType}/{itemId}) and send the complete set; never send a partial tags array expecting a merge.",
+    "`origin` is derived from the CALLER, not the request, and is not stored - reads always return ORIGIN_UNSPECIFIED. ORIGIN_MIGRATION exists in the enum, so a migration caller Wix recognises is labelled automatically; do not try to set it.",
+    "Two roads reach the same data, and the cheaper one is usually right. Wix Blog draft posts and Catalog V3 products carry a `seoData` (SeoSchema: the same `tags[]` plus `settings.preventAutoRedirect`) field on their own create/update call, so a blog post or product imported with its SEO already attached needs NO second pass here. Use this entity for (a) item types whose create call has no seoData, chiefly STATIC_PAGE, (b) a repair/backfill pass over items already created, and (c) reading back `resolvedTags` to verify. See stores/product and blog/post.",
+    "`resolvedTags[]` (read-only) reports the tags an item is expected to render with, each labelled TAG_SOURCE_SITE | TAG_SOURCE_DEFAULT_PATTERN | TAG_SOURCE_USER_PATTERN | TAG_SOURCE_HOST_PAGE | TAG_SOURCE_ITEM. That is the only place the precedence chain is reported, and it is the right post-import check: an item whose title still resolves with TAG_SOURCE_DEFAULT_PATTERN did not receive its override. It excludes tags added by site code or apps at render time, so it is not a literal copy of the rendered head.",
+    "`hasOverride: false` does not mean the item shows Wix defaults - it may inherit from a pattern, the site tags, or the host page. Never use it as 'nothing was imported here'.",
+    "Stores products: write SEO only through product.seoData, only for proven per-field overrides or an owner's materialize choice, and read `resolvedTags` from GET /promote/seo/v1/item-seo-tags/STORES_PRODUCT/{productId} to verify: an override must resolve TAG_SOURCE_ITEM with the same value; an inherited field must have no own tag and resolve from a pattern or site setting (or not at all)."
+  ],
+  "setupRequirements": [
+    "SCOPE.PROMOTE.MANAGE-SEO (writes)",
+    "SCOPE.PROMOTE.VIEW-SEO (reads and post-import verification)",
+    "The owning items must already exist and be crosswalked (Blog posts, Stores products, static pages)"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/item-seo-tags-object",
+      "note": "object page: id format {itemType}:{itemId}, tags[] shape, focusKeywords, hasOverride, resolvedTags + TagSource enum, hostPageId, publishStatus, language, origin (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/bulk-set-item-seo-tags",
+      "note": "POST https://www.wixapis.com/promote/seo/v1/bulk/item-seo-tags/set; single itemType per call, entries 1-100, per-entry fieldMask, publish/returnEntity flags, idempotent retries, errors UNSUPPORTED_ITEM_TYPE / BULK_NOT_SUPPORTED_FOR_ITEM_TYPE, scope SCOPE.PROMOTE.MANAGE-SEO (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/set-item-seo-tags",
+      "note": "PATCH https://www.wixapis.com/promote/seo/v1/item-seo-tags/{itemType}/{itemId}; errors INVALID_FIELD_MASK / INVALID_TAGS / UNSUPPORTED_ITEM_TYPE / ITEM_NOT_FOUND (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/introduction",
+      "note": "the three-level precedence chain, full-replacement writes, no revision checking, per-site item-type coverage (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/product-object",
+      "note": "the alternative path: product.seoData is a SeoSchema (tags[] + settings.preventAutoRedirect) written on the product's own create call (read 2026-08-16)"
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-source-wordpress/plugins/wordpress-seo.json",
+      "note": "source side: yoast_head_json is the RESOLVED output, _yoast_wpseo_* registered meta is the override signal"
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "2026-08-27 (dev notes): Bulk Set Item SEO Tags for STORES_PRODUCT reported per-entry success and persisted nothing; product PATCH seoData resolved TAG_SOURCE_ITEM. Recorded as a failure observation; preferredWrite verification stays docs."
+    }
+  ],
+  "notes": "Authored 2026-08-16 with the seo domain. Docs-verified only; no live write has been exercised. This entity is the standalone road to per-item SEO; the per-entity `seoData` field on blog/post and stores/product is the cheaper road for those two types and should be preferred when the item is being created anyway (see mappingGuidance)."
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/seo/entities/seo-pattern.json

@@ -0,0 +1,91 @@
+{
+  "schemaVersion": 1,
+  "domain": "seo",
+  "entity": "seo-pattern",
+  "displayName": "SEO Pattern",
+  "capability": "content.seo-patterns",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "SEO Pattern",
+    "verifiedFqdn": null,
+    "idPolicy": "natural-key",
+    "crosswalkRequired": false
+  },
+  "sourceAliases": [],
+  "dependsOn": [],
+  "preferredWrite": {
+    "surface": "SEO Pattern V1",
+    "endpoint": "POST /promote/seo/v1/seo-patterns/{pageType}",
+    "writerId": null,
+    "verification": "docs",
+    "importSafe": true,
+    "bulk": false
+  },
+  "reliability": {
+    "status": "unknown",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "create-versus-set-is-a-real-branch",
+      "severity": "warning",
+      "summary": "POST /promote/seo/v1/seo-patterns/{pageType} fails with 409 PATTERN_ALREADY_EXISTS when the site already has its own pattern for that page type, and PATCH on the same path fails with 404 PATTERN_NOT_FOUND when it does not. `source` on the object says which is the case (the site's own pattern versus the Wix default). Read first, then branch; do not retry the other verb blindly."
+    },
+    {
+      "code": "variables-are-per-page-type",
+      "severity": "blocker",
+      "summary": "A pattern may reference only the variables its page type offers ({{product.name}} style, double braces). Anything else fails with INVALID_PATTERN, whose message lists the permitted variables. Call List SEO Pattern Variables (GET /promote/seo/v1/seo-patterns/{pageType}/variables) for the page type before translating a source template; a WordPress template variable such as %%title%% %%sep%% %%sitename%% (Yoast) or %title% %sep% %sitename% (Rank Math) has no automatic equivalent and must be mapped variable by variable, with anything unmappable resolved to a literal or ledgered."
+    },
+    {
+      "code": "page-type-availability-is-per-site",
+      "severity": "warning",
+      "summary": "UNSUPPORTED_PAGE_TYPE (400) means Wix does not recognise the page type at all; PAGE_TYPE_NOT_ON_SITE (404) means it is valid but the business solution providing it is not installed. These are different problems - the second is a setup ordering bug (install the app first), not a mapping gap. Only WIX_DATA_PAGE_ITEM supports a per-page pattern via pageId; passing pageId for any other type fails with PAGE_ID_NOT_SUPPORTED, and passing collectionName fails with COLLECTION_NAME_NOT_SUPPORTED."
+    },
+    {
+      "code": "pattern-write-is-blast-radius",
+      "severity": "warning",
+      "summary": "A pattern applies to EVERY item of its page type that has no override, so one bad write changes the title of every product or post on the site at once, with no revision check to stop a concurrent dashboard edit. `defaultPattern` is always returned so a reset target is known - record it before writing."
+    },
+    {
+      "code": "boolean-fields-cannot-be-variables-round-trip",
+      "severity": "info",
+      "summary": "A tag whose `disabled` or `custom` value is itself a variable is returned with that value UNSET (they are booleans), even though the behaviour still applies at render time. A read-modify-write round trip therefore silently drops such a variable; re-send the intended value rather than echoing what was read."
+    }
+  ],
+  "mappingGuidance": [
+    "Dependencies: no other modeled record must exist first; page types are site configuration, while a dynamic-page ID is only needed for the optional unmodeled dynamic-page case.",
+    "This is where a WordPress SEO plugin's per-post-type TITLE and META DESCRIPTION TEMPLATES belong - Yoast's Settings > Content Types templates (wpseo_titles option) and Rank Math's equivalent. Migrating those as patterns reproduces the source's SEO conventions in one write per page type instead of one write per item, which is exactly the split the Wix SEO introduction asks for.",
+    "The source side is the hard half: those templates live in wp_options, which WordPress REST does not expose, so they arrive only from a user-supplied export or by asking. No plugin profile claims content.seo-patterns today for that reason; the capability is here so the surface has an owner and the mapping is written down.",
+    "Pattern id is the page type (`{pageType}`), or `{pageType}:{pageId}` for a single Wix Data dynamic page. No crosswalk is needed for the page type itself, but WIX_DATA_PAGE_ITEM patterns need the created page's GUID.",
+    "The tag shape is identical to seo/item-seo-tags (`{type, props, children, meta, custom, disabled}`); only the values differ, in that they may contain {{variables}}.",
+    "Precedence: the site's own pattern beats the Wix default pattern, and both are beaten by the host page and the item. Import patterns BEFORE per-item overrides so that a later item write is a deliberate exception rather than an accidental duplicate of the pattern's output."
+  ],
+  "setupRequirements": [
+    "SCOPE.PROMOTE.MANAGE-SEO (writes)",
+    "SCOPE.PROMOTE.VIEW-SEO (reads, incl. List SEO Pattern Variables)",
+    "The business solution that provides each page type must be installed before its pattern is written"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/seo-pattern-object",
+      "note": "object page: id {pageType} / {pageType}:{pageId}, pattern vs defaultPattern, source, boolean-variable caveat, language is the primary language (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/set-seo-pattern",
+      "note": "PATCH https://www.wixapis.com/promote/seo/v1/seo-patterns/{pageType}; errors PATTERN_NOT_FOUND / INVALID_PATTERN / UNSUPPORTED_PAGE_TYPE / PAGE_ID_NOT_SUPPORTED / COLLECTION_NAME_NOT_SUPPORTED (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/create-seo-pattern",
+      "note": "POST same path; 409 PATTERN_ALREADY_EXISTS, 404 PAGE_TYPE_NOT_ON_SITE (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/list-seo-pattern-variables",
+      "note": "GET https://www.wixapis.com/promote/seo/v1/seo-patterns/{pageType}/variables - the only authoritative source of the variables a page type offers (read 2026-08-16)"
+    }
+  ],
+  "notes": "Authored 2026-08-16 with the seo domain. Docs-verified only. Unclaimed by any WordPress plugin profile today because the source templates are in wp_options and unreadable over REST - the honest verdict for the Yoast/Rank Math template settings is reconfigure-in-wix unless the user supplies an export, and this entity is where that reconfiguration lands if it is ever automated."
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/seo/entities/site-seo-tags.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": 1,
+  "domain": "seo",
+  "entity": "site-seo-tags",
+  "displayName": "Site SEO Tags",
+  "capability": "content.site-seo-tags",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Site SEO Tags",
+    "verifiedFqdn": null,
+    "idPolicy": "not-applicable",
+    "crosswalkRequired": false
+  },
+  "sourceAliases": [],
+  "dependsOn": [],
+  "preferredWrite": {
+    "surface": "Site SEO Tags V1",
+    "endpoint": "PATCH /promote/seo/v1/site-seo-tags",
+    "writerId": null,
+    "verification": "docs",
+    "importSafe": true,
+    "bulk": false
+  },
+  "reliability": {
+    "status": "unknown",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "site-noindex-is-writable-here",
+      "severity": "blocker",
+      "summary": "A `robots` tag with `noindex` or `none` at site level stops search engines indexing the WHOLE site. A WordPress source in staging almost always carries site-wide noindex (blog_public = 0; verified live on an anonymized verification environment 2026-08-16, where every yoast_head_json.robots reported index: noindex). Copying the source's site-level robots value across would silently de-index the new Wix site. Never carry noindex; treat indexability as a launch decision, not migrated data."
+    },
+    {
+      "code": "only-site-wide-tags-accepted",
+      "severity": "warning",
+      "summary": "Only og:image (default social share image), a site-level robots directive, search-engine verification tags (google-site-verification, msvalidate.01, p:domain_verify, yandex-verification - one per provider) and other site-wide name/content meta are valid here. A title, description or canonical belongs to a page and is rejected with INVALID_TAGS; use seo/item-seo-tags or seo/seo-pattern."
+    },
+    {
+      "code": "embed-tags-are-read-only",
+      "severity": "info",
+      "summary": "`embedTags[]` returns verification tags a Wix user added through the dashboard's SEO settings, which are stored as HTML embeds rather than as site tags. They are never included in `tags` and cannot be written here, so a read-then-write round trip does not preserve them - they simply stay where they are. Empty also when they cannot be retrieved, so an empty array is not proof there are none."
+    },
+    {
+      "code": "full-replacement-no-revision-check",
+      "severity": "warning",
+      "summary": "PATCH with a fieldMask replaces the named field in full and there is no revision check (INVALID_FIELD_MASK when the mask is empty or names an unwritable field). Read the current tags, merge, and send the complete set."
+    }
+  ],
+  "mappingGuidance": [
+    "Dependencies: no other modeled record must exist first; site SEO tags are a site-level configuration resource.",
+    "The migratable content here is thin and deliberate: the site's default Open Graph share image and the search-engine VERIFICATION tags. Everything else a WordPress SEO plugin keeps at site level - title/meta templates per post type, breadcrumb settings, social profile URLs, knowledge-graph organisation data - is either a pattern (seo/seo-pattern) or reconfigure-in-wix.",
+    "Verification tags are worth carrying because they preserve an existing Google Search Console / Bing property association across the platform switch. In WordPress they live in plugin OPTIONS (Yoast: wpseo `googleverify`/`msverify`; Rank Math: `rank-math-options-general`), which are NOT exposed over REST - they arrive only from a user-supplied export or by asking the user. Treat them as blocked: user-file, never as absent.",
+    "Site tags are the BOTTOM of the precedence chain, so anything set here is overridden by a pattern, the host page, or the item. Setting a site-wide description is not a way to give every page a description.",
+    "`language` is always empty: site SEO tags are not language specific, one set applies to every language version."
+  ],
+  "setupRequirements": [
+    "SCOPE.PROMOTE.MANAGE-SEO (writes)",
+    "SCOPE.PROMOTE.VIEW-SEO (reads)"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/site-seo-tags-object",
+      "note": "object page: supported site-wide tags (og:image, robots noindex/none, verification providers), embedTags read-only, language always empty, origin derived from caller (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/set-site-seo-tags",
+      "note": "PATCH https://www.wixapis.com/promote/seo/v1/site-seo-tags; errors INVALID_FIELD_MASK / INVALID_TAGS; scope SCOPE.PROMOTE.MANAGE-SEO (read 2026-08-16)"
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-source-wordpress/plugins/wordpress-seo.json",
+      "note": "source side: Yoast site-level settings live in wp_options and are not REST-readable"
+    }
+  ],
+  "notes": "Authored 2026-08-16 with the seo domain. No WordPress plugin profile claims content.site-seo-tags today, because the source-side values sit in plugin options that REST does not expose; the entity exists so the Site SEO Tags V1 surface has an owner and so the noindex trap is written down before someone copies it across."
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/site/docs-survey.json

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": 1,
+  "domain": "site",
+  "fetchedAt": "2026-09-01",
+  "roots": [
+    "api-reference/business-management/site-properties"
+  ],
+  "surfaces": [
+    {
+      "id": "api-reference/business-management/site-properties/properties",
+      "title": "Properties",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/site-properties/properties",
+      "group": null,
+      "verdict": "claimed",
+      "refs": [
+        "site/business-contact"
+      ],
+      "reviewedOn": "2026-09-01",
+      "note": "Business Contact is authored. Profile (display name, business name, logo, description), Schedule, Region and Consent Policy are real siblings on the same API with no entity yet -- each needs its own source mapping before it is worth authoring."
+    },
+    {
+      "id": "api-reference/business-management/site-properties/skills",
+      "title": "Skills",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/site-properties/skills",
+      "group": null,
+      "verdict": "gap",
+      "reviewedOn": "2026-09-01",
+      "reason": "Holds 'Change Payment Currency (Site Properties)' and 'Site Settings Dashboard Navigation'. The currency one is a REAL uncovered need: a source store declares its own currency (WooCommerce: woocommerce_currency in the general settings group) and nothing in this pipeline reads or applies it, so a migrated site can price in a currency the merchant never chose. No entity authored yet; the source-side read is itself not part of the default discovery sweep.",
+      "tracking": "site/business-contact covers the address half of this group; the store's declared CURRENCY is captured by rp-source-wordpress/scripts/capture-store-settings.js and reported at the setup gate, but nothing WRITES it — Change Payment Currency has no entity yet. Awaiting a decision on whether a migration should set a site's currency at all."
+    }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/site/domain.json

@@ -0,0 +1,49 @@
+{
+  "schemaVersion": 1,
+  "domain": "site",
+  "dependsOnRequired": true,
+  "displayName": "Wix Site Properties",
+  "ownerHint": "Site Properties domain owners (Business Info: profile, contact, schedule, region, consent policy)",
+  "wixAppsRequired": [],
+  "docsRoots": [
+    "api-reference/business-management/site-properties"
+  ],
+  "defaultImportOrder": [
+    "business-contact"
+  ],
+  "sharedPitfalls": [
+    {
+      "code": "field-mask-clears-what-it-lists-but-you-did-not-send",
+      "severity": "blocker",
+      "summary": "Every Site Properties update takes a `fields.paths[]` mask, and its semantics are DESTRUCTIVE in one direction: a property named in `fields.paths` but absent from the payload object is CLEARED, not left alone. Only properties absent from `fields.paths` are ignored. So the mask must list EXACTLY the properties actually being sent -- never a convenient superset, and never a copy of a documentation example's list. Wix's own Update Business Contact example demonstrates the hazard rather than the safe pattern: it passes paths ['phone','fax','email','address','businessSchedule'] while sending no businessSchedule, which by the documented rule wipes the site's business hours. Build the mask FROM the payload's own keys, never alongside it."
+    },
+    {
+      "code": "updates-return-an-empty-body-so-read-back-is-a-separate-call",
+      "severity": "warning",
+      "summary": "Update Business Contact (and its sibling updates) return `{}` -- no echo of what was stored, no revision. A successful write proves only that the request was accepted. To verify anything actually landed, call GET /site-properties/v4/properties separately and compare. This matters more than usual here because the field mask above can silently clear a field on the same call that successfully sets another."
+    },
+    {
+      "code": "site-properties-is-not-versioned-by-revision",
+      "severity": "info",
+      "summary": "Unlike most Wix entities, these calls take no `revision` and cannot 409 on a concurrent write. Two writers updating different properties will not conflict, but two writers updating the SAME property silently last-write-wins. Read before writing when a value may already be set by the merchant or by an earlier phase of the run."
+    },
+    {
+      "code": "a-site-can-legitimately-have-no-business-address-at-all",
+      "severity": "info",
+      "summary": "LIVE-OBSERVED: GET /site-properties/v4/properties on a fresh site returned only locale/currency/timezone with no business address key present at all -- an absent address is the normal starting state, not an error or a partially-migrated one. Treat 'no address' as 'nothing written yet' and never infer from its absence that a write failed."
+    }
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/site-properties/introduction",
+      "note": "Site Properties is the single source of truth for the site's public business information; the merchant edits the same values in the dashboard under Settings > Business Info"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/introduction",
+      "note": "the five property groups: Profile, Contact, Schedule, Region, Consent Policy"
+    }
+  ],
+  "notes": "Authored to give the business address a real home. It had been an unowned gap: a migrated site published with an empty address field, and the pickup-location entity needed an address the pipeline had no target for. Only `business-contact` is authored so far -- Profile (site display name, business name, logo, description), Schedule, Region (locale, currency, timezone) and Consent Policy are real siblings on the same API and are the obvious next entities, but each needs its own source mapping before it is worth authoring."
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/site/entities/business-contact.json

@@ -0,0 +1,103 @@
+{
+  "schemaVersion": 1,
+  "domain": "site",
+  "entity": "business-contact",
+  "displayName": "Site Business Contact",
+  "capability": "site.business-contact",
+  "target": {
+    "classification": "setup-config",
+    "nativeEntity": "BusinessContactData",
+    "verifiedFqdn": null,
+    "idPolicy": "not-applicable",
+    "crosswalkRequired": false
+  },
+  "dependsOn": [],
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "settings.general",
+      "routes": [
+        "/wc/v3/settings/general"
+      ],
+      "confidence": "high",
+      "note": "The store's own address lives in the general settings group as woocommerce_store_address / _address_2 / _city / _postcode / woocommerce_default_country. Two traps: the REST index advertises only the PARAMETERIZED form /wc/v3/settings/(?P<group>...), so the group must be read directly; and the WooCommerce consumer key 401s here while the WordPress application password succeeds. See rp-source-wordpress's SKILL.md."
+    }
+  ],
+  "preferredWrite": {
+    "surface": "Site Properties",
+    "endpoint": "POST https://www.wixapis.com/site-properties/v4/properties/business-contact",
+    "writerId": "updateBusinessContact",
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": false,
+    "releaseStatus": "stable",
+    "decision": "A site-wide singleton, applied at the setup gate as configuration -- not a per-record import. Permission SITE_PROPERTIES.UPDATE_BUSINESS_CONTACT, scope SCOPE.DC-SITEPROP.MANAGE-BUSINESS-CONTACT. Read back with GET /site-properties/v4/properties, which is a separate call because the update returns an empty body."
+  },
+  "reliability": {
+    "status": "reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "listing-a-field-you-do-not-send-clears-it",
+      "severity": "blocker",
+      "summary": "`fields.paths[]` is destructive in one direction: a property NAMED in the mask but ABSENT from `businessContact` is CLEARED. Migrating only an address therefore means sending paths ['address'] and nothing more -- adding 'email','phone','fax' to be thorough wipes contact details the merchant may already have entered by hand. Build the mask from the payload's own keys. Wix's own documented example is itself unsafe to copy: it lists 'businessSchedule' in paths while sending none."
+    },
+    {
+      "code": "state-is-a-bare-subdivision-and-the-source-encodes-it-in-the-country-field",
+      "severity": "warning",
+      "summary": "Wix takes `country` (ISO 3166-1 alpha-2) and `state` as separate fields. WooCommerce packs both into one setting: `woocommerce_default_country` is either `IL` or `COUNTRY:STATE` (e.g. `US:CA`). Split on the colon -- the same encoding a WooCommerce shipping zone's `state`-type location uses, so shipping-build.js already carries the parse. Sending `US:CA` as `country` does not error; it just stores a country code that matches nothing."
+    },
+    {
+      "code": "street-is-free-text-do-not-parse-a-house-number-out-of-it",
+      "severity": "warning",
+      "summary": "The object has separate `street` and `streetNumber` fields, which invites splitting the source's single address line. Do not. WooCommerce's `woocommerce_store_address` is one free-text field with no structure guarantee -- some shops put the number first, some last, some have no number at all (a store address can be a street name only). Put the whole source line in `street`, leave `streetNumber` empty, and let the merchant correct it. A wrong split is worse than no split: it looks deliberate."
+    },
+    {
+      "code": "zip-has-a-20-character-limit-the-source-does-not",
+      "severity": "warning",
+      "summary": "`zip` is capped at 20 characters; WooCommerce's `woocommerce_store_postcode` is unbounded free text. Guard the length rather than letting the API reject the whole write for one long field."
+    },
+    {
+      "code": "update-returns-nothing-so-success-is-not-evidence",
+      "severity": "warning",
+      "summary": "The response body is `{}`. A 200 proves the request was accepted, not that the address is stored as intended -- and given the clearing behaviour above, a call can succeed while having wiped a sibling field. Always follow a write with GET /site-properties/v4/properties and compare what came back. CONFIRMED LIVE 2026-09-01: an address-only write returned {} and the follow-up read showed the address stored exactly as sent, with the site's other contact fields untouched."
+    },
+    {
+      "code": "coordinates-and-google-formatted-address-have-no-source",
+      "severity": "info",
+      "summary": "`coordinates` and `googleFormattedAddress` are real fields with no WooCommerce counterpart. Omit them rather than geocoding: a migration that silently invents a latitude/longitude is asserting a precision the source never had. Wix resolves display formatting itself."
+    }
+  ],
+  "mappingGuidance": [
+    "Field map: woocommerce_store_address -> street (whole line, unparsed); woocommerce_store_address_2 -> apartmentNumber; woocommerce_store_city -> city; woocommerce_store_postcode -> zip (truncate-guard at 20); woocommerce_default_country -> country, plus state when the value is COUNTRY:STATE. Set isPhysical true -- a shop's registered address is a real place. Omit coordinates and googleFormattedAddress.",
+    "Send `fields.paths` built from the keys actually present on the payload, never a fixed list. See this file's first pitfall; it is the one mistake here that destroys data rather than failing loudly.",
+    "This is the site's OWN address. It is NOT a pickup address, and must never be used as one without a human confirming it -- a shop's registered address and the place customers collect from are routinely different (they can sit in different towns). ecom/pickup-location may OFFER this value as a default to confirm; it may not adopt it.",
+    "Apply at the setup gate with the other configuration, and read back afterwards. An absent business address on the destination is the normal starting state, not evidence of a failed earlier write."
+  ],
+  "setupRequirements": [],
+  "objectPageException": "Site Properties is modelled as a property stream with per-group update methods rather than as a fetchable object with its own '…-object' reference page; the API-reference tree exposes Update Business Contact / Profile / Schedule / Consent Policy and a single Get Properties read, with no object page for BusinessContactData. The field shape here is taken from the Update Business Contact method schema.",
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/update-business-contact",
+      "note": "full request schema: businessContact.address fields (street, streetNumber, apartmentNumber, city, state, country, zip maxLength 20, hint, isPhysical, googleFormattedAddress, coordinates), the fields.paths mask semantics, the empty response body, permission and scope names"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/introduction",
+      "note": "Site Properties as the single source of truth for the site's public business information"
+    },
+    {
+      "type": "live-verification",
+      "path": "anonymized-live-verification",
+      "note": "GET /site-properties/v4/properties on a fresh site returned only locale/currency/timezone with no business address key present"
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "2026-09-01: a site whose business address was entirely blank (street/city/zip empty, isPhysical false) was populated by an address-only update. Read-back matched the payload field for field; email and phone were absent before and after, confirming the derived field mask cleared nothing."
+    }
+  ],
+  "notes": "Authored 2026-09-01 to close an unowned gap: nothing in the pipeline had ever written a business address, so every migrated site published with the field empty, and ecom/pickup-location needed an address with no target entity to point at. Write path VERIFIED LIVE the same day against a site whose address was blank."
+}