@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/resources/rp-target-wix/domains/forms/entities/form.json

@@ -0,0 +1,134 @@
+{
+  "schemaVersion": 1,
+  "domain": "forms",
+  "entity": "form",
+  "displayName": "Wix Form (form schema)",
+  "capability": "content.form-definitions",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Form Schema",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "dependsOn": [],
+  "sourceAliases": [],
+  "preferredWrite": {
+    "surface": "Form Schemas V4 (FormSchemaService)",
+    "endpoint": "POST /form-schema-service/v4/forms",
+    "writerId": null,
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": true
+  },
+  "reliability": {
+    "status": "partially-reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "missing-identifier-breaks-submission-validation-not-just-display",
+      "severity": "blocker",
+      "summary": "LIVE-VERIFIED 2026-09-16: the severe reading below is CONFIRMED, and it is worse than 'the field doesn't appear in the dashboard' — a formField built WITHOUT a top-level `identifier` creates successfully (200; the field shows up fine in the read-side `fields[]` projection) but Create Submission then rejects EVERY key in `submissions` as UNKNOWN_VALUE_ERROR ('must NOT have additional properties'), even against a form left untouched for 20+ minutes (ruling out eventual consistency as the cause — verified by retrying the identical call every 15s for 5 minutes with no change). The giveaway: the SAME create request, submitted with `identifier` set, is accepted by Create Submission within 1-2 seconds. Diffing a working pre-existing form's `formFields[]` (via Query Forms) against a broken one built without `identifier` is what surfaced this — `formFields` in the READ response is EMPTY on both a working and a broken form (a legacy/unpopulated projection on this API version; do not use its length as a success signal), so the only way to catch this pre-emptively is to always set `identifier` explicitly, never rely on it being optional. A generic field with no better semantic match still needs `identifier: 'TEXT_INPUT'` (matching its own componentType) — never omit it."
+    },
+    {
+      "code": "input-field-shape-required-vs-docs-implied",
+      "severity": "blocker",
+      "summary": "LIVE-VERIFIED 2026-09-16: the working shape for an INPUT formField differs from what a naive reading of 'compose from inputType + componentType + <componentType>Options' suggests. `pii`, `required` and `readOnly` live directly on `inputOptions` (NOT nested under a separate top-level `validation: {required}` object — that shape is silently accepted at create but produces the same non-recognized-target failure as a missing identifier), and `stringOptions` needs its OWN nested `validation: {format, enum}` object (use `{format: 'UNKNOWN_FORMAT', enum: []}` for a plain text field with no format constraint). Minimal working INPUT field: `{id, hidden:false, identifier, fieldType:'INPUT', inputOptions:{target, pii:false, required, inputType:'STRING', readOnly:false, stringOptions:{validation:{format:'UNKNOWN_FORMAT', enum:[]}, componentType:'TEXT_INPUT', textInputOptions:{label, showLabel:true}}}}`. Also live-verified: the STRING componentType enum is `TEXT_INPUT, RADIO_GROUP, DROPDOWN, DATE_TIME, PHONE_INPUT, DATE_INPUT, TIME_INPUT, DATE_PICKER, SERVICES_DROPDOWN, PASSWORD` — there is no `TEXT_AREA`; a multi-line source field (WordPress textarea) is still built as `TEXT_INPUT` (matches the existing 'long answer and short answer share TEXT_INPUT' note below)."
+    },
+    {
+      "code": "submit-button-display-field-shape-unresolved-but-skippable",
+      "severity": "info",
+      "summary": "LIVE-VERIFIED 2026-09-16: a DISPLAY field built as `{fieldType:'DISPLAY', displayOptions:{componentType:'SUBMIT_BUTTON', submitButtonOptions:{...}}}` is REJECTED at create ('Unrecognized value passed for enum of wix.forms.v4.fields.DisplayField.DisplayFieldTypeOptions.Empty') regardless of the componentType value tried — the key is wrong (a pre-existing working form's DISPLAY field uses `displayOptions.displayFieldType: 'PAGE_NAVIGATION'` with `pageNavigationOptions`, not `componentType`/`submitButtonOptions`), but the full valid shape/enum was not pinned down this run. Live-verified workaround: a submit DISPLAY field is NOT required for Create Form to succeed, nor for Create Submission to accept values against the form's INPUT fields — a schema built with INPUT fields only creates and accepts submissions fine. Omitting it is a cosmetic simplification (no submit-button widget shown if the merchant edits the form in the Wix Forms builder UI) — the 'every field including the submit button must be placed' guidance below still holds for a human-facing form, but is not a hard requirement for a migration whose only goal is historical Create Submission writes."
+    },
+    {
+      "code": "choice-options-need-lowercase-guid-ids",
+      "severity": "blocker",
+      "summary": "Every option of a choice field (dropdown, radio group, checkbox group, tags) needs its own lowercase GUID `id`: 'An option without one is rejected at creation.' Source plugins do not carry option ids — CF7 form-tags list bare option strings, WPForms keys choices by ordinal — so codegen must MINT an id per option and keep the mint deterministic across re-runs, or a retry produces a schema whose option ids no longer match anything already crosswalked."
+    },
+    {
+      "code": "field-must-be-placed-in-layout",
+      "severity": "blocker",
+      "summary": "`formFields` is an unordered set; display order comes from `steps[].layout.<breakpoint>.items` positioning each field by row/column and matching it through `fieldId`. Every field that IS emitted must be placed. An unplaced field still stores submitted values but the Wix dashboard renders the field — and every submission made against it — as EMPTY. Codegen must emit a layout for every imported INPUT field it actually creates. This does NOT extend to a submit DISPLAY field for a migration -- see submit-button-display-field-shape-unresolved-but-skippable below: the working migration shape omits that field entirely rather than attempting to place an unresolved, previously-rejected shape."
+    },
+    {
+      "code": "field-id-must-be-lowercase",
+      "severity": "warning",
+      "summary": "The server stores `formFields[].id` in lowercase. An uppercase GUID still saves, but the layout's `fieldId` no longer matches it once the schema is stored, so the field is silently unplaced (see field-must-be-placed-in-layout). Lowercase every generated GUID on both sides, or omit `id` and let the server generate it — then the layout must be built from the response."
+    },
+    {
+      "code": "name-collision-renames-silently",
+      "severity": "warning",
+      "summary": "Form schema names are unique within a namespace. If the name is already taken the request still SUCCEEDS and the schema is stored under a numbered variation of the name. Read `name` back from the response and crosswalk that value; re-running an import otherwise produces 'Contact form 1', 'Contact form 1 (1)', … instead of failing or upserting."
+    },
+    {
+      "code": "premium-and-app-gated-field-types",
+      "severity": "warning",
+      "summary": "File upload, signature and all four payment fields need a Core premium plan or higher; product/fixed-price/custom-price/donation fields also need Wix eCommerce, appointment fields Wix Meetings, service pickers Wix Services. A schema containing an unavailable field type FAILS at create. Source forms carrying file-upload or payment fields therefore need a setup-discovery check before the import step, and a degradation decision (drop the field vs. block the form) recorded at the mapping gate."
+    },
+    {
+      "code": "source-field-count-can-exceed-the-cap",
+      "severity": "warning",
+      "summary": "Caps are set per namespace by the app that provides the schema, not hardcoded, and they are enforced by FAILING the create (FORM_FIELDS_COUNT_EXCEEDED / NAMESPACE_FORMS_COUNT_EXCEEDED / FORM_SIZE_EXCEEDED) rather than by truncating. List Forms Providers Configs returns the live numbers per namespace: `maxForms` (forms per namespace, excluding deleted), `maxFields` (all fields and display elements in one form), `maxDeletedForms` (trash-bin occupants count toward it). Read them during setup discovery instead of assuming. Note `formFields` also carries a hard schema ceiling of maxItems 500 independent of the provider config. Splitting one oversized source form across several Wix schemas is possible but trades one submission record for several and consumes more of the namespace allowance — a faithfulness-ledger decision, not an automatic fallback."
+    },
+    {
+      "code": "conditional-logic-and-notification-config-do-not-carry",
+      "severity": "warning",
+      "summary": "WordPress form plugins keep three things next to the field list that have no equivalent create input here: the mail/notification templates (CF7 `properties.mail` / `mail_2`, WPForms `settings.notifications`), the confirmation messages, and the conditional-show/hide rules. Wix has `submitSettings.submitSuccessAction` (NO_ACTION / THANK_YOU_MESSAGE / REDIRECT / POPUP) and `formRules[]`, but their shapes are unrelated to the source's. Treat notification templates as reconfigure-in-wix (they become Wix Automations) and ledger conditional logic as a manual follow-up rather than attempting a rule translation."
+    }
+  ],
+  "mappingGuidance": [
+    "Create every imported WordPress form in namespace `wix.form_app.form`; that is the Wix Forms app's namespace and the only one whose submissions land in the site owner's Forms dashboard. A form created in another app's namespace inherits that app's business logic.",
+    "Compose each input field from three values that must agree: `inputOptions.inputType` (STRING / NUMBER / BOOLEAN / ARRAY / ADDRESS / PAYMENT / SCHEDULING / WIX_FILE), `inputOptions.<inputType>Options.componentType` (for STRING: TEXT_INPUT, RADIO_GROUP, DROPDOWN, DATE_TIME, PHONE_INPUT, DATE_INPUT, TIME_INPUT, DATE_PICKER, SERVICES_DROPDOWN, PASSWORD — LIVE-VERIFIED 2026-09-16 there is no TEXT_AREA in this enum, see the pitfall below) and the matching `<componentType>Options` block holding label/description/choices. The nesting rule is mechanical: camelCase the enum value and append `Options`.",
+    "`inputOptions.target` is the stable storage key a submitted value is written under, and it is the ONLY key Create Submission accepts. Derive it from the source field's machine name (CF7 form-tag name, e.g. `your-email`; WPForms `fields[].id` + label) and persist source-field-name -> Wix target in the crosswalk — the submissions import is unusable without it.",
+    "Map source field types onto Wix identifiers where a semantic match exists (email -> CONTACTS_EMAIL, name -> CONTACTS_FIRST_NAME/CONTACTS_LAST_NAME, phone -> CONTACTS_PHONE, single-line text -> TEXT_INPUT, textarea -> TEXT_INPUT (there is no TEXT_AREA componentType — see the LIVE-VERIFIED pitfall below), select -> DROPDOWN with stringOptions, checkboxes -> ARRAY/CHECKBOX_GROUP, file -> WIX_FILE). For a CONTACTS_* field also set `inputOptions.contactMapping.contactField` and `pii: true` so Wix encrypts the stored value.",
+    "Emit a single step unless the source form is genuinely paginated, and place every INPUT field this migration actually creates in that step's layout for at least one breakpoint; fall back across breakpoints when reading, never assume `large` exists. Do NOT include a submit DISPLAY field -- its valid shape is unresolved and a previously-tried shape was rejected at create (see submit-button-display-field-shape-unresolved-but-skippable below); omitting it is verified to still create the form and accept submissions fine.",
+    "Persist the returned `form.id` against the source form id (CF7 post id, WPForms post id) in the crosswalk at create time — `id` is read-only, so the source id cannot be preserved and the submissions import depends on the crosswalk.",
+    "Bulk Create Form accepts 1–30 schemas per call (POST /forms/v4/bulk/forms/create) and is the right shape for a site with many small forms; a single oversized form still has to go through Create Form.",
+    "Deleting a form schema in Wix moves it to a 90-day trash bin and permanently deleting it deletes all of its submissions — relevant to re-run/rollback design, which must never delete a schema that already carries imported submissions."
+  ],
+  "setupRequirements": [
+    "Wix Forms app installed (`wix_forms`; confirm with GetAppInstance)",
+    "SCOPE.FORMS.EDIT-FORM (Manage forms)",
+    "Premium plan check via List Forms Providers Configs when the source forms carry file-upload, signature or payment fields",
+    "Wix eCommerce / Wix Meetings / Wix Services installed only if the source forms carry payment, appointment or service-picker fields"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/form-object",
+      "note": "object page: id read-only; formFields[] (id lowercase-stored, identifier dropped-if-unknown, fieldType INPUT/DISPLAY), steps[] layout with per-breakpoint items, rules/formRules, namespace, limitationRule, spamFilterProtectionLevel, submitSettings.submitSuccessAction enum, enabled/activationBlock semantics, submissionAccess enum, autoFillContact (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/create-form",
+      "note": "POST https://www.wixapis.com/form-schema-service/v4/forms; scope SCOPE.FORMS.EDIT-FORM; required form + form.namespace; id is read-only in the response; errors incl. UNSUPPORTED_FORM_NAMESPACE, FORM_SIZE_EXCEEDED, FORM_FIELDS_COUNT_EXCEEDED, NAMESPACE_FORMS_COUNT_EXCEEDED, DUPLICATED_FIELD_TARGETS, MISSING_FIELD_TARGETS (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields",
+      "note": "field composition rule (inputType + componentType + <componentType>Options); the Field types table with its Requires column (File upload/Signature = Premium plan; Product/Fixed price/Custom price/Donation = Premium plan + Wix eCommerce; Appointment = Wix Meetings; Service picker + Multi-service picker = Wix Services); identifier is a rendering hint for the submission table and a non-standard one 'may display incorrectly there, even though the form itself works and the API accepts the request'; identifiers are per-namespace; target as the stable storage key; contactMapping.contactField (FIRST_NAME/LAST_NAME/COMPANY/POSITION/EMAIL/PHONE/ADDRESS/BIRTHDATE/VAT_ID/CUSTOM_FIELD/SUBSCRIPTION) + pii for CONTACTS_* fields; 'Every field must appear in the layout, including the submit button. A field that isn't placed still stores submitted values, but the Wix dashboard renders it, and the submissions made against it, as empty'; 'The server stores id in lowercase … an uppercase id still saves, but the layout's fieldId no longer matches it once the form schema is stored, so the field is silently unplaced'; choice options each need a lowercase GUID id or are 'rejected at creation'; componentType alone does not identify a field (long answer and short answer share TEXT_INPUT; image choice and multi choice share CHECKBOX_GROUP) (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/bulk-create-form",
+      "note": "POST https://www.wixapis.com/forms/v4/bulk/forms/create; forms[] minItems 1 maxItems 30 (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/list-forms-providers-configs",
+      "note": "GET https://www.wixapis.com/form-schema-service/v4/forms/providers-config; returns configs[] per namespace with maxForms (0–15000), maxFields (0–200) and maxDeletedForms — the documented way to read the site's live caps instead of assuming fixed numbers (read 2026-08-16)"
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-source-wordpress/plugins/contact-form-7.json",
+      "note": "source side, VERIFIED LIVE 2026-08-16 on an anonymized verification environment: CF7 form definitions ARE readable over the plugin's own namespace (GET /contact-form-7/v1/contact-forms/{id} returns properties.form.fields[] with type/basetype/name/options), while WPForms Lite definitions are NOT REST-readable (the `wpforms` CPT registers with no show_in_rest). Both profiles point content.form-definitions here"
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Form schemas created (CF7, WPForms, Forminator, MetForm definitions), then historical submissions written and confirmed against them (see forms/form-submission's live-run evidence) — surfaced the missing-identifier and input-field-shape pitfalls above, and confirmed the submit-button DISPLAY field is skippable for a migration's purposes."
+    }
+  ],
+  "notes": "Authored 2026-08-16 alongside the contact-form-7 and wpforms-lite profiles. importSafe is true for the schema create itself: Create Form takes no visitor-facing action and emits only Form Created; the notification risk in this domain sits entirely on forms/form-submission. CORRECTION LOG: the first draft of this entity claimed an unrecognized `identifier` is silently dropped from the stored schema; re-reading About Form Fields on 2026-08-16 showed the docs claim only that a non-standard identifier may render incorrectly in the submission table while the API still accepts the field. The pitfall was downgraded from blocker to warning, then RE-UPGRADED to blocker on 2026-09-16 once a live migration proved the severe reading true and much worse than either docs page implies: missing `identifier` breaks Create Submission validation entirely, not just dashboard display (see missing-identifier-breaks-submission-validation-not-just-display). reliability and verification were updated from `unknown`/`docs` to `partially-reliable`/`verified-live` on the same date, once a real form was created and real submissions were written against it end to end."
+}

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

@@ -0,0 +1,41 @@
+{
+  "schemaVersion": 1,
+  "domain": "gift-cards",
+  "fetchedAt": "2026-08-11",
+  "roots": [
+    "api-reference/business-solutions/gift-cards"
+  ],
+  "surfaces": [
+    {
+      "id": "api-reference/business-solutions/gift-cards/gift-card-products",
+      "title": "Gift Card Products",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/gift-cards/gift-card-products",
+      "group": null,
+      "verdict": "claimed",
+      "reviewedOn": "2026-08-11",
+      "refs": [
+        "gift-cards/gift-card-product"
+      ]
+    },
+    {
+      "id": "api-reference/business-solutions/gift-cards/gift-cards",
+      "title": "Gift Cards",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/gift-cards/gift-cards",
+      "group": null,
+      "verdict": "claimed",
+      "refs": [
+        "gift-cards/gift-card"
+      ],
+      "reviewedOn": "2026-08-11"
+    },
+    {
+      "id": "api-reference/business-solutions/gift-cards/transactions",
+      "title": "Transactions",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/gift-cards/transactions",
+      "group": null,
+      "verdict": "not-importable",
+      "reason": "Transaction ledger written by issuance/redemption flows; an imported card carries its balance at creation (gift-cards/gift-card), historical transactions have no import path.",
+      "reviewedOn": "2026-08-11"
+    }
+  ]
+}

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

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": 1,
+  "domain": "gift-cards",
+  "dependsOnRequired": true,
+  "docsRoots": [
+    "api-reference/business-solutions/gift-cards"
+  ],
+  "displayName": "Wix Gift Cards",
+  "ownerHint": "Gift cards, stored value, and store credit domain owners",
+  "wixAppsRequired": [
+    "Wix Gift Card"
+  ],
+  "defaultImportOrder": [
+    "gift-card-product",
+    "gift-card"
+  ],
+  "sharedPitfalls": [
+    {
+      "code": "gift-card-app-required",
+      "severity": "blocker",
+      "summary": "The Wix Gift Card app must be installed before any gift-card write; verify during setup rather than discovering it at import time. appDefId d80111c5-a0f4-47a8-b63a-65b54d774a27 (per dev.wix.com's 'About Apps Created by Wix' table — DO NOT reuse an example id from other docs, e.g. Wix eCommerce's 1380b703-… is a real, easy-to-confuse-with-the-right-one dependency it pulls in). VERIFIED LIVE 2026-08-17: a site with no gift-card app installed fails create with `428 RISE_ACCOUNT_DOES_NOT_EXIST_FOR_META_SITE`, not an auth or validation error — install via the standard App Installation API (`POST /apps-installer-service/v1/app-instance/install`, body `{ appInstance: { appDefId, enabled: true }, tenant: { tenantType: \"SITE\", id: <siteId> }, installType: \"INSTALL_TYPE_SITE\", appsInstallOptions: {} }`), then retry."
+    },
+    {
+      "code": "distinguish-gift-card-surfaces",
+      "severity": "warning",
+      "summary": "Two Wix gift-card surfaces exist. `gift-cards/v1` creates and manages cards. The eCommerce payments gift-card surface only gets/redeems/voids cards issued by an external provider and is NOT an import path."
+    },
+    {
+      "code": "gifted-app-is-unrelated-third-party",
+      "severity": "warning",
+      "summary": "\"Gifted\" is a separate THIRD-PARTY app in the App Market, unrelated to the native \"Wix Gift Cards\" app this domain targets. Gifted stopped supporting new-card issuance on 2026-07-31 (existing cards still work) — that deprecation notice is easy to find while researching this domain and is NOT about the native gift-cards/v1 API, which is unaffected. Do not let a Gifted-app finding get attributed to this domain."
+    }
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/gift-cards/gift-cards/introduction"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix",
+      "note": "source of the appDefId above"
+    },
+    {
+      "type": "support-article",
+      "url": "https://support.wix.com/en/article/offering-gift-cards-with-the-gifted-app",
+      "note": "source of the Gifted-app deprecation notice and its third-party status"
+    }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/gift-cards/entities/gift-card-product.json

@@ -0,0 +1,87 @@
+{
+  "schemaVersion": 1,
+  "domain": "gift-cards",
+  "entity": "gift-card-product",
+  "displayName": "Gift Card Product",
+  "capability": "commerce.gift-card-products",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Gift Card Product",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "dependsOn": [
+    "media/media-file"
+  ],
+  "sourceAliases": [],
+  "preferredWrite": {
+    "surface": "Gift Card Products",
+    "endpoint": "POST /gift-cards/v1/gift-card-products",
+    "writerId": null,
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": false
+  },
+  "reliability": {
+    "status": "partially-reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "one-gift-card-product-per-site",
+      "severity": "blocker",
+      "summary": "A site supports a MAXIMUM OF ONE gift card product (documented as a temporary limitation; second create → 409 GIFT_CARD_PRODUCT_ALREADY_EXISTS). A source shop with several gift-card products (different designs, different denomination sets, seasonal variants) CANNOT be migrated one-to-one: collapse them into a single product whose presetVariants union the denominations, and ledger the lost designs/descriptions as fidelity_loss. Check for an existing product before creating — on a non-empty destination the create will fail rather than merge."
+    },
+    {
+      "code": "products-vs-issued-cards",
+      "severity": "warning",
+      "summary": "A gift card product is the purchasable definition (name, denominations, image); issued cards and balances are gift-cards/gift-card. Import both or buyers get a catalog item while existing card holders lose balances — plan them together."
+    },
+    {
+      "code": "denominations-are-presetVariants",
+      "severity": "blocker",
+      "summary": "The denomination field is presetVariants[], NOT 'variants' or 'denominations'. VERIFIED LIVE 2026-08-16: a body using variants[] fails the whole call with 428 CANNOT_CREATE_GIFT_CARD_PRODUCT_WITHOUT_VARIANTS — an error that reads like a missing-data problem but is actually a wrong-field-name problem. Each preset variant carries price (what the buyer pays) and value (the balance loaded), which are allowed to differ for promotional pricing; a customVariant { minValue, maxValue } can coexist with presets for buyer-chosen amounts. At least one preset or a customVariant is required."
+    },
+    {
+      "code": "image-optional-but-media-manager-only",
+      "severity": "warning",
+      "summary": "The product image is OPTIONAL (verified live 2026-08-16: create succeeds with no image at all — the earlier 'must already exist' framing overstated it), but when supplied it must be a Wix Media Manager image and needs at least id, width, and height; there is no external-URL import on this surface, unlike stores/promotion. Import source card designs through media/media-file first."
+    },
+    {
+      "code": "expiration-is-a-one-of",
+      "severity": "info",
+      "summary": "expirationType is NONE | FIXED | RELATIVE, paired with a one-of: fixedExpirationDate (a date-time, rejected if in the past — 428 CANNOT_CREATE_GIFT_CARD_PRODUCT_WITH_PAST_EXPIRATION_DATE) or relativeExpirationDate { value, period DAYS|WEEKS|MONTHS|YEARS }. A source policy of 'expires N months after purchase' maps to RELATIVE; a source shop's already-lapsed fixed expiry cannot be recreated and must be ledgered."
+    }
+  ],
+  "mappingGuidance": [
+    "Map source gift-card product definitions (e.g. PW/YITH WooCommerce gift card products: title, amounts, design image) to name (max 55 chars), description (max 3000), presetVariants[] (max 200) and/or customVariant, and image.",
+    "Because only one gift card product can exist per site, resolve the source's several products into one BEFORE the write: union the denominations into presetVariants[], derive a customVariant range from any 'choose your own amount' source option, and record every collapsed product in the migration ledger.",
+    "Import media first, then the gift card product, then issued cards (gift-cards/gift-card) so references resolve in one pass."
+  ],
+  "setupRequirements": [
+    "Wix Gift Cards app"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/gift-cards/gift-card-products/gift-card-product-object",
+      "note": "object page: name, description, Media-Manager image, denominations"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/gift-cards/gift-card-products/create-gift-card-product"
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Source verification established that gift-card balances are database-only while product definitions are REST-visible."
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Verified live: POST /gift-cards/v1/gift-card-products with { name, description, expirationType: NONE, presetVariants: [{ price 25 / value 25 }, { price 45 / value 50 }], customVariant: { minValue 10, maxValue 500 } } → 200 with server-assigned product id and per-preset-variant ids; GET readback preserved every amount and populated formattedAmount/convertedAmount in the site currency (ILS). A first attempt using variants[] instead of presetVariants[] failed with 428 CANNOT_CREATE_GIFT_CARD_PRODUCT_WITHOUT_VARIANTS. No image was supplied and the create still succeeded. DELETE /gift-cards/v1/gift-card-products/{id} → 200 at cleanup. Not exercised: image attachment, FIXED/RELATIVE expiration, and the documented one-product-per-site 409 (only one product was ever created)."
+    }
+  ],
+  "notes": "Authored 2026-08-11 from the docs-survey gap (Gift Card Products). Promoted to verified-live 2026-08-16 by a create/readback/delete probe on an anonymized verification environment, which also CORRECTED two docs-era claims: the denomination field is presetVariants[] (a wrong field name surfaces as a misleading 'without variants' 428), and the image is optional rather than required. The one-gift-card-product-per-site cap — the biggest constraint on this migration path — was found in the create-method docs during that probe and is the reason reliability is partially-reliable rather than reliable. Pairs with gift-cards/gift-card for a complete gift-card migration."
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/gift-cards/entities/gift-card.json

@@ -0,0 +1,130 @@
+{
+  "schemaVersion": 1,
+  "domain": "gift-cards",
+  "entity": "gift-card",
+  "displayName": "Gift Card",
+  "capability": "commerce.gift-cards",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Gift Card",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "dependsOn": [],
+  "blockedSourceDependencies": [
+    {
+      "sourceEntityRef": "plugin.pw-woocommerce-gift-cards.gift-card-activity",
+      "degradedField": "balance",
+      "pitfallCode": "balance-is-read-only",
+      "degradation": "warning"
+    }
+  ],
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "giftCard",
+      "sourcePlugin": "woocommerce-gift-cards",
+      "routes": [
+        "/wc/v3/gift-cards"
+      ],
+      "confidence": "high"
+    },
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "giftCard",
+      "sourcePlugin": "pw-woocommerce-gift-cards",
+      "routes": [
+        "/wc/v3/orders"
+      ],
+      "confidence": "high",
+      "note": "Live verification established that the source plugin has no REST namespace of its own. Issuance data rides as line_item meta_data on /wc/v3/orders once an order reaches processing or completed; redemption and balance data have no REST or order-meta surface and require the profile's gift-card-activity entity."
+    }
+  ],
+  "preferredWrite": {
+    "surface": "Gift Cards",
+    "endpoint": "POST /gift-cards/v1/gift-cards",
+    "writerId": null,
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": false
+  },
+  "fallbacks": [
+    {
+      "classification": "cms",
+      "when": "Only for redemption/transaction history, which has no public write surface, or for source-only fields such as the original card design."
+    }
+  ],
+  "reliability": {
+    "status": "partially-reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "suppress-recipient-email-on-import",
+      "severity": "blocker",
+      "summary": "Omit `giftCard.notificationInfo` entirely on import. Including it emails the recipient — immediately when `notificationDate` is empty — so a historical import would re-mail every card holder."
+    },
+    {
+      "code": "code-length-8-to-20",
+      "severity": "blocker",
+      "summary": "`giftCard.code` is constrained to 8-20 characters and is immutable. Source codes outside that range cannot be preserved, which breaks the code customers already hold; surface affected cards before import rather than silently rewriting them."
+    },
+    {
+      "code": "code-alphanumeric-only",
+      "severity": "blocker",
+      "summary": "Verified live: `giftCard.code` rejects any non-alphanumeric character. A hyphenated code returns `428 INVALID_CODE`, independent of the 8-20 length check above. Sources whose default format includes separators therefore cannot preserve those codes as-is. Stripping non-alphanumeric characters produces an acceptable code, but changes what the customer already holds; report affected cards and require an explicit decision rather than stripping silently."
+    },
+    {
+      "code": "full-code-returned-only-at-create",
+      "severity": "blocker",
+      "summary": "The create response is the only place the full unobfuscated code appears; Get/Query return it masked (`****-****-****-4444`) plus `codeSuffix`. Persist the code-to-id crosswalk in the same step as the create or it is unrecoverable."
+    },
+    {
+      "code": "balance-is-read-only",
+      "severity": "warning",
+      "summary": "Only `initialValue` is settable; `balance` is derived from transactions and there is no public adjust-balance method. A partly-spent card must either be created at its remaining value (loses face value and spend history) or created at face value and reduced via a redeem call (preserves both, adds a synthetic transaction). Use one balance policy per run (Policy A/B, never both for the same card) and lib/gift-card-balance-reconciliation.js's buildBalanceReconciliationReport() (fixed 2026-08-18) for the reporting-only drift check this implies — it never proposes a balance patch, only disable-and-replace or investigate, for exactly the no-adjust-balance-method reason stated here."
+    },
+    {
+      "code": "no-transaction-history-import",
+      "severity": "warning",
+      "summary": "No public method writes historical redemption transactions, so per-card spend history is not reproducible natively."
+    }
+  ],
+  "mappingGuidance": [
+    "Always send `source: \"MANUAL\"` — it is required, and it distinguishes imported cards from cards bought through a Wix order.",
+    "Pass a stable `idempotencyKey` derived from the source card id so a retried import cannot double-issue a card.",
+    "`expirationDate` is accepted at create, so original expiry dates are preserved.",
+    "Decide the partial-balance policy in the mapping plan and surface it in the execution plan; do not default silently.",
+    "Amounts are decimal strings with at most 2 decimal places, and currency is ISO-4217 alphabetic.",
+    "CORRECTED 2026-08-17 (VERIFIED LIVE): `currency` is a TOP-LEVEL field on the giftCard object, NOT nested inside `initialValue`. `{ giftCard: { initialValue: { amount, currency } } }` fails with `400 currency must not be empty`; the working shape is `{ giftCard: { initialValue: { amount }, currency, source, code, idempotencyKey } }`."
+  ],
+  "setupRequirements": [
+    "Wix Gift Card app installed",
+    "SCOPE.DC-ECOM-MEGA.MANAGE-ECOM"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/gift-cards/gift-cards/gift-card-object",
+      "note": "object page (docs-survey sweep 2026-08-11)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/gift-cards/gift-cards/create-gift-card"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/gift-cards/gift-cards/introduction"
+    },
+    {
+      "type": "wix-docs-search",
+      "path": "searched: gift card, stored value, voucher, store credit — across business-solutions/gift-cards and e-commerce/payments/gift-cards (2026-08-01)"
+    },
+    {
+      "type": "live-verification",
+      "path": "anonymized-live-verification",
+      "note": "Verified live after installing the Wix Gift Cards app: create and read-back succeeded through rp-target-wix/lib/gift-card-build.js and established the currency-placement and code-alphanumeric constraints. Not exercised: Send Gift Card Email, Query/Search, checkout redemption, or disabling/deleting a card."
+    }
+  ]
+}