@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/resources/rp-target-wix/domains/events/entities/rsvp.json

@@ -0,0 +1,118 @@
+{
+  "schemaVersion": 1,
+  "domain": "events",
+  "entity": "rsvp",
+  "displayName": "Event RSVP",
+  "capability": "content.event-rsvps",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Events RSVP",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [],
+  "dependsOn": ["crm/contact", "events/event", "events/registration-form"],
+  "preferredWrite": {
+    "surface": "Events RSVP V2",
+    "endpoint": "POST /events/v2/rsvps",
+    "writerId": null,
+    "verification": "verified-live",
+    "importSafe": false,
+    "bulk": false,
+    "decision": "The request shape is verified live (create + readback + delete, 2026-08-16), but importSafe stays FALSE: nothing observable proves that disableNotifications actually suppresses the guest confirmation email. The flag is accepted and echoed, and the site-wide mute was on, yet neither is a proof of non-delivery — see pitfall notification-suppression-unproven for exactly what was probed and what would settle it. Any run that needs RSVPs must surface this at the approval gate."
+  },
+  "reliability": {
+    "status": "partially-reliable",
+    "flags": []
+  },
+  "safeModeContactFields": [
+    {
+      "kind": "email",
+      "targetPath": "rsvp.email",
+      "source": "target-schema",
+      "notes": "Guest email on the RSVP create body — required, format-validated, and the key Wix uses to create/match a CRM contact."
+    }
+  ],
+  "pitfalls": [
+    {
+      "code": "notifications-default-on",
+      "severity": "blocker",
+      "summary": "RSVP creation emails the guest a confirmation unless disableNotifications is set — the domain's registration-notifications-default-on pitfall. An import that forgets the flag mass-mails migrated guests. importSafe is false until the generated script provably sets it on every call AND the suppression itself is proven."
+    },
+    {
+      "code": "notification-suppression-unproven",
+      "severity": "blocker",
+      "summary": "PROBED 2026-08-16, STILL UNPROVEN. What was established: `disableNotifications: true` is accepted on create, is persisted, and is echoed back on both the create response and a later GET (a response flag, not a delivery flag); the site was verified muted (getSiteMuteState → muted:true) before and during the probe; the guest address used a .invalid domain, so nothing could have been delivered anyway. What was NOT established: the create-rsvp docs describe the field only as \"Whether notifications are disabled\" — no statement that it covers the guest-facing confirmation email; there is no public API that lists sent emails, so non-delivery cannot be observed from the API; and the site-wide mute cannot be credited either, because its documented scope is site notifications, not proof about guest transactional mail. WHAT WOULD SETTLE IT: (a) an explicit statement from the Events team/docs that disableNotifications suppresses the guest confirmation email — ask Wix, or (b) a controlled probe on a throwaway site with a real monitored mailbox, comparing disableNotifications true vs false on an UNMUTED site (the true-vs-false pair is what makes the negative observable). Until one of those exists, keep importSafe false."
+    },
+    {
+      "code": "draft-events-reject-rsvps",
+      "severity": "blocker",
+      "summary": "DISCOVERED 2026-08-16 (live): creating an RSVP against a DRAFT event fails with 400 EVENT_NOT_FOUND — RSVP V2 does not see unpublished events. The same call succeeded immediately after POST /events/v3/events/{id}/publish. This breaks the tempting 'import events as drafts, load RSVPs quietly, publish later' plan: the event must be publicly published before its guest list can be imported, which widens the notification/visibility surface of an RSVP import."
+    },
+    {
+      "code": "rsvp-creates-a-crm-contact",
+      "severity": "blocker",
+      "summary": "CORRECTED 2026-08-16 (live): the earlier claim that RSVPs do not touch CRM is wrong. Creating one RSVP produced a new contact for the guest email with sourceType WIX_EVENTS. An RSVP import therefore writes into Contacts as a side effect — it can duplicate contacts imported by crm/contact, and it means RSVP volume is contact volume. Reconcile guest emails against the contact crosswalk before importing RSVPs, and count the contact writes in the plan. (Method note: a Contacts V4 query filtered on info.emails.email returned zero rows for a contact that plainly exists — filter fields are a closed list per endpoint, so verify by listing, not by an unsupported filter.)"
+    },
+    {
+      "code": "registration-state-blocks-create",
+      "severity": "warning",
+      "summary": "A freshly created event comes back with registration.status CLOSED_AUTOMATICALLY (no sale/RSVP window open), and create-rsvp defines RSVPS_CLOSED / RSVPS_NOT_STARTED / GUEST_LIMIT_EXCEEDED / RSVP_LIMIT_EXCEEDED failures. The 2026-08-16 probe passed options.ignoreResponseStatus:true and options.ignoreLimits:true and succeeded; which of the two was strictly required was not isolated. A historical-guest import should pass both deliberately and disclose it — they override the site's own registration rules."
+    },
+    {
+      "code": "form-response-must-match-the-event-form",
+      "severity": "warning",
+      "summary": "rsvp.form.inputValues must use the input names from the event's form (GET /events/v3/events/{id}?fields=FORM), honour mandatory inputs for YES responses, and stay inside predefined options, else INVALID_FORM_RESPONSE. The probe sent firstName/lastName/email and they round-tripped. options.ignoreFormValidation exists as an escape hatch for lossy source data. Additional guests require the event form to carry a GUEST_CONTROL control."
+    },
+    {
+      "code": "one-rsvp-per-email-per-event",
+      "severity": "warning",
+      "summary": "Duplicate guest emails on one event fail with 428 MEMBER_EMAIL_ALREADY_REGISTERED (and MEMBER_ALREADY_REGISTERED when memberId repeats) — dedupe the source guest list by email per event before writing, and make retries crosswalk-guarded."
+    },
+    {
+      "code": "rsvp-only-events",
+      "severity": "blocker",
+      "summary": "The event's registration.initialType must be RSVP and is immutable — a TICKETING event can never accept RSVPs (428 INVALID_EVENT_TYPE). Choose the registration type when creating the event from the source data."
+    },
+    {
+      "code": "past-event-rsvps-unverified",
+      "severity": "warning",
+      "summary": "Still unverified whether Create Rsvp accepts already-ended events; the 2026-08-16 probe used a far-future event. Historical RSVP import may be restricted to upcoming events — verify before planning full history."
+    }
+  ],
+  "mappingGuidance": [
+    "Dependencies: events/event must be published for the RSVP API; events/registration-form supplies accepted input names; crm/contact must exist when matching the RSVP attendee by email.",
+    "Create the event first with registration.initialType RSVP, PUBLISH it, and use its crosswalked ID in eventId — draft events are invisible to this API.",
+    "Set disableNotifications on every create call — this is the safe-import rule for the whole registration group — and still treat the write as guarded until the suppression is proven.",
+    "Map source attendee records (e.g. Event Tickets RSVPs) to firstName/lastName/email/status (YES | NO | WAITLIST) and additionalGuestDetails.guestCount/guestNames; build form.inputValues from the event's form controls.",
+    "Plan the CRM impact: each RSVP creates or matches a contact (sourceType WIX_EVENTS), so sequence RSVPs after crm/contact and reconcile by email."
+  ],
+  "setupRequirements": [
+    "Wix Events app",
+    "SCOPE.DC-EVENTS.MANAGE-GUEST-LIST"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/events/registration/rsvp-v2/rsvp-object",
+      "note": "object page: eventId, firstName/lastName/email, status, totalGuests"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/events/registration/rsvp-v2/create-rsvp",
+      "note": "disableNotifications is a field on the rsvp object (not a query param); described only as \"Whether notifications are disabled\" — no statement about the guest confirmation email"
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "The docs survey identified the RSVP import surface."
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Verified live on a muted site: RSVP creation against a draft event returned EVENT_NOT_FOUND; after publication, creation with disableNotifications:true and ignoreResponseStatus/ignoreLimits succeeded. The flag persisted on readback and Wix created a contact with sourceType WIX_EVENTS. Notification delivery remains unverified because the site was muted and the test address was undeliverable. Probe records were deleted afterward."
+    }
+  ],
+  "notes": "Authored 2026-08-11 from the docs-survey gap (RSVP V2). The write shape was promoted to verified-live on 2026-08-16, but importSafe deliberately stays FALSE — the probe could not prove that no guest email fires (see notification-suppression-unproven for the settle-it conditions). The same probe found two contradictions in the original entry: draft events reject RSVPs, and RSVP creation does create a CRM contact."
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/events/entities/ticket-definition.json

@@ -0,0 +1,93 @@
+{
+  "schemaVersion": 1,
+  "domain": "events",
+  "entity": "ticket-definition",
+  "displayName": "Event Ticket Definition",
+  "capability": "content.event-ticket-definitions",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Events Ticket Definition",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [],
+  "dependsOn": ["events/event"],
+  "preferredWrite": {
+    "surface": "Events Ticket Definitions V3",
+    "endpoint": "POST /events/v3/ticket-definitions",
+    "writerId": null,
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": false,
+    "decision": "Create with { ticketDefinition: { eventId, name, pricingMethod, feeType, initialLimit?, hidden? } }. eventId, name, pricingMethod and feeType are all required. Verified live on a DRAFT event, so definitions can be staged before the event is published; hidden:true keeps a definition unpurchasable. DELETE /events/v3/ticket-definitions/{id} works. Max 100 definitions per event."
+  },
+  "reliability": {
+    "status": "reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "definitions-not-sales",
+      "severity": "blocker",
+      "summary": "A ticket definition is the purchasable ticket type (name, price, limits) — importing it does not carry sold tickets. Past ticket sales remain not importable (domain pitfall ticket-order-history-not-importable)."
+    },
+    {
+      "code": "past-event-definitions-unverified",
+      "severity": "warning",
+      "summary": "Still unverified whether definitions attach to already-ended events (the 2026-08-16 probe used a far-future draft event). For past events the definition is likely pointless without its sales. Import definitions for upcoming events; ledger past ones."
+    },
+    {
+      "code": "ticketing-events-only",
+      "severity": "blocker",
+      "summary": "Create fails with 428 INVALID_EVENT_TYPE unless the event's registration.initialType is TICKETING, and initialType is IMMUTABLE (docs) — an event created for RSVP can never take ticket definitions. Decide RSVP vs TICKETING at event-create time from the source data; a source event with both attendee lists and ticket types cannot be represented as one Wix event."
+    },
+    {
+      "code": "name-capped-at-30-chars",
+      "severity": "warning",
+      "summary": "`name` is minLength 1 / maxLength 30 (description 500, policyText 1000). Source ticket-type names routinely exceed 30 characters — truncate deterministically and ledger it rather than letting the create 400."
+    },
+    {
+      "code": "free-ticket-fee-type",
+      "severity": "warning",
+      "summary": "VERIFIED LIVE 2026-08-16: a free ticket is pricingMethod.fixedPrice.value \"0\" plus feeType NO_FEE (the response echoes free:true, pricingType STANDARD, value normalised to \"0.00\"). NO_FEE is only accepted for free tickets and legacy users — paid tickets must pick FEE_INCLUDED or FEE_ADDED_AT_CHECKOUT, a merchant decision that belongs in the mapping review, not a default."
+    },
+    {
+      "code": "canonical-vs-alias-path",
+      "severity": "warning",
+      "summary": "The docs canonical host path is /events-ticket-definitions/v3/ticket-definitions; /events/v3/ticket-definitions is an accepted alias (both returned 200 on 2026-08-16, creating one definition each). They are the same resource — do not call both in one import or you double-create."
+    }
+  ],
+  "mappingGuidance": [
+    "Dependencies: events/event is required because ticketDefinition.eventId identifies the event that owns every ticket definition.",
+    "Create the event first with registration.initialType TICKETING and use its crosswalked ID in eventId; ticket definitions are per-event and initialType cannot be changed later.",
+    "Map source ticket types (e.g. Event Tickets ticket name/price/capacity) to name (≤30 chars), pricingMethod.fixedPrice (or pricingOptions for tiered prices, guestPrice for pay-what-you-want) and initialLimit; omit initialLimit for unlimited tickets.",
+    "Set salePeriod from the source sale window when present (startDate before endDate, else 428 INVALID_SALE_PERIOD); use hidden:true to stage definitions that should not go on sale at import time."
+  ],
+  "setupRequirements": [
+    "Wix Events app",
+    "SCOPE.DC-EVENTS.MANAGE-TICKET-DEF"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/ticket-definitions-v3/ticket-definition-object",
+      "note": "object page: eventId, name, pricingMethod, salePeriod, initialLimit, limitPerCheckout"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/ticket-definitions-v3/create-ticket-definition"
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "The docs survey identified the ticket-definition surface."
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Verified live: a free hidden ticket definition can be created on a future draft ticketing event through both the /events/v3 alias and the canonical /events-ticket-definitions/v3 path and read back successfully. Probe records were deleted afterward."
+    }
+  ],
+  "notes": "Authored 2026-08-11 from the docs-survey gap (Ticket Definitions V3). Promoted to verified-live 2026-08-16 by a create/read/delete probe on a draft ticketing event; the probe also pinned the required feeType, the 30-char name cap, and the TICKETING-only/immutable-initialType constraint."
+}

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

@@ -0,0 +1,86 @@
+{
+  "schemaVersion": 1,
+  "domain": "forms",
+  "fetchedAt": "2026-08-16",
+  "roots": [
+    "api-reference/crm/forms"
+  ],
+  "surfaces": [
+    {
+      "id": "api-reference/crm/forms/chat-settings",
+      "title": "Chat Settings",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/chat-settings",
+      "group": null,
+      "verdict": "not-relevant",
+      "reason": "Configuration for the AI chat that helps a visitor fill a form: enable/disable AI chat, greeting message, summary message. The docs state it 'works alongside the Interactive Form Sessions API' and that each form can have exactly one settings entity keyed by the form's own id. It holds no source-side record — a WordPress form has no AI-chat configuration to carry over — so there is nothing to import here. A migrated form simply has no chat settings, which is the Wix default.",
+      "reviewedOn": "2026-08-16"
+    },
+    {
+      "id": "api-reference/crm/forms/form-schema-templates",
+      "title": "Form Schema Templates",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-schema-templates",
+      "group": null,
+      "verdict": "not-importable",
+      "reason": "The API is explicitly read-only: 'App owners define templates in the app dashboard, and templates can't be created, updated, or deleted through the API.' A template is a starter definition an app publishes for its namespace, not site data — so an imported WordPress form can never become a template, and there is no write path to attempt. The page is still load-bearing for this domain as the authoritative namespace table (Wix Forms = wix.form_app.form), which forms/form depends on; it is cited in that entity's mapping guidance rather than claimed as an import target.",
+      "reviewedOn": "2026-08-16"
+    },
+    {
+      "id": "api-reference/crm/forms/form-schemas",
+      "title": "Form Schemas",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-schemas",
+      "group": null,
+      "verdict": "claimed",
+      "refs": [
+        "forms/form"
+      ],
+      "reviewedOn": "2026-08-16"
+    },
+    {
+      "id": "api-reference/crm/forms/form-submissions",
+      "title": "Form Submissions",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-submissions",
+      "group": null,
+      "verdict": "claimed",
+      "refs": [
+        "forms/form-submission"
+      ],
+      "reviewedOn": "2026-08-16"
+    },
+    {
+      "id": "api-reference/crm/forms/interactive-form-sessions",
+      "title": "Interactive Form Sessions",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/interactive-form-sessions",
+      "group": null,
+      "verdict": "not-relevant",
+      "reason": "A runtime surface, not a storage surface: it drives an AI conversation that walks a live visitor through filling a form, streaming typed response chunks (TEXT, SINGLE_SELECT_INPUT, SUBMISSION, END_OF_RESPONSE, …) and ending in a normal submission. Sessions are per-conversation state created against an already-existing form schema; there is no historical session in a WordPress source to recreate, and any record it would produce arrives through forms/form-submission anyway. Nothing to import.",
+      "reviewedOn": "2026-08-16"
+    },
+    {
+      "id": "api-reference/crm/forms/other-services/intake-forms",
+      "title": "Intake Forms",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/other-services/intake-forms",
+      "group": "Other Services",
+      "verdict": "not-relevant",
+      "reason": "A different business capability that happens to sit in the same doc tree: waivers, liability releases and consent forms with an expiration period, shareable submission links, and a submission lifecycle with extend/cancel operations. It is not the generic form-and-response capability the WordPress form plugins produce, and the docs are explicit that 'the Wix Forms app isn't required' — it is a parallel service, not a route into Wix Forms. Landing CF7/WPForms contact forms here would give every migrated enquiry an expiry clock it never had. If a source site is later found to run genuine waiver/consent forms with renewal periods, this becomes its own entity pair (intake-form + intake-form-submission); no such source exists in scope today.",
+      "reviewedOn": "2026-08-16"
+    },
+    {
+      "id": "api-reference/crm/forms/service-plugins/form-submissions-service-plugin",
+      "title": "Form Submissions Service Plugin",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/service-plugins/form-submissions-service-plugin",
+      "group": "Service Plugins",
+      "verdict": "not-relevant",
+      "reason": "Service plugin (SPI) -- adds LIVE validation on new submissions. It accepts no historical records, so it cannot carry a source submission archive. (a form plugin's historical entries are typically unreachable for an unrelated reason anyway: the answers live in a denied *meta table.) See domains/SERVICE-PLUGINS.md for the escalation rule, the cost list, a worked example and the full 25-plugin catalog.",
+      "reviewedOn": "2026-08-31"
+    },
+    {
+      "id": "api-reference/crm/forms/skills",
+      "title": "Skills",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/skills",
+      "group": null,
+      "verdict": "not-relevant",
+      "reason": "AI-agent walkthrough pages (Create Form, Forms Dashboard Navigation), not a data surface. Same verdict and rationale as pricing-plans/skills.",
+      "reviewedOn": "2026-08-16"
+    }
+  ]
+}

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

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": 1,
+  "domain": "forms",
+  "dependsOnRequired": true,
+  "docsRoots": [
+    "api-reference/crm/forms"
+  ],
+  "displayName": "Wix Forms",
+  "ownerHint": "Wix Forms (form schemas, form submissions) domain owners — the Forms APIs sit under the CRM docs tree, not Business Solutions",
+  "wixAppsRequired": [
+    "Wix Forms"
+  ],
+  "defaultImportOrder": [
+    "form",
+    "form-submission"
+  ],
+  "sharedPitfalls": [
+    {
+      "code": "forms-app-required",
+      "severity": "blocker",
+      "summary": "The Wix Forms app (`wix_forms`) must be installed before any write in this domain. The Form Submissions docs state plainly that the API 'only works with the Wix Forms app' and tell callers to confirm with GetAppInstance; Create Form additionally rejects an unknown namespace with 400 UNSUPPORTED_FORM_NAMESPACE. Verify during setup, not at import time."
+    },
+    {
+      "code": "submission-create-has-no-suppression-flag",
+      "severity": "blocker",
+      "summary": "Create Submission (POST /forms/v4/submissions) exposes exactly four inputs — submission, additionalMetadata, captchaToken — and NO notification control: no disableNotifications, no suppressNotifications, no flowControlSettings, no participantNotification. Creating a submission fires the Submission Created domain event, which is the documented trigger surface for Wix Automations (the Forms glossary calls these 'post-submission triggers: automated actions that are executed after a form submission is received'), and the site owner's 'new form submission' notification is exactly such an automation. No docs page in this tree states whether Create Submission emails anyone. Treat every submission create as a potential owner-facing and submitter-facing send until proven silent on a live site; the only control we know of is the site-wide MuteSite policy, which is not a per-call flag and is not applied to existing sites by default."
+    },
+    {
+      "code": "form-caps-and-gated-field-types",
+      "severity": "warning",
+      "summary": "Two independent limits, both enforced by FAILING the create rather than degrading. (1) Counts: each namespace has a provider-set maxForms, maxFields and maxDeletedForms, readable live with List Forms Providers Configs (GET /form-schema-service/v4/forms/providers-config); exceeding one returns 400 FORM_FIELDS_COUNT_EXCEEDED / NAMESPACE_FORMS_COUNT_EXCEEDED / FORM_SIZE_EXCEEDED. Note deleted forms occupy their own cap, so a re-run that deletes and recreates schemas can exhaust maxDeletedForms. (2) Field types: About Form Fields marks File upload and Signature as requiring a Premium plan; Product, Fixed price, Custom price and Donation as requiring Premium plan + Wix eCommerce; Appointment as requiring Wix Meetings; Service picker and Multi-service picker as requiring Wix Services. Check both during setup discovery, not at import time."
+    },
+    {
+      "code": "namespace-decides-behaviour",
+      "severity": "warning",
+      "summary": "Every form schema belongs to an app namespace, and the namespace decides both which app renders the form and what status a submission is created in. Imported WordPress forms belong in `wix.form_app.form` (Wix Forms). Do not create schemas in another app's namespace (wix.bookings.v2.bookings, wix.ecom.v1.checkout, wix.pricing_plans.v1.custom_form, …) to make a form 'appear' somewhere — those namespaces carry that app's business logic, including PENDING submissions that are deleted if never confirmed."
+    }
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/introduction",
+      "note": "domain root; menu walked 2026-08-16. NOTE: Wix Forms is NOT under api-reference/business-solutions — the whole tree lives under api-reference/crm/forms (Form Schemas, Form Submissions, Service Plugins, Chat Settings, Interactive Form Sessions, Other Services → Intake Forms, Skills, Form Schema Templates)."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/introduction",
+      "note": "'form' and 'form schema' are used interchangeably; namespace table for apps made by Wix (Wix Forms = wix.form_app.form); deleted schemas go to a 90-day trash bin and permanently deleting a schema deletes all of its submissions (read 2026-08-16)"
+    },
+    {
+      "type": "domain-kb",
+      "path": "skills/wix-replatform/SKILL.md",
+      "note": "the only notification control available to this domain is the site-level MuteSite primitive; it is applied to new target sites and is opt-in for existing sites — it is not a per-call suppression flag"
+    }
+  ]
+}

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

@@ -0,0 +1,121 @@
+{
+  "schemaVersion": 1,
+  "domain": "forms",
+  "entity": "form-submission",
+  "displayName": "Wix Form Submission",
+  "capability": "content.form-submissions",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Form Submission",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [],
+  "dependsOn": ["crm/contact", "forms/form", "media/media-file"],
+  "preferredWrite": {
+    "surface": "Form Submissions V4 (FormSubmissionService)",
+    "endpoint": "POST /forms/v4/submissions",
+    "writerId": null,
+    "verification": "verified-live",
+    "importSafe": false,
+    "bulk": false
+  },
+  "reliability": {
+    "status": "partially-reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "create-notification-behavior-undocumented",
+      "severity": "blocker",
+      "summary": "OBSERVED 2026-08-16, full method-parameter list of Create Submission read end to end: the call accepts exactly `submission`, `additionalMetadata` and `captchaToken`. There is NO disableNotifications, no suppressNotifications, no flowControlSettings, no participantNotification, and no `sendEmail`-style toggle anywhere on the Form Submissions surface; the words 'notification' and 'email' do not appear on the Create Submission, Submission Object, Confirm Submission or Form Submissions Introduction pages at all. What IS documented: creating a submission fires the `Submission Created` domain event, and the Form Schemas glossary defines 'post-submission trigger' as 'automated actions that are executed after a form submission is received' — i.e. the Wix Automations hook that the default 'new form submission' owner email rides on. Suppression therefore cannot be proven from the docs, so importSafe stays false, exactly as for events/rsvp. The only control we have is the site-wide MuteSite policy, which is not a per-call flag, is applied by default only to newly created target sites, and has not been verified to cover the Automations email path. PARTIAL LIVE DATA POINT 2026-09-16: MuteSite was applied before a bulk historical import through this endpoint (one single test submission first, then the full batch) and no notification complaint was raised — but no inbox check covered every record, so this is supporting evidence for MuteSite as the mitigation, not proof Create Submission is itself silent. Keep muting for any future bulk write through this endpoint until a dedicated probe (a throwaway form + a mailbox checked in real time) settles the underlying question."
+    },
+    {
+      "code": "submitter-is-read-only",
+      "severity": "blocker",
+      "summary": "`submitter` (the oneOf memberId / visitorId / applicationId / userId) is READ-ONLY on both the request and the response — the original submitter cannot be set. A migrated submission will be attributed to the importing identity, not to the person who filled the WordPress form. The one identity field that IS settable at create is `contactId` (GUID, immutable), so submitter attribution has to be carried as a contact reference resolved through the CRM contacts crosswalk, and the loss of the true submitter identity must be ledgered rather than papered over."
+    },
+    {
+      "code": "backdating-is-documented-but-unverified",
+      "severity": "warning",
+      "summary": "`createdDate` IS a request field on Create Submission (format date-time, `immutable`, and — unlike id / namespace / updatedDate / revision / submitter — NOT marked read-only), so the docs say a submission can be created carrying its original date and that the date cannot be changed afterwards. Whether the server actually honours a past createdDate rather than overwriting it with now is not stated anywhere and has not been probed live. Verify on a throwaway form before promising historical fidelity; if it is overwritten there is no Update Submission path back, because the field is immutable."
+    },
+    {
+      "code": "unknown-key-fails-the-whole-submission",
+      "severity": "blocker",
+      "summary": "Every key in `submissions` must be the `target` of a field in the form's schema. A single key that is not a target is rejected as UNKNOWN_VALUE_ERROR and fails the ENTIRE submission — not just that value. WordPress submission stores keep whatever field names the form had at the time, so a form that was edited after some submissions were taken will have historical records carrying retired field names. Reconcile every record's keys against the created schema's targets before writing, and route unmatched values to a ledgered overflow (or add a hidden catch-all field) rather than letting one stale key drop a whole message."
+    },
+    {
+      "code": "status-is-namespace-dependent-not-chosen",
+      "severity": "blocker",
+      "summary": "The status a submission is created with depends on the form's namespace and on whether the form collects payment; the docs say to read `status` from the response rather than assume it. LIVE-VERIFIED (upgraded from warning to blocker): for `wix.form_app.form` without payment, Create Submission's response ALWAYS reads PENDING first -- there is no immediate-CONFIRMED case for this namespace, and a codegen path that treats the create response's status as final (whether it expects CONFIRMED or treats PENDING as a stop signal) is wrong either way. An ASYNC SPAM-FILTER PASS then resolves that PENDING to one of two outcomes within 1-2 seconds: CONFIRMED (stored), or silent deletion (GET on the id then returns 404 NOT_FOUND -- confirmed within 3 seconds and stable on repeated re-checks over several minutes, so this is not eventual consistency, it is a real content-based decision). Two live-confirmed causes of deletion, both risking real data loss on a historical bulk import: (1) bot-like WORDING -- a submission whose text read like a migration self-test ('Migration test', 'confirming no notification fires...') was reliably deleted even though the exact same field shape with natural wording confirmed every time; (2) a GENUINE customer record was ALSO deleted as a false positive (real name/email/phone/message content) purely because the form's `spamFilterProtectionLevel` was 'ADVANCED' -- the same content resubmitted after PATCHing the target form's `spamFilterProtectionLevel` to 'NONE' confirmed immediately. A THIRD, unrelated class also surfaced: a large fraction of a historical dataset can turn out to be an actual automated SQL-injection scanner sweep (boolean-blind and time-based payloads sent across a several-minute burst) that the filter correctly deleted -- this is a genuine reason to exclude data, not a false positive, and should be identified independently (a tight creation-timestamp cluster proved far more reliable than matching individual payload signatures, which kept missing new variants) and excluded BEFORE attempting the write, not left for the filter to catch. Required practice for any bulk historical import through this endpoint: (a) lower the TARGET form's spamFilterProtectionLevel to NONE for the duration of the import if false positives on real content are unacceptable, (b) after every create, POLL by re-fetching the submission id (2-3 attempts, ~2s apart) and only count it as landed once status reads CONFIRMED -- a 404 on re-fetch is definitive proof of loss, not a transient error, (c) never trust the initial create response's PENDING status as either success or failure -- it is neither, it is provisional."
+    },
+    {
+      "code": "no-bulk-create",
+      "severity": "warning",
+      "summary": "There is no bulk create for submissions — the tree offers Bulk Mark Submissions As Seen and nothing else. Every historical message is one POST, so a store with thousands of Flamingo inbound messages is a long, rate-limited, one-record-at-a-time import that must be checkpointed and resumable. (Form SCHEMAS do have Bulk Create Form; submissions do not.)"
+    },
+    {
+      "code": "file-uploads-need-a-separate-upload-step",
+      "severity": "warning",
+      "summary": "Values for WIX_FILE fields are not URLs from the source site: the documented path is Get Media Upload URL, upload the file, then reference the resulting media in the submission. A WordPress attachment URL passed straight through will not resolve, so file-upload answers require the media import to run first and the submission import to consume its crosswalk."
+    },
+    {
+      "code": "seen-flag-should-be-set-on-import",
+      "severity": "info",
+      "summary": "`seen` is settable at create. Historical submissions imported from another platform were already read by the owner there; leaving `seen` false lands the whole history in the dashboard as unread and, on top of any notification behaviour, makes the migration look like a flood of new leads. Set seen:true for imported history unless the user asks otherwise."
+    }
+  ],
+  "mappingGuidance": [
+    "Dependencies: forms/form supplies required formId and field targets; crm/contact is required when contactId is crosswalked; media/media-file is required for file-upload answer IDs.",
+    "Import order is strict: forms/form (the schema) first, then contacts/members if contactId is to be populated, then media for any file-upload answers, then submissions. formId is required and is the crosswalked Wix schema id.",
+    "Build `submissions` as a map keyed by the schema field's `target` — the value shape follows that field's inputType: STRING (including date and time fields), NUMBER, BOOLEAN, ARRAY (array of selected option values), ADDRESS (address object), PAYMENT (array of product objects), SCHEDULING (appointment object). The source-field-name -> target map written by the forms/form step is the input to this.",
+    "Set `createdDate` to the source submission's original timestamp (Flamingo inbound messages carry post_date; the CSV export carries a `Date` column produced by get_post_time('c')) and verify on the first record that the value came back unchanged before importing the rest.",
+    "Resolve `contactId` from the submission's email through the CRM contacts crosswalk where a contact exists; leave it unset otherwise. Do not attempt to set `submitter` — it is read-only.",
+    "Set `seen: true` on imported history so a migration does not present years of answered enquiries as new unread leads.",
+    "LIVE-VERIFIED 2026-09-16 (supersedes the older 'anything but CONFIRMED on create is a stop signal' guidance): Create Submission for `wix.form_app.form` ALWAYS returns PENDING first, then an async spam-filter pass resolves it to CONFIRMED (stored) or silent deletion within 1-2 seconds -- PENDING on the immediate create response is the NORMAL case, not a stop signal. Only CONFIRMED means the record is stored; do not stop on an initial PENDING, and do not treat a bare create-response read as proof either way. Poll (2-3 attempts, ~2s apart) and only count a submission as landed once a re-fetch reads CONFIRMED -- a 404 on re-fetch is definitive proof of loss. See the status-is-namespace-dependent-not-chosen pitfall below for the full mechanism, causes of false-positive deletion, and required practice.",
+    "Until the notification behaviour is proven silent, treat this as a guarded write: run the first record against a throwaway form on the target site with a mailbox the team controls, confirm nothing was sent to the owner or the submitter, and only then release the batch. If a send is observed, the fallback is not 'skip the data' — it is site-level MuteSite for the import window, or landing the history in a CMS collection with its original ids and re-deciding at the gate.",
+    "Spam-flagged source records (Flamingo's flamingo-spam post status, Akismet meta) should be filtered out before import rather than recreated. LIVE-VERIFIED 2026-09-16: this is in ADDITION to Wix's own spam filter, not instead of it -- Wix's spamFilterProtectionLevel DOES evaluate every API-created submission (see the pitfall below); the older claim that it does not re-evaluate API-created submissions was wrong and is corrected there."
+  ],
+  "setupRequirements": [
+    "Wix Forms app installed (`wix_forms`; the Form Submission API only works with it — confirm with GetAppInstance)",
+    "SCOPE.DC-FORMS.MANAGE-SUBMISSIONS (Manage Submissions)",
+    "The target form schema created and crosswalked first (404 FORM_NOT_FOUND otherwise)",
+    "Target site must not be a template (428 SITE_IS_A_TEMPLATE)",
+    "Notification decision taken at the execution-plan gate: either a live probe proving Create Submission is silent, or site-level MuteSite for the import window"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/submission-object",
+      "note": "object page: id, formId, namespace, status enum (PENDING/CONFIRMED/PAYMENT_WAITING/PAYMENT_CANCELED), submissions map keyed by field target, createdDate/updatedDate, revision, submitter, seen, extendedFields, orderDetails, contactId, accessRestriction, tags, appointmentDetails (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/create-submission",
+      "note": "POST https://www.wixapis.com/forms/v4/submissions; scope SCOPE.DC-FORMS.MANAGE-SUBMISSIONS; required submission + submission.formId; settable createdDate (date-time, immutable), seen, contactId (immutable), accessRestriction, tags, extendedFields; read-only id/namespace/updatedDate/revision/SUBMITTER; only additionalMetadata and captchaToken beyond the submission — NO notification/suppression parameter of any kind; errors SUBMISSION_VALIDATION, FORM_NOT_FOUND, SITE_IS_A_TEMPLATE, INVALID_CAPTCHA, FORM_RETRIEVAL_ERROR (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/introduction",
+      "note": "a key that is not a field target fails the whole submission (UNKNOWN_VALUE_ERROR); status-on-creation table; validation error shape (errorPath/errorType/errorMessage/params). No mention of notifications or emails anywhere on the page (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/submission-created",
+      "note": "the Submission Created domain event fires on create — the trigger surface Wix Automations (and therefore the owner's 'new form submission' email) hangs off; the webhook page documents no way to create a submission without emitting it (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/about-submission-values",
+      "note": "per-inputType value shapes (ADDRESS/PAYMENT/SCHEDULING objects), keys come from field targets, one rejected value fails the whole submission (read 2026-08-16)"
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-target-wix/domains/events/entities/rsvp.json",
+      "note": "precedent: importSafe:false when a create call's member-notification behaviour cannot be proven suppressed from the docs"
+    }
+  ],
+  "notes": "Authored 2026-08-16 (forms vertical). Docs-verified only. Two honest negatives recorded rather than guessed: the submitter CANNOT be set (read-only; contactId is the only settable identity), and notification behaviour CANNOT be proven safe — Create Submission has no suppression flag at all and fires Submission Created, which is the documented automation trigger. Backdating IS documented as settable (createdDate is a non-read-only, immutable request field) but has not been verified live, which is the single highest-value probe to run next on this entity."
+}