@wix/agent-skills 1.33.1 → 1.35.0

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

@@ -0,0 +1,75 @@
+{
+  "schemaVersion": 1,
+  "domain": "bookings",
+  "dependsOnRequired": true,
+  "docsRoots": [
+    "api-reference/business-solutions/bookings",
+    "api-reference/business-management/calendar"
+  ],
+  "displayName": "Wix Bookings",
+  "ownerHint": "Bookings (services, bookings, sessions/schedules, availability, staff, resources, policies) domain owners",
+  "wixAppsRequired": [
+    "Wix Bookings"
+  ],
+  "defaultImportOrder": [
+    "service",
+    "service-add-on",
+    "booking"
+  ],
+  "sharedPitfalls": [
+    {
+      "code": "bookings-app-not-installed-by-default",
+      "severity": "blocker",
+      "summary": "The Wix Bookings app (appDefId 13d21c63-b5ec-5912-8397-c3a5ddb27a97) must be installed before any write in this domain, and it is not present on a fresh headless site. The app id is documented on the Booking object (booking.appId) and the Booking Policy object (policy.appId), which both state that entities are displayed in Wix Bookings only when associated with that app id or with no app id at all. Verified live 2026-08-12: `/bookings/v2/services` and `/bookings/v2/resources/query` both answer with ordinary 200s/validation errors (never an 'app not installed' error) even when the app instance is absent from `GET /apps-installer-service/v1/app-instances` — a plausible response from either endpoint is not proof the app is installed. Create Service instead fails with a plain 'form Form with id 00000000-0000-0000-0000-000000000000 doesn't exist', which reads like a form problem but is actually the app-install gap. Install it first (see rp-execute-setup SKILL.md 'Installing / enabling Wix apps'); doing so auto-provisions the default booking form and one default 'Business Owner' staff resource as a side effect. Treat the install as a setup gate, mirroring pricing-plans-app-required."
+    },
+    {
+      "code": "bookings-is-notification-heavy",
+      "severity": "blocker",
+      "summary": "Wix Bookings sends customer-facing email and SMS on booking lifecycle transitions. Two documented request-level controls exist on Bookings Writer V2 and they point in OPPOSITE directions: participantNotification.notifyParticipants defaults to false (the ad-hoc message is off unless asked for), while sendSmsReminder defaults to TRUE - an SMS goes to contactDetails.phone 24 hours before the session unless every create call explicitly sets sendSmsReminder:false. Neither flag is documented to govern the site's own Bookings automation emails (booking confirmation, reminders, staff alerts), and no suppression flag for those is documented anywhere in the tree. Until that is proven, every booking write in this domain is a guarded write: importSafe stays false and the site-wide notification mute is the only control we can actually prove."
+    },
+    {
+      "code": "staff-and-resources-are-a-prerequisite-graph",
+      "severity": "warning",
+      "summary": "An appointment service cannot be created without at least one entry in staffMemberIds, and those are RESOURCE GUIDs (staffMember.resourceId), not staff-member GUIDs - the Create Service page says so explicitly. A source platform that models 'who provides this' loosely (or not at all, as WooCommerce booking-product plugins generally do) still needs a staff member provisioned on Wix first. Treat staff/resource provisioning as a setup step that precedes the service import, and record the placeholder staff member in the faithfulness ledger when the source has no provider concept. Note that installing the Bookings app auto-provisions one default 'Business Owner' staff resource that can be reused."
+    },
+    {
+      "code": "category-required-for-visibility",
+      "severity": "warning",
+      "summary": "Create Service documents that a service without an assigned category.id is not visible on the live site. Category assignment is therefore part of a correct service import, not cosmetic; Categories V2 (Create Category) is the surface, and the source's product category is the natural input."
+    },
+    {
+      "code": "session-is-not-a-bookings-endpoint",
+      "severity": "warning",
+      "summary": "A Service's one-time or recurring date/time is not written through any '/bookings/v2/...' endpoint. It is an ordinary Calendar V3 event (`POST /calendar/v3/events`) on the schedule the service auto-creates (`service.schedule.id`). See domains/bookings/entities/service.json evidence and rp-target-wix/lib/wix-writers.js `createCalendarEvent`."
+    }
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/architecture",
+      "note": "domain root; menu walked 2026-08-16 (Services, Staff Members, Resources, Pricing, Policies, Time Slots, Bookings, Calendar, Skills)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/calendar",
+      "note": "second docs root: Bookings' own Calendar > Schedules and Sessions menu node is EMPTY - the schedule/session/participation surfaces live under Business Management > Calendar (Schedules V3, Schedule Time Frames V3, Events V3, Event Views V3, Participations V3). Verified by fetching both menu pages 2026-08-16; the Service object's schedule.id field links straight into that tree."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/create-service"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/wix-forms-integration"
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-source-wordpress/plugins/mwb-bookings-for-woocommerce.json",
+      "note": "the source side this domain was authored against: WPS Bookings for WooCommerce 3.12.0, live on an anonymized verification environment 2026-08-16"
+    },
+    {
+      "type": "live-verification",
+      "path": "anonymized-live-verification"
+    }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/bookings/entities/booking.json

@@ -0,0 +1,181 @@
+{
+  "schemaVersion": 1,
+  "domain": "bookings",
+  "entity": "booking",
+  "displayName": "Booking",
+  "capability": "commerce.bookings",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Booking",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "dependsOn": [
+    "bookings/service",
+    "crm/contact"
+  ],
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "bookingOrderLineItem",
+      "sourcePlugin": "mwb-bookings-for-woocommerce",
+      "routes": [
+        "/wc/v3/orders"
+      ],
+      "confidence": "medium"
+    }
+  ],
+  "preferredWrite": {
+    "surface": "Bookings Writer V2",
+    "endpoint": "POST /bookings/v2/bookings",
+    "writerId": null,
+    "verification": "docs",
+    "importSafe": false,
+    "bulk": true,
+    "decision": "importSafe is FALSE and this is the blocking entity of the domain. An import path demonstrably EXISTS on paper - Create Booking accepts an arbitrary bookedEntity.slot.startDate/endDate, status CONFIRMED is settable at create by an identity with Manage Bookings permissions, and flowControlSettings.skipAvailabilityValidation exists precisely to bypass availability - so this is not a missing-capability gap. It is a notification-safety gap. sendSmsReminder DEFAULTS TO TRUE: unless every single create call explicitly sends sendSmsReminder:false, Wix Bookings is instructed to text contactDetails.phone 24 hours before the session. That default points the wrong way for an import, it is the only request-level control whose scope is documented in delivery terms, and it says nothing at all about the site's own Bookings confirmation and reminder emails. Nothing in the tree documents a suppression flag for those. See notification-suppression-unproven for exactly what would settle it. Until then every booking write is a guarded write that must be surfaced at the approval gate, and the site-wide mute is the only control we can actually point at."
+  },
+  "reliability": {
+    "status": "unknown",
+    "flags": []
+  },
+  "safeModeContactFields": [
+    {
+      "kind": "email",
+      "targetPath": "booking.contactDetails.email",
+      "source": "target-schema",
+      "notes": "Customer email on the booking. The Booking object states outright: 'If no contact with this email exist, a new contact is created' - so this field silently writes into CRM as well as Bookings."
+    },
+    {
+      "kind": "phone",
+      "targetPath": "booking.contactDetails.phone",
+      "source": "target-schema",
+      "notes": "The SMS destination. Create Booking: 'the customer receives an SMS 24 hours before the session starts. The phone number is taken from contactDetails.phone' - and sendSmsReminder defaults to true. In safe mode this field is the single highest-risk value in the domain."
+    }
+  ],
+  "pitfalls": [
+    {
+      "code": "sms-reminder-defaults-to-true",
+      "severity": "blocker",
+      "summary": "sendSmsReminder has 'Default: true' on both Create Booking and Bulk Create Booking (read 2026-08-16). This is the inverse of every other notification control the KB has met - events/rsvp's disableNotifications and this API's own participantNotification.notifyParticipants both default to OFF, so a generated payload built from the required-field list alone is SAFE there and UNSAFE here. Omitting the flag opts every migrated customer into an SMS to their real phone number. Every create call in the generated script must set sendSmsReminder:false explicitly, and the script's own test must assert its presence on every element of a bulk request, not just the first."
+    },
+    {
+      "code": "notification-suppression-unproven",
+      "severity": "blocker",
+      "summary": "UNPROVEN AS OF 2026-08-16 - docs only, no live probe. What IS established from the docs: exactly two request-level notification controls exist on Create Booking / Bulk Create Booking, participantNotification.notifyParticipants (default false, governs an ad-hoc message the caller supplies in participantNotification.message, delivered over channels named in metadata as EMAIL and/or SMS) and sendSmsReminder (default TRUE, governs a 24-hours-before SMS to contactDetails.phone). What is NOT established: neither flag is documented to govern the SITE's own Wix Bookings automation - the booking confirmation email, the reminder emails, the staff/owner 'new booking' alert - and no suppression flag for those appears anywhere on the Bookings Writer V2 pages. Confirm Booking has the same two controls and no more. So an import that sets sendSmsReminder:false and leaves notifyParticipants at its false default has silenced the two documented channels and has NO documented control over the rest. WHAT WOULD SETTLE IT: (a) a statement from the Bookings team, or in the docs, enumerating which automations a Create Booking with status CONFIRMED triggers and whether any request-level flag suppresses them (ask Wix); or (b) a controlled probe on a throwaway site with a real monitored mailbox and a real monitored phone number, creating one booking with the flags set and one without on an UNMUTED site - the pair is what makes the negative observable, exactly as recorded for events/rsvp. Until one exists, importSafe stays false."
+    },
+    {
+      "code": "past-dated-bookings-unverified",
+      "severity": "blocker",
+      "summary": "THE OPEN QUESTION FOR HISTORICAL IMPORT, and the docs do not answer it in either direction. Nothing on the Booking object, Create Booking, or Bulk Create Booking pages restricts bookedEntity.slot.startDate/endDate to the future, states a minimum date, or lists a past-date error - the documented failures are 403 UNAUTHORIZED_OPERATION and 428 VALIDATION_FAILURE ('Verify all required booking fields are provided and valid'), which is generic enough to swallow a past-date rejection without naming it. Do NOT read that silence as permission: the same silence around draft events in events/rsvp turned out to be a hard 400 the moment it was probed live. flowControlSettings.skipAvailabilityValidation is documented for availability CONFLICTS ('the booking is created regardless of availability conflicts'), not for time travel, so it may or may not cover a slot that has already elapsed. WHAT WOULD SETTLE IT: one create call against a past slot on the test site, with and without skipAvailabilityValidation - it is a single cheap probe and it decides whether this domain can carry booking history at all or only forward-dated bookings. Plan the import as if past bookings may be rejected until that probe is run."
+    },
+    {
+      "code": "payment-status-is-ignored-at-create",
+      "severity": "blocker",
+      "summary": "'All bookings are created with paymentStatus=UNDEFINED, ignoring the payment status you specify.' A historical booking that was paid in the source therefore CANNOT be imported paid in one call - the field is accepted and discarded. The documented way to set it is a second call, Confirm Booking (or Confirm or Decline Booking), which 'also updates the booking's paymentStatus, if you specify a new payment status'. This collides with the next pitfall: Confirm Booking only accepts bookings whose status is PENDING, CREATED or WAITING_LIST, so a booking created directly as CONFIRMED has ALREADY BURNED its one chance to set a payment status through this path. The correct sequence for a paid historical booking is create as CREATED, then Confirm Booking with revision and paymentStatus - never create as CONFIRMED first."
+    },
+    {
+      "code": "created-is-invisible-confirmed-needs-permission",
+      "severity": "blocker",
+      "summary": "Create Booking defaults to status=CREATED, and 'such bookings aren't visible in the Booking Calendar' - an import that leaves the default produces records the site owner cannot see in the product they actually use, which will read as a failed migration. Setting status=CONFIRMED at create is possible but restricted: 'Only identities with Manage Bookings permissions can set status=CONFIRMED.' Two knock-on facts: for appointment services Wix Bookings only populates bookedEntity.slot.eventId (i.e. creates the calendar session) when the status becomes CONFIRMED, so an unconfirmed import leaves no calendar footprint at all; and confirmation is also the moment most likely to trigger customer-facing automation, which is why this interacts directly with notification-suppression-unproven."
+    },
+    {
+      "code": "booking-creates-a-crm-contact",
+      "severity": "blocker",
+      "summary": "contactDetails.email on the Booking object: 'If no contact with this email exist, a new contact is created.' A booking import therefore writes into Contacts as a side effect - it can duplicate contacts already imported by crm/contact, and booking volume becomes contact volume. This is the same trap that was CORRECTED live for events/rsvp on 2026-08-16, where the KB had wrongly claimed RSVPs do not touch CRM; take the documented statement at face value here rather than repeating that mistake. Sequence bookings after crm/contact, reconcile source customers by email, and pass the crosswalked contactDetails.contactId so Wix matches instead of creating. Count the contact writes in the plan."
+    },
+    {
+      "code": "class-bookings-need-a-session-that-nothing-imports",
+      "severity": "blocker",
+      "summary": "The three service types take three different bookedEntity shapes and only one of them is self-sufficient. APPOINTMENT: bookedEntity.slot with startDate/endDate/resource/location - Wix Bookings creates the session itself on confirmation, so the import is complete. CLASS: bookedEntity.slot.eventId, a GUID of an EXISTING calendar event, and 'when you specify eventId, Wix Bookings automatically derives startDate, endDate, timezone, resource, and location based on the event details. Manually specified values are ignored' - so a class booking is impossible until the session exists. COURSE: bookedEntity.schedule.scheduleId. No entity in this domain creates class sessions or course schedules; that is the recorded events-v3 gap in the docs survey. Consequence for bookings/service's own mapping rule - a source booking product with per-slot capacity greater than 1 becomes a CLASS - is that such products can have their SERVICE imported but not their BOOKINGS. Detect the capacity>1 branch during planning and disclose it at the approval gate."
+    },
+    {
+      "code": "bulk-create-caps-at-twelve",
+      "severity": "warning",
+      "summary": "Bulk Create Booking (POST /bookings/v2/bulk/bookings/create) validates createBookingsInfo as minItems 1 / maxItems 12 - 'Max: 12 bookings'. That is an order of magnitude tighter than the sibling bulk endpoints this KB has met (Bulk Create Services 100, Bulk Create Add Ons 100), so a booking history of any size is a long chain of small calls: budget the run time and the rate-limit headroom accordingly, and make every batch crosswalk-guarded so a mid-chain failure resumes instead of duplicating. bulk is recorded as true because the endpoint exists, not because it is efficient."
+    },
+    {
+      "code": "flow-control-overrides-need-app-permissions",
+      "severity": "warning",
+      "summary": "The overrides an import actually needs each carry their own permission beyond Manage Bookings: skipBusinessConfirmation requires BOOKINGS.OVERRIDE_AVAILABILITY, skipSelectedPaymentOptionValidation requires BOOKINGS.MANAGE_PAYMENTS, skipAddOnValidation requires BOOKINGS.MANAGE_ADDONS, and skipAvailabilityValidation warns to 'make sure the call's identity has the required permissions'. A run that discovers this at import time fails with 403 UNAUTHORIZED_OPERATION per call. Verify the identity's permissions during setup, and note that the docs' own remedies - a higher app permission, or Velo elevation - are deliberate escalations that belong in the approval-gate disclosure, not in silently generated code."
+    },
+    {
+      "code": "a-site-installed-validation-plugin-can-veto-every-write",
+      "severity": "warning",
+      "summary": "The Bookings Validation Service Plugin lets a site (or an installed app) implement Validate Before Create and reject bookings by its own rules. On a target site that has one, an import can be refused for reasons that exist in no Wix doc and in no error the KB can enumerate ahead of time. Check for installed validation extensions during setup, and treat an unexplained systematic create failure as this before assuming the payload is wrong."
+    },
+    {
+      "code": "participants-are-a-required-one-of",
+      "severity": "warning",
+      "summary": "'You must specify either participantsChoices or totalParticipants.' Use totalParticipants (minimum 1) only when the service has fixed pricing and no variants; use participantsChoices when the service has service options and variants, and 'the call fails if the specified participantsChoices aren't among the supported service options and variants'. Since bookings/service maps source products to FIXED pricing with no variants, totalParticipants is the correct branch for this vertical - but it must be sent, as neither is defaulted."
+    },
+    {
+      "code": "selected-payment-option-required-only-for-wix-checkout",
+      "severity": "info",
+      "summary": "selectedPaymentOption (UNDEFINED | OFFLINE | ONLINE | MEMBERSHIP | MEMBERSHIP_OFFLINE) is required when the customer pays through a Wix eCommerce checkout, and the Create Booking call fails without it; 'for custom checkouts, you don't have to specify this field'. A historical import is neither - it recreates a settled record, not a purchase. OFFLINE is the honest value for a booking that was paid on the source platform's gateway, since that money never lands in Wix; skipSelectedPaymentOptionValidation exists if the chosen option is not among those the service offers."
+    },
+    {
+      "code": "revision-is-required-on-every-follow-up-call",
+      "severity": "info",
+      "summary": "Confirm Booking's only required parameter is revision, and revision 'increments by 1 each time the booking is updated, rescheduled, or canceled'. Any two-phase import (create, then confirm with paymentStatus) must carry the revision returned by the create response into the second call - do not assume 1, and re-read the booking if a retry loses the value."
+    }
+  ],
+  "mappingGuidance": [
+    "Order this entity LAST in the domain: it needs a crosswalked service GUID (bookedEntity.slot.serviceId), the staff member's resource GUID, add-on and add-on-group GUIDs for bookedAddOns, and a CRM contact to match against. domain.json's defaultImportOrder service -> service-add-on -> booking is that dependency chain.",
+    "Two-phase per booking, and the order matters: (1) POST /bookings/v2/bookings with status omitted (CREATED), sendSmsReminder:false, no participantNotification, flowControlSettings as required by the source's confirmation rules; (2) POST /bookings/v2/bookings/{id}/confirm with the revision from step 1 plus paymentStatus (PAID for a settled source order, NOT_PAID otherwise, EXEMPT for a free booking). Creating as CONFIRMED in one call is possible with Manage Bookings but forfeits the ability to set paymentStatus, because Confirm Booking only accepts PENDING/CREATED/WAITING_LIST.",
+    "Map the source booking window to bookedEntity.slot.startDate/endDate in ISO-8601, and ALWAYS send bookedEntity.slot.timezone as an IANA name - the docs state the slot is permanently redisplayed to the customer in the timezone captured at booking time, so a wrong timezone here is a permanent per-record defect, not a display setting that can be fixed later.",
+    "bookedEntity.slot.resource.id is the staff member's RESOURCE GUID (the same resourceId that bookings/service puts in staffMemberIds), not a staff-member GUID. Specifying it triggers an availability check that fails the call if the resource is busy; omitting it defers resource assignment to confirmation. For a historical import against a single placeholder staff member, expect self-collisions across back-to-back source bookings and plan on flowControlSettings.skipAvailabilityValidation.",
+    "contactDetails: send the crosswalked contactId together with firstName/lastName/email/phone so Wix matches the existing contact instead of minting a new one. Do NOT also send formSubmission unless the booking form data is genuinely being migrated - when formSubmission is present Wix overwrites every contactDetails field from it and ignores what you sent, except contactId.",
+    "Source booking status maps onto the enum CREATED | CONFIRMED | CANCELED | PENDING | DECLINED | WAITING_LIST. CANCELED is reachable at create only as a literal status value; the Cancel Booking method is a lifecycle call whose notification behaviour is unexamined, so prefer setting the status over calling the lifecycle method during an import.",
+    "externalUserId is a free string on the Booking object and is the natural place to park the source booking id as a secondary key alongside the crosswalk. extendedFields exists but, as everywhere else in Wix, requires a schema-plugin app namespace configured in the app dashboard first - it is not a free-form carry.",
+    "totalParticipants (minimum 1) is the correct participant branch for this vertical; participantsChoices is only for services carrying options and variants, which bookings/service does not create.",
+    "Every booking that reaches Wix also reaches CRM. Reconcile the source customer list against the contact crosswalk before this step runs and count the contact writes in the plan report."
+  ],
+  "setupRequirements": [
+    "Wix Bookings app installed (appId 13d21c63-b5ec-5912-8397-c3a5ddb27a97) - see the bookings-app-required shared pitfall",
+    "SCOPE.DC-BOOKINGS.MANAGE-BOOKINGS - also the permission that gates setting status=CONFIRMED at create",
+    "BOOKINGS.OVERRIDE_AVAILABILITY, BOOKINGS.MANAGE_PAYMENTS and BOOKINGS.MANAGE_ADDONS if the corresponding flowControlSettings overrides are used",
+    "bookings/service and bookings/service-add-on imported, with service, resource, add-on and add-on-group GUIDs in the crosswalk",
+    "crm/contact imported and reconciled by email, because every booking create touches Contacts",
+    "Site-wide notification mute confirmed active before any write, since it is the only suppression control this entity can actually point at",
+    "At least one staff member provisioned, with its resourceId known"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/booking-object",
+      "note": "object page: status enum CREATED|CONFIRMED|CANCELED|PENDING|DECLINED|WAITING_LIST with per-value semantics, paymentStatus enum UNDEFINED|NOT_PAID|PAID|PARTIALLY_PAID|REFUNDED|EXEMPT|FAILED, selectedPaymentOption enum, contactDetails.email creates a contact when none matches, bookedEntity slot-vs-schedule ONE-OF, bookedAddOns snapshot fields (maxItems 21), externalUserId, revision, appId 13d21c63-b5ec-5912-8397-c3a5ddb27a97, formSubmissionId/formId (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking",
+      "note": "POST https://www.wixapis.com/bookings/v2/bookings (schema header also shows the internal /_api/bookings-service/v2/bookings form); permission SCOPE.DC-BOOKINGS.MANAGE-BOOKINGS; booking required, bookedEntity required, participantsChoices|totalParticipants required ONE-OF; 'Create Booking defaults to status=CREATED. Such bookings aren't visible in the Booking Calendar. Only identities with Manage Bookings permissions can set status=CONFIRMED'; 'All bookings are created with paymentStatus=UNDEFINED, ignoring the payment status you specify'; sendSmsReminder Default: true; participantNotification.notifyParticipants Default: false; flowControlSettings skipAvailabilityValidation / skipBusinessConfirmation / skipSelectedPaymentOptionValidation / skipAddOnValidation with their per-flag permissions; class bookings derive everything from eventId; errors 403 UNAUTHORIZED_OPERATION and 428 VALIDATION_FAILURE, and NO documented past-date restriction (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/bulk-create-booking",
+      "note": "POST https://www.wixapis.com/bookings/v2/bulk/bookings/create; createBookingsInfo minItems 1, maxItems 12 ('Max: 12 bookings'); the same sendSmsReminder Default: true and participantNotification defaults repeat per element, so the unsafe default is per-booking not per-request (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/confirm-booking",
+      "note": "POST https://www.wixapis.com/bookings/v2/bookings/{bookingId}/confirm; required parameter revision; 'You can only confirm bookings with a status of PENDING, CREATED, or WAITING_LIST'; 'Also updates the booking's paymentStatus, if you specify a new payment status'; same two notification controls and no others (read 2026-08-16)"
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-target-wix/domains/events/entities/rsvp.json",
+      "note": "the importSafe:false pattern this entry follows, and the two live corrections it warns against repeating: documented silence about a precondition (draft events) turned out to be a hard rejection, and a KB claim that guest records do not touch CRM turned out to be wrong"
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-source-wordpress/plugins/mwb-bookings-for-woocommerce.json",
+      "note": "the source profile this domain was authored against; the live WP test site carried no booking records, so the source-to-booking FIELD mapping could not be observed - the /wc/v3/orders route claim in sourceAliases rests on the storage model, not on an observed payload"
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-source-wordpress/plugins/mwb-bookings-for-woocommerce.json",
+      "note": "sourceAliases added 2026-08-16 from the live probe of WPS Bookings for WooCommerce 3.12.0: the plugin registers NO booking post type and NO booking order type (authed /wp/v2/types on an anonymized verification environment carries neither), so a booked appointment on WooCommerce is an ORDER LINE ITEM on /wc/v3/orders, flagged by order meta mwb_order_type='booking' and carrying its window in line-item meta (_wps_single_cal_date_time_from/_to, _wps_single_cal_booking_dates, or legacy _mwb_bfwp_date_time_from/_to). confidence 'medium': the route and the key names are established from the live REST index plus the published 3.12.0 source, but no booking order was available on the test site, so no payload has been observed."
+    }
+  ],
+  "notes": "Docs-verified only; reliability remains unknown. Three questions block a usable booking import: whether past-dated slots are accepted, which automations create/confirm triggers and how they are suppressed, and whether class sessions can be created. WPS Bookings for WooCommerce registers no booking post type or custom table, so a booked appointment is represented by WooCommerce order-line metadata, but no representative booking payload has been verified and the per-field mapping remains [NEEDS-VERIFICATION]. sendSmsReminder defaults to true, so generated code must set it false explicitly until notification behavior is proven safe."
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/bookings/entities/service-add-on.json

@@ -0,0 +1,130 @@
+{
+  "schemaVersion": 1,
+  "domain": "bookings",
+  "entity": "service-add-on",
+  "displayName": "Bookings Service Add-On",
+  "capability": "commerce.bookable-service-add-ons",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Bookings Add-On",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "bookingAdditionalServiceTerm",
+      "sourcePlugin": "mwb-bookings-for-woocommerce",
+      "routes": [
+        "/wp/v2/mwb_booking_service",
+        "/wp/v2/mwb_booking_cost"
+      ],
+      "confidence": "low"
+    }
+  ],
+  "dependsOn": ["bookings/service", "tax/tax-group"],
+  "preferredWrite": {
+    "surface": "Add-Ons",
+    "endpoint": "POST /addons/v1/add-ons",
+    "writerId": null,
+    "verification": "docs",
+    "importSafe": true,
+    "bulk": true,
+    "decision": "importSafe is true: an add-on is a catalog object with no customer-facing side effect documented anywhere on the Add On object, Create Add On, or Bulk Create Add Ons pages (read 2026-08-16) - no notification field, no recipient, no delivery prose. It is also invisible to customers until it is placed in an add-on group on a service, which is a second, deliberate call. Note this is the WEAKER of the two importSafe claims in this domain; it rests on absence of documented notification, never on a live probe."
+  },
+  "reliability": {
+    "status": "unknown",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "duration-or-quantity-is-a-required-one-of",
+      "severity": "blocker",
+      "summary": "Create Add On declares durationInMinutes and maxQuantity as a required ONE-OF: every add-on is EITHER duration-based (durationInMinutes 1..1440, i.e. max 24 hours) OR quantity-based (maxQuantity 1..9999), never both and never neither. A source extra that is conceptually both ('add 30 minutes, up to 3 times') cannot be expressed as one add-on and must be split or ledgered. The two kinds also behave differently at booking time: for duration-based add-ons quantity is not applicable - passing quantity 1 is accepted but silently cleared, and any other value returns INVALID_ARGUMENT with the message 'Invalid AddOn details: either duration or quantity must be set correctly'."
+    },
+    {
+      "code": "add-on-is-invisible-until-grouped",
+      "severity": "blocker",
+      "summary": "Creating an add-on is only half the import. About Add-On Groups states plainly: 'Add-ons for Bookings services must be included in a group before customers can book them.' The group is the thing that binds an add-on to a service and it lives on a DIFFERENT surface (Services V2: Create Add On Group / Set Add Ons For Group / Update Add On Group / List Add On Groups By Service Id), not on the Add-Ons API. An import that stops after POST /addons/v1/add-ons produces orphan add-ons that no customer can ever select and that no site page shows - a silent, look-successful failure mode."
+    },
+    {
+      "code": "group-limits-cap-the-catalog",
+      "severity": "warning",
+      "summary": "About Add-On Groups: a maximum of 3 add-on groups per service and 7 add-ons per group - 'Exceeding these limits results in validation errors'. That is a hard ceiling of 21 selectable add-ons per service, which the Booking object independently corroborates (bookedAddOns maxItems 21). A source product carrying more optional extras than that cannot be recreated in full; count add-ons per source product BEFORE the import and surface the overflow at the approval gate rather than discovering it as a validation error mid-run."
+    },
+    {
+      "code": "group-requires-a-service-id-so-ordering-is-fixed",
+      "severity": "warning",
+      "summary": "'Each add-on group is associated with a single service and requires a service ID when created', while an add-on itself may be reused across groups on different services. The import order is therefore forced and three-phase: services first (bookings/service), then add-ons (which are service-independent and can be deduplicated across the whole source catalog), then one group per service that binds them. This is also why bookings/service records add-on-groups-not-settable-at-create - Create Service explicitly refuses existing add-on groups."
+    },
+    {
+      "code": "add-on-currency-is-explicit-not-inherited",
+      "severity": "warning",
+      "summary": "price is a Money object carrying its OWN currency field (ISO 4217, required format CURRENCY) rather than inheriting the site currency the way pricing-plans/plan.currency does. value is a decimal string with maxScale 2 (gte 0, lte 1000000000000000). [NEEDS-VERIFICATION] what happens when the currency sent differs from the site currency was not established - the docs neither coerce nor reject it in writing. Send the site currency explicitly and check the readback; do not assume inheritance."
+    },
+    {
+      "code": "deleting-an-add-on-silently-edits-every-group",
+      "severity": "warning",
+      "summary": "'Deleting an add-on automatically removes it from all groups where it's included.' Rollback of a partial add-on import is therefore not isolated - deleting one add-on mutates the composition of every service group that referenced it, with no error and no notification. Roll back groups and add-ons together, and re-read the affected services' groups afterwards rather than trusting the local plan."
+    },
+    {
+      "code": "booked-add-ons-are-snapshots-not-references",
+      "severity": "info",
+      "summary": "The Booking object stores bookedAddOns with name, nameTranslated and durationInMinutes captured 'at the time of booking' alongside the id/groupId. Historical bookings therefore carry their own copy of the add-on wording, so importing bookings does NOT require the add-on catalog to be imported first for the names to be right - but bookings/booking still needs real add-on and group GUIDs unless flowControlSettings.skipAddOnValidation is set. Import add-ons before bookings anyway; that keeps the crosswalk honest."
+    }
+  ],
+  "mappingGuidance": [
+    "Dependencies: bookings/service is required because an add-on must be placed in a service's add-on group; tax/tax-group is required when the optional taxGroup GUID is mapped for eCommerce checkout.",
+    "One Wix add-on per distinct source extra, deduplicated across the whole source catalog - add-ons are service-independent objects and the same one may be reused in groups on many services, so never mint one add-on per (product x extra) pair.",
+    "Classify each source extra into the required ONE-OF before writing: an extra that lengthens the appointment becomes durationInMinutes (cap 1440); an extra sold in units becomes maxQuantity (cap 9999). If the source expresses neither, quantity-based with maxQuantity 1 is the closest faithful default - record the choice in the faithfulness ledger.",
+    "name is capped at 100 characters (minLength 1); truncate long source labels and keep the full text in the ledger. There is no description field on an add-on - any source blurb has nowhere native to go.",
+    "price.value is a decimal string with at most 2 decimal places; price.currency must be sent explicitly as the site currency ISO code (see add-on-currency-is-explicit-not-inherited).",
+    "Use Bulk Create Add Ons (POST /addons/v1/bulk/add-ons/create, minItems 1 / maxItems 100) for the catalog pass, then one Create Add On Group per service on Services V2, then Set Add Ons For Group with the crosswalked add-on GUIDs - the order in addOnIds is the customer-facing display order, so preserve the source ordering there.",
+    "taxGroup is an eCommerce tax-group GUID and only applies to Wix eCommerce checkout; leave it unset for imports that are not also provisioning tax groups (the field 'doesn't apply to custom checkout/billing implementations').",
+    "Persist both the add-on GUID and its owning group GUID per source extra in the crosswalk - bookings/booking needs bookedAddOns[].id AND bookedAddOns[].groupId, and the group GUID is not derivable from the add-on."
+  ],
+  "setupRequirements": [
+    "Wix Bookings app installed (appId 13d21c63-b5ec-5912-8397-c3a5ddb27a97) - see the bookings-app-required shared pitfall",
+    "SCOPE.DC-BOOKINGS.MANAGE-BOOKINGS (the permission on Create Add On, Bulk Create Add Ons, and the Services V2 add-on-group methods alike)",
+    "bookings/service imported first - an add-on group cannot be created without a service GUID"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/add-on-object",
+      "note": "object page: id, revision, name, price (Money with its own currency + formattedValue), taxGroup, extendedFields, tags.privateTags/tags; the duration-vs-quantity ONE-OF is on the create/response schema (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/create-add-on",
+      "note": "POST https://www.wixapis.com/addons/v1/add-ons; required param addOn; required ONE-OF durationInMinutes (1..1440) | maxQuantity (1..9999); name minLength 1 maxLength 100; price.value DECIMAL_VALUE maxScale 2; permission SCOPE.DC-BOOKINGS.MANAGE-BOOKINGS; NO notification field of any kind (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/bulk-create-add-ons",
+      "note": "POST https://www.wixapis.com/addons/v1/bulk/add-ons/create; addOns minItems 1, maxItems 100 (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-add-on-groups",
+      "note": "the binding half of this entity, and why it lives on Services V2 not Add-Ons: 'Add-ons for Bookings services must be included in a group before customers can book them'; group requires a service ID; limits 3 groups per service and 7 add-ons per group; deleting an add-on removes it from all groups; addOnIds order is display order (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/booking-object",
+      "note": "consumer side: booking.bookedAddOns[] carries id, groupId, quantity, durationInMinutes, name and nameTranslated 'at the time of booking', maxItems 21 - which independently confirms the 3x7 group ceiling (read 2026-08-16)"
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-source-wordpress/plugins/mwb-bookings-for-woocommerce.json",
+      "note": "the source profile this domain was authored against; it is the authority for the two add-on-shaped product taxonomies (mwb_booking_service, mwb_booking_cost) that sourceAliases points at, and for the fact that their prices and quantity rules sit in REST-invisible term meta"
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-source-wordpress/plugins/mwb-bookings-for-woocommerce.json",
+      "note": "sourceAliases added 2026-08-16 after the live probe: WPS Bookings for WooCommerce DOES expose an add-on-shaped surface - the product taxonomies mwb_booking_service ('Additional Services') and mwb_booking_cost ('Additional Costs'), both registered show_in_rest:true and both serving 200 with X-WP-Total 0 on an anonymized verification environment (the taxonomies exist, no terms created). confidence is 'low' because only the term NAMES are reachable: the plugin stores every price and quantity rule as term meta and never calls register_meta, so the fields this entity actually needs are invisible to REST. See the profile's booking-additional-service / booking-additional-cost entities."
+    }
+  ],
+  "notes": "Authored 2026-08-16 to complete the bookings vertical alongside bookings/service and bookings/booking. Docs-verified only, never exercised live - reliability unknown, verification docs. sourceAliases carries ONE low-confidence entry, added 2026-08-16: WPS Bookings for WooCommerce's two REST-exposed product taxonomies (mwb_booking_service, mwb_booking_cost) are a real, live-verified route claim - both returned 200 with X-WP-Total 0 - but only the term names come back, because the plugin's prices and quantity rules live in unregistered term meta. So the source mapping is proven to EXIST and proven to be INCOMPLETE, which is what 'low' records. The entity is genuinely two surfaces stitched together - Add-Ons for the catalog object and Services V2 for the add-on group that makes it bookable - which is why the docs survey claims both surfaces for it."
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/bookings/entities/service.json

@@ -0,0 +1,180 @@
+{
+  "schemaVersion": 1,
+  "domain": "bookings",
+  "entity": "service",
+  "displayName": "Bookings Service",
+  "capability": "commerce.bookable-services",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Service",
+    "verifiedFqdn": "wix.bookings.services.v2.service",
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "dependsOn": [],
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "bookingProduct",
+      "sourcePlugin": "mwb-bookings-for-woocommerce",
+      "routes": [
+        "/wc/v3/products"
+      ],
+      "confidence": "medium"
+    },
+    {
+      "sourceSystem": "wordpress",
+      "sourceEntity": "event",
+      "sourcePlugin": "the-events-calendar",
+      "routes": [
+        "/tribe/events/v1/events"
+      ],
+      "confidence": "medium"
+    }
+  ],
+  "preferredWrite": {
+    "surface": "Bookings Services V2",
+    "endpoint": "POST /bookings/v2/services",
+    "writerId": "createBookingsService",
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": false
+  },
+  "fallbacks": [
+    {
+      "classification": "unsupported-native-gap",
+      "when": "Attendee/registrant PII import: Bookings has no bulk 'import a past booking' path, mirroring the Events domain's ticket-order-history-not-importable gap. Only the service+session definitions are importable, never historical bookings."
+    }
+  ],
+  "reliability": {
+    "status": "reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "bookings-app-not-installed-by-default",
+      "severity": "blocker",
+      "summary": "Wix Bookings is not present on a fresh headless site, and neither `/bookings/v2/services` nor `/bookings/v2/resources/query` reveal that by erroring — both answer with ordinary 200s/validation errors regardless. Create Service instead fails with a plain 'form Form with id 00000000-0000-0000-0000-000000000000 doesn't exist', which reads like a form problem but is actually the app-install gap. Install with appDefId 13d21c63-b5ec-5912-8397-c3a5ddb27a97 (see rp-execute-setup SKILL.md) before the first Create Service call; this also auto-provisions the default booking form and one default 'Business Owner' staff resource."
+    },
+    {
+      "code": "staff-member-required-and-it-is-a-resource-id",
+      "severity": "blocker",
+      "summary": "For appointment-based services at least one staffMemberIds entry is REQUIRED at create, and the docs are explicit that the values are RESOURCE GUIDs (staffMember.resourceId), not staff-member GUIDs - 'Query staff members with the RESOURCE_DETAILS field set to retrieve resourceId'. A WooCommerce booking product has no provider concept at all, so the import must provision (or reuse) a staff member during setup and record the substitution in the faithfulness ledger; the app install already provisions one default 'Business Owner' resource that can be reused. For classes and courses staffMemberIds is read-only and derived from the recurring sessions, so it must NOT be sent."
+    },
+    {
+      "code": "five-required-create-fields",
+      "severity": "blocker",
+      "summary": "Create Service requires type (APPOINTMENT | CLASS | COURSE), name, onlineBooking, payment, and defaultCapacity - all five, on every call. defaultCapacity must be exactly 1 for APPOINTMENT services; a source per-slot capacity greater than 1 therefore cannot be expressed as an appointment and must either become a CLASS or be ledgered as loss. payment.options must have at least one of inPerson or online true even when rateType is NO_FEE."
+    },
+    {
+      "code": "session-is-a-calendar-v3-event-not-a-bookings-endpoint",
+      "severity": "blocker",
+      "summary": "There is no '/bookings/v2/...' endpoint for a service's date/time occurrence. The one-time or recurring session is an ordinary Calendar V3 event (POST /calendar/v3/events) on `service.schedule.id` (present on the Create Service response). `event.type` must equal the service's `type` or the create 400s 'type must match the service type'; a CLASS/COURSE event additionally requires `resources: [{ id, permissionRole: 'WRITER' }]` naming a real Bookings resource (POST /bookings/v2/resources/query) or it 400s 'resources must have at least 1 resource for class events'. `start.localDate`/`end.localDate` are LOCAL date-time strings with no offset/zone suffix, paired with a separate `timeZone` — the same trap documented for Wix Events."
+    },
+    {
+      "code": "payment-options-has-no-default",
+      "severity": "warning",
+      "summary": "Omitting `payment.options` 400s 'It is mandatory to specify either payment.options.online or payment.options.inPerson as true', even for a NO_FEE service with no money changing hands. Always set at least one of `online`/`inPerson`. (Live-verified error string 2026-08-12; the docs state the same requirement.)"
+    },
+    {
+      "code": "default-capacity-required-by-type",
+      "severity": "warning",
+      "summary": "`defaultCapacity` must be exactly 1 for `type: APPOINTMENT` and greater than 1 for `CLASS`/`COURSE`. The source rarely carries a capacity figure (The Events Calendar has none) — pick and document a deterministic default rather than guessing per record."
+    },
+    {
+      "code": "no-category-means-invisible",
+      "severity": "warning",
+      "summary": "Create Service: 'Without an assigned category, the service isn't visible on the live site.' Services are not auto-categorized, so the import must create/crosswalk a Categories V2 category and set category.id, or every imported service silently fails to appear. Separately, service.hidden controls whether the service shows in Wix Bookings pages and widgets - set it deliberately rather than letting the default decide."
+    },
+    {
+      "code": "no-organizer-or-category-field",
+      "severity": "warning",
+      "summary": "Bookings Services have no organizer/contact field and use their own Categories V2 catalog, disconnected from any other domain's categories (e.g. Wix Events categories). A source record's organizer name/email and taxonomy have nowhere native to land and are dropped unless explicitly folded into `description` or a real Bookings category is created and linked."
+    },
+    {
+      "code": "session-durations-rules-differ-by-type",
+      "severity": "warning",
+      "summary": "schedule.availabilityConstraints.sessionDurations is required for appointment-based services and must NOT be specified for classes or courses. For appointment services with varied pricing by session length the field is still mandatory but its values are IGNORED - real durations come from Service Options and Variants. Duration values are minutes, min 1 and max 44639 (30 days minus a minute), maxItems 50."
+    },
+    {
+      "code": "pricing-plan-and-manual-approval-conflict",
+      "severity": "warning",
+      "summary": "payment.options.pricingPlan cannot be combined with onlineBooking.requireManualApproval, and online payment requires rateType FIXED or VARIED. A source service that is both 'admin must confirm' and 'payable by membership' cannot be recreated as-is; pick one and ledger the other."
+    },
+    {
+      "code": "location-country-is-iso-alpha-2",
+      "severity": "warning",
+      "summary": "`locations[].custom.address.country` validates as an ISO-3166-1 alpha-2 code ('IL'), not a free-text country name ('Israel'). `formattedAddress` and `city` are free text and accept the source value directly; convert or omit `country`."
+    },
+    {
+      "code": "locations-immutable-on-bulk-create",
+      "severity": "warning",
+      "summary": "The Bulk Create Services parameter table marks locations as immutable (maxItems 500). Set Service Locations exists as a dedicated method, so plan location assignment as part of the create payload or through that method - not as a later Update Service field patch."
+    },
+    {
+      "code": "add-on-groups-not-settable-at-create",
+      "severity": "info",
+      "summary": "Create Service explicitly says not to specify existing add-on groups; use Create Add On Group / Set Add Ons For Group after the service exists. Add-on import is therefore a second pass (bookings/service-add-on), ordered after the service."
+    },
+    {
+      "code": "hidden-does-not-hide-from-dashboard-services-list",
+      "severity": "info",
+      "summary": "`hidden: true` only affects the public storefront/booking page — a migrated service still shows normally under the dashboard's Bookings > Services list, live-confirmed by the site owner. Do not treat 'I don't see my migrated classes' as evidence `hidden` needs to change; ask which dashboard view is being checked first. A genuinely separate dashboard view lists actual customer bookings/reservations (appointments against a session), not services or sessions themselves — that view is correctly empty when the source recorded zero registrants (e.g. The Events Calendar exposes no RSVP/attendee data on its public REST routes), since this migration only imports service+session definitions, never historical bookings (see the unsupported-native-gap fallback above)."
+    }
+  ],
+  "mappingGuidance": [
+    "One Wix service per source bookable record. For the WooCommerce mwb_booking product type the natural target is type APPOINTMENT (the plugin books a person-less time window against one product); a source product whose per-slot capacity is greater than 1 (mwb_mbfw_max_bookings / mwb_mbfw_maximum_booking_per_unit) is a CLASS instead, because APPOINTMENT forces defaultCapacity = 1.",
+    "Small-group workshops/classes with per-attendee capacity and 'booking required' language are a Bookings fit (type CLASS); large public ticketed happenings stay Wix Events — see rp-source-wordpress's the-events-calendar profile for the classification heuristic.",
+    "Create with `hidden: true` and `onlineBooking.enabled: false` for an initial migration pass, mirroring Wix Events' `draft: true` — this avoids turning on real online booking/payment collection before a human reviews pricing and policy.",
+    "name and description come from the product title and description; media.mainMedia takes the product image after the media import has uploaded it (Media Manager GUIDs, not source URLs).",
+    "payment.rateType FIXED with payment.fixed.price = the product price (the plugin writes its unit cost to both mwb_mbfw_booking_unit_cost and _price). payment.options.inPerson = true is the safe default, because the source checkout (WooCommerce gateways) does not migrate.",
+    "A blank/empty source cost defaults to NO_FEE (free) — record this as an explicit mapping note per affected record, never invent a price.",
+    "onlineBooking.enabled = true, and onlineBooking.requireManualApproval = (source mwb_mbfw_admin_confirmation === 'yes') - that flag is the plugin's 'Booking confirmation required by admin' checkbox.",
+    "schedule.availabilityConstraints.sessionDurations: derive minutes from the source cadence pair mwb_mbfw_booking_unit x mwb_mbfw_booking_count. A day-unit source booking has no minute duration of its own; use the product's daily window (mwb_mbfw_daily_calendar_start_time / mwb_mbfw_daily_calendar_end_time) where present and ledger the assumption otherwise.",
+    "locations: the plugin stores a free-text venue in mwb_mbfw_booking_location, which maps to a CUSTOM location (the documented default type). Fold a per-event source venue into `locations[0]` as a CUSTOM address (formattedAddress + city + ISO alpha-2 country code) rather than BUSINESS. Business locations must exist first if the source venue should become a real location rather than free text.",
+    "category.id: crosswalk the source product category (WooCommerce product_cat) to a Categories V2 category. Without it the service is invisible on the live site. [NEEDS-VERIFICATION] the mwb-bookings-for-woocommerce profile records that the plugin assigns a 'booking' product_cat term only when the PRO edition is active with its category setting enabled, and that was never observed live - so do not assume a discriminating source category exists. Until bookings/service-category is authored (the categories-v2 gap in the docs survey), setup creates a single catch-all category and the source's real category structure is flattened into it; ledger that loss.",
+    "Import services BEFORE bookings and before add-ons: a booking needs bookedEntity plus a resolvable service, and add-on groups can only be attached to a service that already exists.",
+    "Bulk Create Services accepts up to 100 services per call and is the documented path for large catalogs, but the verified-live writer (`createBookingsService`) creates one at a time - persist the returned service.id (and schedule.id, which is the handle into Business Management > Calendar) against the source record id in the crosswalk either way."
+  ],
+  "setupRequirements": [
+    "Wix Bookings app installed (appDefId 13d21c63-b5ec-5912-8397-c3a5ddb27a97)",
+    "At least one staff member provisioned, with its resourceId known - required for every APPOINTMENT service",
+    "At least one Categories V2 category, otherwise imported services are invisible on the live site",
+    "Business locations configured if source venues should become real locations rather than CUSTOM free text"
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/service-object",
+      "note": "object page: type enum APPOINTMENT|CLASS|COURSE, hidden, category (services aren't auto-assigned; without one the service is invisible), defaultCapacity, form, onlineBooking, locations, policy, schedule.id (links into Business Management > Calendar), staffMemberIds are resource IDs and are read-only for classes/courses (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/create-service",
+      "note": "POST https://www.wixapis.com/_api/bookings/v2/services; required type + name + onlineBooking + payment + defaultCapacity; defaultCapacity must be 1 for appointments; rateType FIXED|VARIED|CUSTOM|NO_FEE and at least one of payment.options.inPerson/online; pricingPlan option incompatible with requireManualApproval; sessionDurations required for appointments and forbidden for classes/courses; staffMemberIds are resource GUIDs; don't specify existing add-on groups (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services",
+      "note": "POST https://www.wixapis.com/bookings/v2/bulk/services/create; services maxItems 100; locations marked immutable, maxItems 500; sessionDurations minutes 1..44639, maxItems 50 (read 2026-08-16)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/bookings/wix-forms-integration"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/create-event"
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-source-wordpress/plugins/mwb-bookings-for-woocommerce.json",
+      "note": "source shape: mwb_booking product type + unregistered mwb_mbfw_*/wps_mbfw_* product meta (cadence, capacity, venue, admin confirmation, daily window)"
+    },
+    {
+      "type": "live-verification",
+      "path": "anonymized-live-verification"
+    }
+  ],
+  "notes": "Two independent authorings merged 2026-08-16. The Events Calendar path (WordPress events -> CLASS services + Calendar V3 sessions) was exercised live on an anonymized verification environment 2026-08-12, 8/8 - that is where reliability:reliable and the verified error strings come from. The WooCommerce mwb-bookings-for-woocommerce path (WPS Bookings for WooCommerce 3.12.0, authored 2026-08-16) is docs-verified only and has never been exercised live; treat its cadence/capacity/venue meta mapping as unproven. Service creation itself has no documented customer-facing notification (the only 'notif' hits on the Create Service and Service object pages are waitlist reservationTimeInMinutes prose), which is why importSafe is true here while bookings/booking is false."
+}