# Rp Target Wix

> Wix target adapter with verified write primitives, shared execution runtimes, and contract tests. Use when vendoring Wix writers, validating API shapes, or Wix provisioning mechanics.

- Skill: `wix/rp-target-wix` (Agent Skill, multi-file: 116 files)
- Install (CLI): `npx skillmds@latest add wix/rp-target-wix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wix/rp-target-wix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: wix (https://skillmd.com/u/wix)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/wix/rp-target-wix

---


# rp-target-wix

Wix **target adapter**. Owns the Wix-side write surface and shared execution runtime that every migration shares —
verified once here so the platform-agnostic stages and per-project codegen never
re-derive (and re-break) it. This is the symmetric counterpart to `rp-source-wordpress`:
that adapter owns *reading* a source platform; this one owns *writing* to Wix.

## When this skill is used

Not a stage in the flow — a reference + shared library consulted by:

- **`rp-import-codegen`** vendors `lib/wix-writers.js` into the project (like the
  `wp-http` transport) plus the shared write/setup runtime modules, and generates thin
  project-specific write specs/transforms that **call these primitives/runtime APIs**.
  Codegen does not re-emit Wix API plumbing.
- **`rp-setup-discovery` / `rp-execute-setup`** consult the "Verified endpoints" and
  "Provisioning" notes for app-install / Wix-Data / collection mechanics.

Because the Wix surface is identical across source platforms, adding a new source
(`rp-source-shopify`, …) requires **no change here**.

## Shared runtime boundary

This adapter owns the **shared Wix layer** written once for all migrations.

It should own:

- verified request builders and endpoint primitives
- shared Wix client/auth handling
- shared retry and throttling policy
- generic write execution runtime
- generic setup execution/runtime behavior
- checkpoint helpers
- local crosswalk helpers (`state/crosswalk/crosswalk.ndjson` authority, append-only
  attempt journal, optional CMS mirror seed/upload adapters)
- URL preservation helpers (`state/url-preservation/` base paths, ledger, planned
  redirects, and unresolved route rows)
- NDJSON record-stream I/O (`lib/ndjson.js`): streaming read/write, batching by count and by
  cost, cursoring, and append-only producers. Migration data files are record streams, so the
  scan/batch/cursor primitives live here once instead of being re-derived by codegen.
- audit log emission
- compact execution report generation
- contract tests for stable request/runtime behavior

Per-migration code generation should own only:

- field maps
- transforms
- write specs
- setup-plan renderings
- entity ordering
- dependency wiring — populate `WriteSpec.dependencyRefs` from each in-scope entity's
  domain-knowledge `dependsOn` field (spec 0041), not re-derived per project

## Write contract (the verified Wix surface)

`lib/wix-writers.js` exposes pure request builders (`build*Request`) + executors. Shapes
marked **VERIFIED** were validated by a real call against a live site, not just read from
docs. Shapes marked **UNVERIFIED** are docs-schema/MCP-derived bootstrap primitives that
must be surfaced in execution plans until a live contract call promotes them. It also
exports `sendDirectRest` and `notifyMissingWriter` for generated native REST paths when
Wix has a native entity but this adapter does not yet ship a dedicated primitive.

This resource should also expose shared execution-runtime modules above those primitives,
so generated migrations use one common path for retries, throttling, checkpointing,
reporting, and audit logging.

**Read/return contract for `query*` executors.** Every `query*` executor
(`queryStoresProducts`, `queryStoresCategories`, `queryContacts`, `queryCoupons`,
`queryOrders`) **unwraps the response to the entity array and returns one page**, discarding
`pagingMetadata`. Two failure modes follow, both of which have shipped:

- **The return value IS the array.** Reading `.products` / `.categories` off it a second time
  gives `undefined` → `[]`. A dedupe index or existing-entity safety net then comes back
  empty *without erroring*, which is indistinguishable from a fresh site — so the import
  duplicates what is already there, and a setup verification reports 0 categories on a site
  with 25.
- **These executors cannot be cursor-paged**, because the cursor is in the metadata they
  discarded. Use a `queryAll*` primitive where one exists — `queryAllStoresCategories`,
  `queryAllStoresProducts`, `queryAllDataItems` — otherwise send
  `wix.send(build<X>Request(body))` and read `pagingMetadata.cursors.next` off the raw
  response.

Every sweep used for dedupe must **throw on a partial result rather than return it**. "Empty
net" and "empty store" look identical to the caller, and the caller assumes the second.

## Domain entity suitability knowledge

Target entity suitability lives in `domains/`, not in a large prose table in this skill.
Use the deterministic reader as the normal access path:

```bash
node scripts/domain-knowledge.js list-domains
node scripts/domain-knowledge.js list-entities --domain stores
node scripts/domain-knowledge.js read-entity --ref stores/product
node scripts/domain-knowledge.js resolve-source --source-system woocommerce --source-entity product
node scripts/domain-knowledge.js resolve-source --route /wc/v3/products
node scripts/domain-knowledge.js list-flagged --flag IMPORT_UNRELIABLE
node scripts/domain-knowledge.js summarize-entities --refs stores/product,ecom/order
```

`domains/index.json` is generated from domain/entity files and checked in. After editing
domain knowledge, run:

```bash
node scripts/domain-knowledge-validate.js --write-index
```

**Authoring or editing any entity file also requires the spec 0041 dependency check**, both
directions: (1) what does *this* entity need to already exist and be crosswalked — record it in
`dependsOn: string[]` (a `domain/entity` ref array; empty is a real, reviewed answer, not the same
as the field being absent); (2) does this entity change what an *already-written* entity's
`dependsOn` should say (e.g. authoring `gift-cards/gift-card` should have prompted revisiting
`ecom/order.json` — it hadn't, until spec 0042 caught it by hand). `domain-knowledge-validate.js`
checks `dependsOn` refs resolve and the whole graph stays acyclic whenever the field is present, but
it is not yet required on every entity — `node scripts/domain-knowledge-validate.js
--list-missing-deps` prints the live backlog of entities that have never had it authored at all;
that command is the source of truth, not a hand-maintained list.

`writerId` values in entity files must match exported functions from `lib/wix-writers.js`;
use `null` for direct REST plans, setup/manual work, or unsupported native gaps.

Entity files may also expose `fieldContracts[]` for verified nested write paths. These
are machine-readable contracts for codegen and dry-run validators, not replacements for
the human notes below. For Stores products, `domains/stores/entities/product.json`
records the verified Catalog V3 create contract for `product.subscriptionDetails`,
including required nested paths, allowed recurrence values, read-back behavior, and the
live-validated `subscriptions[].description <= 60` constraint. Generated transforms
should consume that metadata through the vendored `wix-writers.js` exports instead of
copying limits into project-local code.

Live verification helpers must not edit `domains/` directly. When a probe changes a
target write assumption, emit a proposal artifact and let the orchestrator promote it
deliberately:

```bash
node skills/wix-replatform/resources/rp-target-wix/scripts/verify-stores.js stores subscription-create \
  --artifact migrations/<project>/setup/stores-subscription-verification.json \
  --proposal-artifact migrations/<project>/setup/contract-ledger-proposal.json
```

Use `lib/contract-ledger.js` to validate the handoff: a passed verification without a
proposal is incomplete, and a proposal that is neither promoted into `fieldContracts[]`
nor explicitly deferred is stale product knowledge. Codegen should consume
`fieldContracts[]` through `scripts/domain-knowledge.js summarize-entities`, which
includes promoted contracts.

| Capability | Endpoint | Notes / traps |
| --- | --- | --- |
| HTML → rich content | `POST /ricos/v1/ricos-document/convert/to-ricos` | VERIFIED. `options.plugins` enum is **UPPERCASE** — the docs example shows lowercase and 400s. |
| Import media from URL | `POST /site-media/v1/files/import` | VERIFIED. **Async**: response is `PENDING`; poll `GET /site-media/v1/files/{id}` for `READY` before referencing. |
| Blog category | `POST /blog/v3/categories` | VERIFIED. body `{ category: { label, slug, description } }`. |
| Blog tag | `POST /blog/v3/tags` | VERIFIED. Body is **top-level `{ label, language }`** — NOT `{ tag: { label, slug } }`; slug is derived. |
| Blog post | `POST /blog/v3/draft-posts` → `…/{id}/publish` | VERIFIED. `memberId` **required** (3rd-party). VERIFIED (2026-08-02): the **site owner's auto-created user-member** satisfies it — it was already present on our API-provisioned test site with zero Members-area interaction (single-site observation), so attribute-to-owner needs no member provisioning. **Resolve it via `listMembers` + `loginEmail` match — never derive it from the account/user GUID** (the observed id equality is n=1 on a solo account, undocumented). Also VERIFIED (2026-08-02): author is **re-assignable after publish** — `PATCH /blog/v3/draft-posts/{id}` `{ draftPost: { memberId } }` then republish updates the published post's author (post id == draft id; republish fires non-suppressed events — do author-upgrade passes inside the notification-mute window). Visible custom cover media requires **both** `heroImage.id` and `media: { displayed:true, custom:true, wixMedia:{ image:{ id }}}`. `heroImage.id` alone leaves the cover hidden. |
| Blog posts (bulk) | `POST /blog/v3/bulk/draft-posts/create` | UNVERIFIED bootstrap (public docs + wix/skills `wix-manage` recipe, 2026-07-21). Max **20 posts/call**; `bulkCreateDraftPosts` chunks larger inputs. Prefer over per-post creates for N ≥ 2 (single create runs ~25–30s/call per the recipe). Publish is still per-post — a bulk `publish` flag is unverified. Surface in the execution plan until the live contract call promotes it. |
| CMS item | `POST /wix-data/v2/items` | VERIFIED. `{ dataCollectionId, dataItem: { data } }`. Requires Wix Data enabled (else `WDE0110`). |
| Members | `GET`/`POST /members/v1/members` | VERIFIED. dedup by `loginEmail` (gated PII; use a fallback member when absent). VERIFIED (2026-08-02, single-site observation): the target-site member list can already contain **auto-created user-members** for the owner/contributing Wix users (`status: APPROVED`; resolve by `loginEmail`, never by deriving from the account GUID — the observed id equality is undocumented) — never dedupe or count these against source-site members; `DELETE /members/v1/members/{id}` works for cleaning up importer-created members. Throughput: **no bulk create; documented ≥1s spacing** (10k ≈ 3h serial floor — plan + resume via crosswalk). Create sends **no email** and does **not** fire the signup automations trigger (source-confirmed) — silent by default. **Activation policy (decided 2026-08-03): passwords are never imported, and passwordless members complete the standard forgot-password flow (confirmed).** Delivery = post-import **label-wave automation**: owner creates one dashboard automation (trigger `label added`, e.g. `migrated-2026` → owner-branded email: "Log in → Forgot password"); importer applies the label via API in batches for rate control/re-targeting; enable only after the import window (AUTO-02 pause). **Never mass-send** `send-set-password-email` (3h single-use link), and never fetch/store per-member reset links — they are credential-equivalent secrets and the no-link flow needs none. |
| Stores product (BULK — the scale path) | `POST /stores/v3/bulk/products-with-inventory/create` | UNVERIFIED bootstrap. **Use this, not per-product creates, for any catalog above a handful** — 1000 products is 11 calls instead of 1000. Creates up to 100 products with inline options, inline brand/ribbon/infoSections, all variants AND per-variant inventory items in one request. **Five caps apply simultaneously and exceeding ANY ONE rejects the whole request:** products ≤100, `variantsInfo.variants` ≤1000 total, `options` ≤100 total, `modifiers` ≤100 total, `infoSections` ≤100 total. With 2 options per product the options cap binds at **50** products, not 100 — so batch with `lib/ndjson.js` → `readBatchesByLimits` using the exported `BULK_PRODUCT_LIMITS` + `storesProductBulkCost`, never on record count alone. **TRAP: bulk is NOT atomic** — a `200` can carry per-item failures in `results[].itemMetadata.success`; never infer success from the HTTP status. **TRAP: correlate results by `itemMetadata.originalIndex`**, not response position. **TRAP: `bulkActionMetadata.undetailedFailures`** counts failures whose detail the server dropped; ignoring it silently loses records. `returnEntity:false` (default) still returns `itemMetadata.id`, which is all a crosswalk needs — pass `true` only for a contract probe that must inspect the created entity. `bulkCreateStoresProductsWithInventory` handles normalization, correlation and the unaccounted-item check, returning `{ results, succeeded, failed, undetailedFailures, unaccounted }`. Normalization is purely local — HTML descriptions travel as `plainDescription` for Wix to convert server-side — so a batch is **one** HTTP call. It used to convert one description per product first, which made a 100-product batch 101 calls and reliably tripped the Ricos endpoint's 403 throttle. |
| Stores product | `POST /stores/v3/products`, `POST /stores/v3/products/query`, `PATCH /stores/v3/products/{id}`, `GET /stores/v3/products/{id}`, `GET /stores/v3/products/slug/{slug}` | VERIFIED (2026-07-05; media patch verified in migration-20260715-01). `buildCreateStoresProductRequest` runs `normalizeStoresProductV3`, which bakes in the create traps: PHYSICAL requires `physicalProperties:{}`; simple/V1-ish top-level `price`, `sku`, and physical properties are moved into a single V3 variant; option/variant choice names clamped to 50 (identical truncation both places); variant `optionChoiceNames.renderType` defaulted to `TEXT_CHOICES`; `compareAtPrice` dropped unless strictly > `actualPrice`; variant `price` must be a **money object** (`{ actualPrice: { amount: "14.95" } }`) — a bare string/number 400s "Expected an object" (verified 2026-07-19), so the normalizer coerces scalar prices. **Descriptions:** a string `description` is HTML and is moved to **`plainDescription`** by `normalizeStoresProductV3`; Wix converts that to rich content server-side, so the product path never calls the Ricos endpoint (`description` proper is a Ricos document *object* — HTML there is a type error). **TRAP: `plainDescription` is silently ignored when `description` is also set** — a 200 with an empty description — so the normalizer throws when both are present. **TRAP: hard cap of 16,000 characters** (the old Ricos path chunked at 28k and merged, so it was effectively unbounded); over-long bodies throw rather than truncate, and need an info section or an explicit `mapping-gaps.json` entry. For product media, prefer `media.itemsInfo.items[]` with external `url` values when the source URLs are publicly reachable: the Stores product API ingests them in the background, avoiding the slower, heavily-throttled Media Manager pre-import path. Use pre-imported Wix media ids only when the target flow requires them. **Upsert lookups:** `getStoresProduct(wix, id)` and `getStoresProductBySlug(wix, slug)` return the product or throw 404 — callers should catch and treat as `null` for "not found". **Catalog sweeps:** `queryStoresProducts` returns **one page** unwrapped to the array with the cursor discarded, so a crosswalk-recovery or name-match safety net must use **`queryAllStoresProducts(wix)`**, which follows the cursor and throws rather than returning a partial index. **Slugs:** sanitizing is owned by `lib/wix-build.js` (`toWixSlug`, applied automatically via the `coerce: 'slug'` rule on `product.slug`), not by this module and deliberately not by `normalizeStoresProductV3` — the writer passes the caller's slug through unchanged so URL preservation can record the original next to the derived `plannedTargetSlug`. It matters because Wix rejects anything outside `[a-z0-9-]` and slug validation precedes application, so one bad slug (Shopify mints `ph-5_5` from a "pH 5.5" title) 400s the entire bulk batch rather than just that product. **General patch:** `patchStoresProduct(wix, { productId, revision, ...fields })` applies `normalizeStoresProductV3`, so a string `description` moves to `plainDescription` here too; `revision` from the existing product is required. UNVERIFIED for get-by-id, get-by-slug, and general-field patch (endpoint VERIFIED; arbitrary-field patching and slug lookup not yet live-tested). **Variable products / variant matrices:** Wix Stores V3 requires server-assigned `optionChoiceId` GUIDs before a variant matrix can be built — those IDs do not exist until after the initial `createStoresProduct` call returns. A single-pass import therefore cannot create a full variant matrix in one call. The two-pass approach: (1) create the product with options declared (but no variants), (2) create each option choice via `POST /stores/v3/products/{id}/options/{optionId}/choices` to obtain server-assigned choice IDs, (3) create variants via `POST /stores/v3/products/{id}/variants`. When the two-pass flow is out of scope (e.g. public-data single-pass run), import as a single-variant product at the base price, record the fidelity loss in `mapping-gaps.json`, surface it in the execution-plan report, and ensure the generated product detail page renders `productOptions` when non-empty so the storefront is ready once options are added. |
| Stores category | `POST /categories/v1/categories`, `POST /categories/v1/categories/query` | VERIFIED (2026-07-05) for create. Body `{ category, treeReference }` — `treeReference` is **top-level** (sibling of `category`, `{appNamespace:"@wix/stores"}`); nesting it 400s "treeReference must not be empty". Empty optional strings such as `description: ""` are omitted. **Query:** same top-level `treeReference` trap applies. `queryStoresCategories(wix)` returns **one page (100 max)** unwrapped to the array — it does **not** return all categories, and the unwrap discards the cursor so it cannot be paged. Any dedupe/upsert index must use **`queryAllStoresCategories(wix)`**, which follows `pagingMetadata.cursors.next` and throws rather than returning a partial index. Observed 2026-07-29: a site with 119 categories read back as 100 through the single-page call, which would have duplicated the missing 19. UNVERIFIED for query (not yet live-tested). |
| Wix Tag (global) | `POST /tags/v1/tags` | UNVERIFIED bootstrap. Body `{ tag: { name, fqdn } }`. FQDN for Stores V3 products: `"wix.stores.catalog.v3.product"`. Max 100 tags per FQDN. Create tags before products; crosswalk tag IDs into product `tags.publicTags.tagIds[]` at create time. Tags are a native Wix entity — do not route product tags to CMS. |
| Stores inventory item | `POST /stores/v3/inventory-items` | UNVERIFIED bootstrap. `{ inventoryItem: { variantId, productId, inStock: true } }` marks a variant as in-stock at the default location (omit `locationId`). Inventory items are **not** auto-created on product create — call this for each variant after `createStoresProduct`. For quantity-tracked stock use `{ quantity, trackQuantity: true }` instead of `inStock`. `setProductVariantsInStock(wix, { productId, variantIds })` is a convenience wrapper that calls `createInventoryItem` for each variant. Requires permission scope `SCOPE.STORES.INVENTORY_ITEM_WRITE`. |
| Stores category membership | `POST /categories/v1/bulk/categories/add-item` | VERIFIED (2026-07-05). `{ item:{ catalogItemId, appId }, categoryIds[], treeReference }`; `appId` = Wix Stores `215238eb-…`, `catalogItemId` = Wix product id. |
| Contacts | `POST /contacts/v5/contacts`, `POST /contacts/v5/bulk/contacts/upsert`, `POST /contacts/v5/contacts/query`, `GET /contacts/v5/contacts/{id}`, `PATCH /contacts/v5/contacts/{id}` | **GA** (docs verified 2026-08-04 — was Developer Preview when selected on 2026-07-26). Do not fall back to V4 unless a migration explicitly chooses a legacy compatibility path. **The GA contact shape is FLAT** — no `info` wrapper, no `emails.items`/`phones.items` list wrappers: one main `email`/`phone` (contact matching + subscription status live on these) plus `additionalEmails`/`additionalPhones` arrays; `addresses[]` keeps postal fields **nested under `address`**; `company` is `{ name, jobTitle }`. Create and update both take `{ contact, allowDuplicates }`; update requires the current `revision` and has **no fieldMask**. Phone tags: `OTHER`/`MAIN`/`HOME`/`MOBILE`/`WORK`/`FAX` (no `UNTAGGED`). `buildCreateContactRequest`/`buildUpdateContactRequest` accept the flat GA `contact` (legacy `info` payloads convert strictly — non-mechanical keys like `extendedFields`/`labelKeys` throw). Live create/query/update verification is still pending a token with Contacts permissions (2026-07-26 probe got `403`) — keep V5 writers surfaced as UNVERIFIED in execution reports until a live contract test promotes them. **Custom fields (GA):** the V5 contact carries `extendedFields.namespaces.<ns>`; per the V5 contact-object docs, definitions go through the **Data Extension Schema API with FQDN `wix.contacts.*.contact`** (user-defined values under `_user_fields`). The V4 Contacts Extended Fields API (`POST /contacts/v4/extended-fields`, values under `info.extendedFields`) pairs with the V4 surface only — do not mix. CAVEAT: the Data Extension Schema intro's supported-objects table does not list contacts yet (docs inconsistency at GA cutover); verify the DES path live during setup before relying on it. **Labels → tags:** V5 exposes `tags.privateTags.tagIds[]` managed via the Tags API (same FQDN); V4 label APIs and the `labels_added` automation trigger are a V4-surface concept — resolve the tag/label story during setup before planning post-import label waves through V5 writers. |
| Coupons | `POST /stores/v2/coupons`, `POST /stores/v2/coupons/query` | UNVERIFIED bootstrap. Prefer native Wix coupons because Wix has a native coupon entity; do not special-case coupons into CMS merely for caution or because scoping must be mapped. Fallback is only for source semantics with no native representation. |
| eCom order | **`POST /ecom/v1/orders/import`** (historical orders), `POST /ecom/v1/orders/query`, `POST /ecom/v1/orders/{orderId}/activities/add` | **VERIFIED LIVE** (2026-08-12 reference-store run; re-verified 2026-08-16 with applied discounts, line-item description lines and merchant notes). Import Order is the only import-safe path — see `ecom/order.json`. **`POST /ecom/v1/orders` (createOrder) remains BLOCKED for migration**: it decrements inventory, emails the buyer and auto-creates contacts. TRAP: `order.number` must be numeric — a prefixed source number fails the whole call with a bare `400 {"message":"Not a numeric value"}` and no field path. |
| Site notifications mute | `POST /notification-preferences/v1/site-mute/mute`, `POST /notification-preferences/v1/site-mute/unmute`, `GET /notification-preferences/v1/site-mute` | VERIFIED (2026-08-04, full cycle live on a test target: mute → state read → idempotent re-mute → unmute → state restored, all 200). Spec 0012. Mutes **all** notifications of the site in context — all recipients, all channels; sendability denied regardless of recipient-level preferences. All three calls return `{ siteMuteState: { muted, reason?, mutedBy: { wixUserId } } }`; executors unwrap to `siteMuteState`. Mute body `{ reason?: string }` (≤500, clamped by the builder) — always pass a project-identifying reason (`RePlatform migration — <project>`) so the mute is auditable. **TRAP: re-mute overwrites `reason`** (last caller wins) — the import preflight's idempotent re-call must pass the same reason as setup. **AUTH TRAP: user tokens only** — the CLI-minted `OauthNG` site token (`WIX_AUTH_TOKEN` from `config/wix.env`) works; an account API key gets a uniform empty-body 403 on all three endpoints. Hard invariant: when mute is in effect (always for `WIX_SITE_STRATEGY=new`; explicit opt-in for existing sites), a failed mute halts the run before any import write — no degraded mode. `unmuteSiteNotifications` is **never called by the flow itself** — explicit owner request only; after an on-request unmute, confirm `muted: false` via `getSiteMuteState`. |
| Direct native REST | any Wix REST path derived by codegen | UNVERIFIED generated path for native Wix entities missing a dedicated adapter writer. Must log, call `notifyMissingWriter`, and be shown in the execution plan. |

## Safe-mode contact replacement

`lib/wix-writers.js` exports the shared safe-mode runtime:

```js
createSafeModeConfig(env)
mockEmailForEntity(entityType, entityId)
sanitizeContactFieldsForSafeMode(value, options)
sanitizeWixRequestBody(body, options)
```

Generated imports must pass `safeModeOptions` to writer builders/executors when
`SAFE_MODE` is enabled. Request builders sanitize a copied request body before returning
it and throw `SafeModeBlockedError` before any send when suspicious non-replaced email
values remain.

Safe-mode replacement paths use deterministic request-body paths with object fields,
array wildcards, and Wix wrapper arrays, for example:

```text
contact.email.email
contact.additionalEmails[].email
contact.phone.phone
order.billingInfo.email
dataItem.data.submissions[].email
```

Replacement only touches primitive leaf values — a generic path that lands on an object
(such as the GA Contacts V5 `email` object) is skipped rather than clobbered, and any raw
email left inside a skipped object still trips the suspicious-value block.

Target domain entity files may define `safeModeContactFields[]` with `{ kind, targetPath,
source, notes }` entries. Mapper/codegen must merge those target hints with source-side
contact evidence and user mappings, then pass resolved request-body paths to the shared
writers.

### Stores subscription validation

`lib/wix-writers.js` exports the Stores subscription contract and deterministic helpers:

- `STORES_SUBSCRIPTION_CONTRACT`
- `normalizeStoresProductSubscriptions`
- `validateStoresProductSubscriptionDetails`

Generated import code should call the normalizer from product transforms and the
validator during dry-run and immediately before live create. Validation failures are
record-level preflight failures/deferred outcomes; do not send known-invalid
subscription payloads to Wix to discover field errors live.

Catalog V3 subscriptions are a native Stores target, not an automatic CMS fallback or
semantic loss. Product create with `subscriptionDetails.allowOneTimePurchases` and
`subscriptions[]` entries containing `title`, `description`, `frequency`, `interval`, and
`autoRenewal` was verified live on 2026-07-26 in the nopong migration; Wix returned
server-assigned subscription option ids. Mapping/codegen should emit native recurring product
creates when the source cadence is known. General subscription patching remains unverified.

### Stores live verification helpers

Use the shared Stores verification CLI for live target checks that would otherwise become
migration-local snippets:

```bash
node skills/wix-replatform/resources/rp-target-wix/scripts/verify-stores.js stores subscription-create \
  --artifact migrations/<project>/setup/stores-subscription-verification.json \
  --proposal-artifact migrations/<project>/setup/contract-ledger-proposal.json
node skills/wix-replatform/resources/rp-target-wix/scripts/verify-stores.js stores product-count \
  --artifact migrations/<project>/execution/stores-product-count-verification.json
node skills/wix-replatform/resources/rp-target-wix/scripts/verify-stores.js stores product-by-source-marker \
  --marker-path customFields.sourceId --marker-value <source-id> \
  --artifact migrations/<project>/execution/stores-product-marker-verification.json
node skills/wix-replatform/resources/rp-target-wix/scripts/verify-stores.js stores delete-probe \
  --product-id <probe-product-id> \
  --artifact migrations/<project>/setup/stores-probe-cleanup.json
```

The CLI reads `WIX_AUTH_TOKEN` and `WIX_SITE_ID` from the environment or
`config/wix.env` under the current project root, creates the shared Wix client, and sends
requests through `wix.send(...)`. It writes machine-readable artifacts with the target
site id, endpoint, method, verified nested paths, discovered constraints, probe id,
cleanup status, warnings, recovery instructions, and timestamp. Failed probe cleanup is
not hidden: the artifact must remain with an explicit warning and a `delete-probe`
recovery command.

## Routed URL preservation behavior

URL preservation is a mapping and execution-state concern. This adapter owns only the
Wix-side facts that generated code may rely on when deciding whether a final target URL is
known.

Current import-only phase rules:

- Do not configure Wix redirects or site routing.
- Do not guess a destination relative URL from a slug when Wix route behavior has not been
  verified for that entity and delivery mode.
- When the destination base path or final URL is unknown, write URL ledger rows with
  `urlStatus: "pending_target_route"` or `target_url_missing` and record unresolved rows
  for the future website-builder phase.
- When a Wix create/update response or a safe declared lookup returns a final slug or
  relative path, generated code may record it as `actualTargetSlug` or
  `actualTargetRelativeUrl` and write a redirect plan if it differs from the source URL.

Known routed entity status:

| Entity | URL behavior contract |
| --- | --- |
| Blog posts | Create/publish is verified for content writes. Final public route exposure after publish is not verified here; generated code must treat the target route as `pending_target_route` unless a safe lookup in the generated write spec proves the final relative URL. |
| Blog categories | Category create is verified. Final public category route exposure is not verified here; default to `pending_target_route`. |
| Stores products | Product create and slug-bearing product operations are verified, but arbitrary route/base-path configuration is not part of this phase. Generated code may record actual target slugs only when returned or safely looked up; target relative URLs remain `pending_target_route` unless the route pattern is explicitly verified in the project. |
| Stores categories/collections | Category create is verified. Final collection/category route exposure is not verified here; default to `pending_target_route`. |
| CMS items with dynamic pages | CMS item writes are verified. Dynamic page route patterns are site-builder configuration, not native item import output; default to `pending_target_route` unless website-builder artifacts define the route. |

## Shared execution runtime contract

In addition to endpoint primitives, this adapter should define the reusable runtime API
that generated migrations call.

Conceptual contracts:

```ts
executeWriteSpec({
  spec,
  items,
  client,
  dryRun,
  runContext,
}): Promise<WriteExecutionReport>

executeSetupPlan({
  plan,
  client,
  dryRun,
  runContext,
}): Promise<SetupExecutionReport>
```

The exact filenames are implementation details, but the shared runtime should be the
single place that owns generic Wix execution mechanics.

### `WriteSpec` contract

Generated migrations should pass a declarative `WriteSpec` into the shared runtime.

Each spec should define, as applicable:

- `entity`
- `mode`: `create | update | upsert | bulk_create | bulk_upsert`
- `create`
- `update`
- `lookup`
- `bulk`
- `batchSize`
- `concurrency`
- `retryPolicy`
- `throttlePolicy`
- `auditKeys`
- `crosswalkAuthority: "local"`
- `cmsMirror`
- `crosswalkStrategy`
- `reconciliationStrategy`
- `dependencyRefs`
- `verificationLevel`: `verified | unverified`

This resource should document how each field is interpreted by the runtime.

### `WriteExecutionReport` contract

The shared runtime should return a compact, token-aware report suitable for the agent.

It should include:

- run ID
- entity
- counts: input, attempted, created, updated, skipped, failed, retried, throttled
- grouped error buckets
- references to fuller on-disk logs

The runtime should prefer grouped summaries over raw per-record detail.

These per-entity or per-phase reports are intermediate runtime outputs. They are inputs to
the final completion artifact, not replacements for it.

### Completion artifact contract

The shared runtime should support deterministic emission of a final machine-readable
completion artifact for the whole run.

Preferred output:

- `execution/completion-report.json`

This artifact should be the authoritative source for:

- final run status
- final imported/updated/skipped/failed counts
- separate dry-run counts when `dryRun: true`: requests built, Wix calls skipped,
  would-create/update/delete, would require live lookup, and local validation failures
- grouped skipped/deferred outcomes
- grouped failure outcomes
- dashboard/editor/preview destinations
- artifact references for audit/error/execution logs

The shared runtime should also support deterministic rendering inputs for:

- `execution/review/completion-summary.md`

The rendered summary should be derived from `completion-report.json`, not independently
invented by the agent.

### Audit log contract

The shared runtime should emit append-only machine-readable audit events.

Preferred format: NDJSON.

Each event should capture, at minimum:

- timestamp
- run ID
- phase: `setup | import`
- entity
- operation
- source ID when applicable
- target ID when known
- endpoint or primitive used
- attempt number
- result status
- HTTP status or platform error code when applicable
- latency

The `run ID` is required because audit files are append-only across dry-runs, retries, and
recovery passes. Completion reports should be generated from runtime counters for the
current run and may use audit aggregation only when filtered by `run ID`. The shared
`lib/audit-summary.js` helper enforces this filter for fallback/verification summaries.

### Dry-run runtime contract

The shared Wix runtime exports `createDryRunConfig`, `normalizeDryRunValue`,
`createWixClient`, and `createWixSetupExecutor`.

Dry-run is enabled by `DRY_RUN=true` or by the generated entrypoint's `--dry-run` flag.
It is disabled by default. `true`, `1`, `yes`, and `on` enable it; `false`, `0`, `no`,
and `off` disable it.

When `createWixClient({ dryRun: true })` is used:

- `authToken` and `siteId` may be blank unless the generated project requires the site ID
  for a local artifact namespace;
- `send()` must not call `fetch`, SDK, MCP, or CLI transports;
- `send()` must capture the would-send request under
  `state/attempts/wix-request-captures.ndjson` when `projectDir` or `requestCapturePath`
  is supplied;
- captured headers must omit `Authorization` and redact secret-like header/body keys;
- captured bodies must be after `SAFE_MODE` contact-value sanitization;
- response payloads must preserve the live shape expected by writer helpers, for example
  `{ contact }`, `{ product }`, `{ dataItem }`, `{ file }`, or an expected collection
  field such as `{ contacts: [] }` for skipped queries.

Dry-run placeholder target IDs are not live authority. If downstream local execution
needs them, write them only to `state/crosswalk/dry-run-crosswalk.ndjson` or keep them
in memory. Never append simulated target IDs to `state/crosswalk/crosswalk.ndjson` and
never upload them to a CMS crosswalk mirror.

When `createWixSetupExecutor({ dryRun: true })` is used, each setup step must first be
reduced to a structured intent, then captured as `planned_dry_run` without invoking MCP,
CLI, SDK, or REST transports that access or mutate Wix account/site state.

### Artifact authority at run completion

The shared runtime contract should preserve explicit artifact authority:

1. `execution-log.md` for chronology and operator/debug context only
2. `completion-report.json` for final outcome
3. `completion-summary.md` for deterministic user-facing rendering

The runtime should not force downstream consumers to reconstruct final outcome by reading
raw audit logs or chronological execution logs.

### Retry and throttling policy

This adapter should define one shared retry/throttling contract rather than letting each
migration invent its own.

It should classify, at minimum:

- retryable transport/network failures
- retryable `429` responses
- retryable `5xx` responses
- non-retryable `4xx` validation failures unless explicitly listed otherwise

When the server provides backoff hints such as `Retry-After`, the shared runtime should
honor them.

### Bulk and fallback policy

The shared runtime should know:

- when a native bulk primitive exists and is preferred
- when to fall back from bulk to per-record writes
- when an upsert requires lookup + create/update orchestration
- when an unverified native path must be surfaced before execution rather than used
  silently

## Media policy by target

Do not treat all media the same. The target domain decides whether media must exist in Wix
first or can be ingested through the entity API itself.

- **Wix Stores products:** prefer external URLs on `media.itemsInfo.items[]` and let the
  product API ingest them in the background. This is the default path when the URLs are
  publicly reachable.
- **Wix Blog cover images and other surfaces that require a Wix media id at create/update
  time:** import media first, then pass the Wix media id into the entity payload.
- **Generic Media Manager import** is a fallback/shared primitive, not the default for
  every entity carrying media.

## Media import source URL reachability

The media primitive imports by URL: Wix servers fetch the provided `sourceUrl`. Public
HTTPS URLs are expected; `localhost`, `127.0.0.1`, Docker-only hosts, and other
private-only URLs are not reachable by Wix during a live import. This is optional source
preparation and, as far as we know today, affects media import only.

If the source system is local, the migration should either:

- expose the source through a public HTTPS tunnel, then pass/rewire media URLs to that
  public base URL; or
- skip/defer media import and clearly state which media-dependent references will be
  missing until media is imported.

Ngrok quick setup for macOS:

```bash
brew install ngrok
ngrok config add-authtoken "<YOUR_AUTHTOKEN>"
ngrok http 8090
export WP_BASE_URL=https://<id>.ngrok-free.app
```

## Validate by real call — do not trust doc examples

Codegen-time MCP doc checks confirm an endpoint *exists*; they do **not** confirm the
request *shape works*. The live wporg-news import proved doc examples can be wrong
(lowercase Ricos plugins → 400) or incomplete (featured image field, tag body). The
rule for this adapter:

- Treat a shape as verified **only after a real call succeeds** — encode the working
  shape here with a `// VERIFIED:` (or `// VERIFIED-TRAP:`) note and a date.
- A `// UNVERIFIED:` primitive is allowed as a bootstrap point for generated code, but it
  is not a silent live-write permission. The execution plan must call it out, and setup
  verification must either promote it with a sandbox/live validation or route to fallback.
- Keep `tests/target-wix/contract-test.js` current: it issues one real call per primitive
  against a sandbox site and is the single place schema drift surfaces. Tests live in the
  repo's `tests/` tree rather than in this bundle, so the published product carries no test
  harnesses. Run from the repo root:

  ```bash
  bash tests/run-all.sh target-wix
  WIX_AUTH_TOKEN=... WIX_SITE_ID=... bash tests/run-all.sh target-wix
  ```

  Without credentials the shape checks still run and the live calls are skipped.
  `tests/target-wix/ndjson-contract-test.js` covers `lib/ndjson.js` and never needs
  credentials.

  For live verification runs, pass `--progress-log <path

…(truncated)