@wix/agent-skills 1.18.2 → 1.19.0

package/skills/wix-manage/references/bookings/booking-service-policy-setup.md

@@ -1,6 +1,6 @@
 ---
 name: "Booking Service Policy Setup"
-description: Sets up booking policies, cancellation rules, and waitlist configuration using the Services API policy fields. Covers bookingPolicy, cancellationPolicy, and waitlist settings.
+description: Sets up booking policies, cancellation rules, and waitlist configuration using the Booking Policies API (query, then PATCH the bookingPolicy entity with its revision). Covers cancellationPolicy, reschedulePolicy, booking-notice limits, waitlistPolicy, and participants limits — e.g. "customers can cancel up to 24 hours before".
 ---
 
 # Technical Step-by-Step Instructions: Configuring Wix Bookings Service Policies (Real-World, API-First)
@@ -20,72 +20,98 @@ Wix Bookings policy configuration allows businesses to set rules for:
 - **Waitlist policies**: When waitlists are enabled, capacity handling
 - **Group booking policies**: Maximum participants per booking
 
-Policies can be configured at two levels:
+Policies are **standalone entities** managed by the Booking Policies API (`/bookings/v1/booking-policies`), not fields nested on the service:
 
-- **Site-wide (business) policies**: Default rules that apply to all services
-- **Service-specific policies**: Override rules for individual services
+- Installing Wix Bookings creates a **"Default policy"** (`default: true`) that every new service references.
+- Each service points at exactly one policy via its `bookingPolicy` field; many services can share a policy.
+- To change rules site-wide, update the default policy. To give one service different rules, create a separate policy and reference it from that service.
 
 ### IMPORTANT NOTES
 
-- Services inherit from site-wide booking policies by default
-- Service policies only override fields you explicitly specify - unspecified fields keep site defaults
-- Policy options available may vary based on service type (APPOINTMENT, CLASS, COURSE)
-- All policy configurations support the same core features across service types
+- A default policy exists on any site with Wix Bookings installed — **even before any service exists**. "Set a cancellation window" is always actionable by updating the default policy.
+- Policy updates are PATCH-style: send only the sub-policies you want to change, plus the current `revision` (fetched via query/get) inside the `bookingPolicy` object.
+- Policy options are the same across service types (APPOINTMENT, CLASS, COURSE).
 
 ---
 
 ## Steps
 
-### 1. Configure Site-Wide Business Policy (Optional)
+### 1. Find the Policy to Change
 
-Set default policies that will apply to all services unless overridden. Use the Business Policy API to configure booking deadlines, cancellation rules, waitlist settings, and group booking limits.
+Query existing policies (`POST https://www.wixapis.com/bookings/v1/booking-policies/query`):
 
-### 2. Create or Update Service with Policy Overrides
+```json
+{ "query": { "cursorPaging": { "limit": 100 } } }
+```
 
-When creating or updating a service, specify policy fields that should differ from business defaults. Only include the policy fields you want to override - unspecified fields will inherit from business defaults.
+For a site-wide change, pick the policy with `"default": true`. For a specific service, read the service first — its embedded `bookingPolicy.id` names the policy it uses. Save the policy's `id` and `revision`.
 
-### 3. Configure Course-Specific Policies
+### 2. Update the Policy
 
-Courses may have additional policy options such as `bookUntilXMinutesAfterStart` which allows customers to join courses even after they've started.
+`PATCH https://www.wixapis.com/bookings/v1/booking-policies/<POLICY_ID>` with the current `revision` inside the `bookingPolicy` object and only the sub-policies you're changing. Example — cancellations allowed up to 24 hours before the session:
+
+```json
+{
+  "bookingPolicy": {
+    "id": "<POLICY_ID>",
+    "revision": "<CURRENT_REVISION>",
+    "cancellationPolicy": {
+      "enabled": true,
+      "limitLatestCancellation": true,
+      "latestCancellationInMinutes": 1440
+    }
+  }
+}
+```
+
+**Field map (business rule → policy field):**
+
+| Business rule | Sub-policy fields |
+|---|---|
+| Cancellation deadline | `cancellationPolicy.{enabled, limitLatestCancellation, latestCancellationInMinutes}` |
+| Reschedule deadline | `reschedulePolicy.{enabled, limitLatestReschedule, latestRescheduleInMinutes}` |
+| How far ahead customers can book | `limitEarlyBookingPolicy.{enabled, earliestBookingInMinutes}` |
+| Booking notice / last-minute cutoff | `limitLateBookingPolicy.{enabled, latestBookingInMinutes}` |
+| Booking after session start (courses/classes) | `bookAfterStartPolicy.enabled` |
+| Waitlist | `waitlistPolicy.{enabled, capacity, reservationTimeInMinutes}` |
+| Participants per booking | `participantsPolicy.{enabled, maxParticipantsPerBooking}` |
+
+### 3. Per-Service Policies (Optional)
+
+To give one service different rules, create a new policy (`POST https://www.wixapis.com/bookings/v1/booking-policies`) and point the service at it by updating the service's `bookingPolicy` reference (see [Update Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/update-service)).
 
 ### 4. Verify Policy Application
 
-Query the service to confirm policies are applied correctly. The service should show explicitly set policy fields with your specified values and unspecified fields inheriting from business defaults.
+Read the service (`GET /bookings/v2/services/<SERVICE_ID>`) — the response embeds the full resolved `bookingPolicy`, so you can confirm the effective rules exactly as customers will experience them.
 
 ### IMPORTANT NOTES
 
-- **Policy inheritance**: Only specify fields you want to override - leave others undefined to inherit business defaults
-- **Partial updates**: When updating service policies, only include fields you want to change
-- **Capacity requirements**: Waitlist policies require service capacity settings to be configured
-- **Group booking considerations**: `maxParticipantsPerBooking` works with all service types
-- **Time calculations**: Policy deadlines are calculated from booking start time in business timezone
-- **Course flexibility**: Course services support additional policy options like `bookUntilXMinutesAfterStart`
+- **Revision required**: Every policy update needs the current `revision` inside `bookingPolicy`; fetch it first, or the PATCH fails.
+- **Partial updates**: Send only the sub-policies you're changing; the rest keep their values.
+- **Enabled flags matter**: Each sub-policy has an `enabled` (and often a `limit*`) boolean — setting only the minutes value without enabling the limit has no effect.
+- **Time calculations**: Policy deadlines are calculated from the booking's start time, in minutes (24 hours = 1440).
 
 ### Troubleshooting Common Issues
 
 **Policies not applying:**
 
-- Verify you're setting policies on the service object, not as separate policy entities
-- Check that policy fields are properly nested under `service.policy`
-- Ensure you're updating the correct service ID
+- Policies are separate entities — verify you PATCHed `/bookings/v1/booking-policies/<id>`, not fields on the service object (there is no `service.policy` field)
+- Confirm the service actually references the policy you changed (`service.bookingPolicy.id`)
+- Check the `revision` was current — a stale revision fails the update
 
 **Waitlist not working:**
 
-- Confirm service has `maxParticipants` capacity set
-- Verify `waitingListPolicy.enabled` is `true`
-- Check that `waitingListPolicy.capacity` is set if you want limited waitlist size
+- Verify `waitlistPolicy.enabled` is `true` and `waitlistPolicy.capacity` is set
+- Confirm the service has capacity configured (`defaultCapacity` for CLASS/COURSE)
 
 **Cancellation policies not enforced:**
 
-- Ensure `cancelRescheduleUpToInMinutes` is set to appropriate value
-- Verify `cancelationAllowed` is `true` if cancellations should be permitted
-- Check that payment and booking flow supports the configured policy
+- Set all three fields together: `cancellationPolicy.enabled: true`, `limitLatestCancellation: true`, and `latestCancellationInMinutes` — the minutes value alone has no effect without the booleans
 
 **Group booking limits not working:**
 
-- Confirm `maxParticipantsPerBooking` is set to desired limit
-- Verify service type supports group bookings (all types do)
-- Check that booking UI respects the participant limit
+- Confirm `participantsPolicy.enabled` is `true` and `participantsPolicy.maxParticipantsPerBooking` is set
+- Check that the booking UI respects the participant limit
 
 ## API Documentation References
 

package/skills/wix-manage/references/bookings/bookings-staff-setup.md

@@ -68,7 +68,8 @@ The most common mistake is confusing which ID to use in which API call, leading
 
 * **Two-Step Requirement**: Custom working hours requires both `assignWorkingHoursSchedule` AND creating `WORKING_HOURS` events. Only doing the first step results in staff with no actual working hours.
 * **Foundation Dependencies**: Staff operations require Wix Bookings app installation and proper business schedule configuration. "Business schedule not found" errors indicate missing foundation setup.
-* **Event Field Requirements**: When creating `WORKING_HOURS` events, several fields that appear optional in documentation are actually required: `externalScheduleId`, `adjustedStart`, `adjustedEnd`, `resources` array, and `appId`.
+* **Bulk Request Envelope**: `bulkCreateEvents` requires each event to be wrapped in an `event` object — `{"events": [{"event": {...}}], "returnEntity": true}`. Sending a flat `{"events": [{...}]}` fails with 400 `event must not be empty`. Pass `returnEntity: true` to get the created events back; otherwise the response contains only `itemMetadata`.
+* **Minimal Event Fields**: A `WORKING_HOURS` event needs only `type`, `scheduleId`, `start.localDate`, `end.localDate`, and (for recurring hours) `recurrenceRule`. The server derives `externalScheduleId` (set to the staff member's resource ID automatically), `adjustedStart`/`adjustedEnd`, and `appId`; `resources` may stay empty on a working-hours schedule.
 * **Revision Numbers**: Event updates ALWAYS require the current revision number. Fetch current event details before any update operation.
 * **Time Format Precision**: All date/time fields must use precise ISO 8601 format (`YYYY-MM-DDTHH:mm:ss`) without timezone indicators.
 * **Separate Events for Each Day**: Each working day requires a separate event with single-day recurrence rules. You cannot specify multiple days in one event's `recurrenceRule.days` array.
@@ -113,9 +114,7 @@ Before creating staff members, ensure the foundation is properly configured:
 
 **Install Wix Bookings App** (if needed): Use the App Installer API with Wix Bookings app ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`.
 
-**Configure Business Schedule**: Set up site properties with business operating hours using the Site Properties API.
-
-**Create Calendar Schedule and Working Hours**: Create a calendar schedule for Wix Bookings integration and populate it with business `WORKING_HOURS` events.
+**Configure Business Schedule**: Default business hours live as `WORKING_HOURS` calendar events on the business schedule — set them up per the [Configure Default Business Hours](../calendar/configure-default-business-hours.md) recipe. Do **not** use the Site Properties API for this: its business-schedule fields are separate general site info and do not drive Bookings availability.
 
 ### 2. Verify Current Business Hours (CRITICAL)
 
@@ -156,11 +155,10 @@ Create staff members using the Staff API (`POST https://www.wixapis.com/bookings
 
 **⚠️ INHERITANCE MOMENT**: The moment this API call completes, the staff member inherits the current business hours. There's no "undo" for this inheritance.
 
-**Save Critical IDs from Response**:
-- `staffMember.id` for updates and schedule assignment
-- `staffMember.resourceId` for services and event resources
-- `staffMember.resource.eventsSchedule.id` for working hours events
-- `staffMember.resource.usesDefaultWorkingHours` (should be `true` initially)
+**Save Critical IDs**:
+- `staffMember.id` (in the create response) for updates and schedule assignment
+- `staffMember.resourceId` (in the create response) for services and event resources
+- `staffMember.resource.eventsSchedule.id` for working hours events — **NOT in the create response**. The create response contains only id/name/resourceId; fetch the staff member again with `?fields=RESOURCE_DETAILS` to get `resource.eventsSchedule.id` (and `resource.usesDefaultWorkingHours`, initially `true`). Reading `resource.eventsSchedule.id` off the create response yields `undefined` and downstream `scheduleId must not be empty` errors.
 
 ### 5. Set Up Custom Working Hours (Two-Step Process)
 
@@ -168,21 +166,44 @@ Create staff members using the Staff API (`POST https://www.wixapis.com/bookings
 
 **Step 5A: Assign Custom Working Hours Schedule**
 
-Get staff member details (`GET https://www.wixapis.com/bookings/v1/staff-members/<STAFF_MEMBER_ID>?fields=RESOURCE_DETAILS`) to extract the events schedule ID. Call `assignWorkingHoursSchedule` (`POST https://www.wixapis.com/bookings/v1/staff-members/<STAFF_MEMBER_ID>/assign-working-hours-schedule`) using the staff member ID and their events schedule ID. This detaches the staff member from business default hours.
+Get staff member details (`GET https://www.wixapis.com/bookings/v1/staff-members/<STAFF_MEMBER_ID>?fields=RESOURCE_DETAILS`) to extract the events schedule ID. Then call `assignWorkingHoursSchedule` (`POST https://www.wixapis.com/bookings/v1/staff-members/<STAFF_MEMBER_ID>/assign-working-hours-schedule`):
+
+```json
+{ "scheduleId": "<EVENTS_SCHEDULE_ID>" }
+```
+
+The request field is `scheduleId` (other names, e.g. `eventsScheduleId`, fail with 400 `scheduleId must not be empty`). This detaches the staff member from business default hours.
 
 Verify the response shows `"usesDefaultWorkingHours": false`.
 
+> **On failure, resume — don't restart.** If this call (or a later step) fails, the staff member from Step 4 already exists. Fix the failing call and continue with the same staff member ID; re-running the whole flow creates a duplicate staff member.
+
 **Step 5B: Create WORKING_HOURS Events**
 
-Use the Events API (`POST https://www.wixapis.com/calendar/v3/bulk/events/create`) to create working hours events for each working day. Each event must include:
-- `scheduleId`: Staff member's events schedule ID
-- `externalScheduleId`: Staff member's resource ID
-- `type`: `"WORKING_HOURS"`
-- `resources` array: Staff member's resource ID
-- `appId`: Wix Bookings app ID
-- Proper recurrence rules with single-day specification
+Use the Events API (`POST https://www.wixapis.com/calendar/v3/bulk/events/create`) to create one recurring event per working day. Note the request envelope: each event is wrapped in an `event` object.
 
-Create separate events for each day of the week the staff member works.
+```json
+{
+  "events": [
+    {
+      "event": {
+        "type": "WORKING_HOURS",
+        "scheduleId": "<STAFF_EVENTS_SCHEDULE_ID>",
+        "start": { "localDate": "2026-09-07T09:00:00" },
+        "end": { "localDate": "2026-09-07T15:00:00" },
+        "recurrenceRule": { "frequency": "WEEKLY", "interval": 1, "days": ["MONDAY"] }
+      }
+    }
+  ],
+  "returnEntity": true
+}
+```
+
+- `scheduleId` is the staff member's **events schedule ID** (`resource.eventsSchedule.id`).
+- `externalScheduleId`, `adjustedStart`/`adjustedEnd`, and `appId` are derived by the server — you do not need to send them (`externalScheduleId` comes back set to the staff member's resource ID).
+- `recurrenceRule.frequency` must be `WEEKLY` (the only supported value); `interval` is 1–4.
+- `recurrenceRule.days` takes exactly one **full uppercase** day name from `MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY` — abbreviations like `MON` fail validation. One day per event, so create a separate event for each working day.
+- `start`/`end` must be today or in the future for recurring events.
 
 ### 6. Verify Setup
 
@@ -193,10 +214,9 @@ Query the staff member to confirm:
 
 ### IMPORTANT NOTES
 
-* **ID Relationship Critical**: Use staff member ID for assignment, events schedule ID for event `scheduleId`, and resource ID for `externalScheduleId` and `resources` array
+* **ID Relationship Critical**: Use the staff member ID for assignment and the events schedule ID for event `scheduleId`; the resource ID appears in server-derived fields (`externalScheduleId`) and in `resources` arrays when attaching this staff member to CLASS/COURSE session events
 * **Foundation First**: Complete foundation setup before staff operations to avoid "Business schedule not found" errors
 * **Complete Two-Step Process**: Both schedule assignment AND event creation are mandatory for custom working hours
-* **Event Field Requirements**: Include all required fields even if they appear optional in basic documentation
 * **Revision Management**: Always fetch current revision numbers before updating events
 * **Date Format Strict**: Use precise ISO 8601 format without timezone indicators
 * **Inheritance is Permanent**: Once inherited, business hours changes don't affect existing staff
@@ -218,7 +238,10 @@ Completed assignment but missing event creation. Create `WORKING_HOURS` events u
 - **Solution**: Standardize by configuring custom hours for all staff, or recreate staff after fixing business hours
 
 **"Invalid scheduleId" or "Resource not found" Errors**:
-Using wrong ID type in API calls. Verify you're using events schedule ID for `scheduleId`, resource ID for `externalScheduleId` and `resources` array, and staff member ID for updates.
+Using wrong ID type in API calls. Verify you're using the events schedule ID for `scheduleId` and the staff member ID for updates.
+
+**400 "event must not be empty" on bulkCreateEvents**:
+The request body is missing the per-event wrapper. Each entry in `events` must be `{"event": {...}}`, not the event fields directly.
 
 **Event Update Fails with Revision Error**:
 Get current event details first and include the revision number in update requests.
@@ -227,7 +250,7 @@ Get current event details first and include the revision number in update reques
 Use current or future dates for recurring event start dates.
 
 **Events Not Linked to Staff Member**:
-Ensure `resources` array contains staff member's resource ID and `externalScheduleId` is properly set.
+Verify the event was created on the staff member's own events schedule (`resource.eventsSchedule.id`) — the schedule is what links working-hours events to the staff member. The returned event's `externalScheduleId` should equal the staff member's resource ID (server-derived).
 
 ### Working with Existing Staff
 

package/skills/wix-manage/references/bookings/multi-resource-service-creation.md

@@ -18,8 +18,9 @@ Below are the recommended steps to successfully create Wix Bookings services tha
 Before creating multi-resource services, ensure the following requirements are met:
 
 1. **Wix Bookings** - Core app must be installed and configured
-2. **Premium Plan** - Advanced resource management typically requires premium features
-3. **Business Location** - At least one business location must be configured
+2. **Business Location** - At least one business location must be configured
+
+> Resource type, resource, and resource-bound service creation succeed via the API without any premium-related error. If a plan-gating error does occur, it surfaces explicitly (e.g. a 403) — don't preemptively block on plan checks.
 
 ### App Installation Process
 
@@ -112,6 +113,12 @@ Before creating anything, plan your resource type structure. Each type should re
 
 Create resource types using `createResourceType` API (`POST https://www.wixapis.com/bookings/v2/resources/resource-types`) ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resource-types-v2/create-resource-type)):
 
+```json
+{ "resourceType": { "name": "Treatment Room" } }
+```
+
+The response returns `resourceType.id` — save it for resource creation and the service's `serviceResources`.
+
 **Key Requirements:**
 - `name` must be unique across the site
 - Keep `name` descriptive but concise (appears in booking interface)
@@ -121,9 +128,23 @@ Create resource types using `createResourceType` API (`POST https://www.wixapis.
 
 ### 3. Create Individual Resources
 
-For each resource type, create the individual resource instances using `createResource` API (`POST https://www.wixapis.com/bookings/v2/resources`) ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/create-resource)):
+Create the resource instances of each type. For more than one (the usual case — e.g. Room A and Room B), use `bulkCreateResources` (`POST https://www.wixapis.com/bookings/v2/bulk/resources/create`) ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/bulk-create-resources)); for a single one, `createResource` (`POST https://www.wixapis.com/bookings/v2/resources`) takes `{ "resource": { "name": ..., "typeId": ... } }`.
+
+```json
+{
+  "resources": [
+    { "name": "Room A", "typeId": "<RESOURCE_TYPE_ID>" },
+    { "name": "Room B", "typeId": "<RESOURCE_TYPE_ID>" }
+  ],
+  "returnEntity": true
+}
+```
+
+Read each created resource's ID from `results[i].item.id` (with `returnEntity: true`) or `results[i].itemMetadata.id` (without it). **The resource is directly under `item` — there is no `item.resource.id`** (reading it throws `Cannot read properties of undefined`). Match items to your request by `itemMetadata.originalIndex`, and check `bulkActionMetadata.totalFailures` before proceeding.
 
-**Gap Not in Docs**: The docs don't clearly explain that `availableInAllLocations: true` is the simplest approach and that specific location configuration is complex and often unnecessary.
+**⚠️ Payload shape**: the type reference is the flat `typeId` field (same on single and bulk). Sending a nested object (`"type": {"id": ...}`) fails with 400 `Unexpected value for StringValue`. A resource without `typeId` is created but is not bookable.
+
+If you omit `locationOptions`, the resource defaults to `availableInAllLocations: true` — the simplest and usually correct configuration; specific location setup is complex and often unnecessary.
 
 **Advanced Configuration (Gap):**
 - Custom working hours override business location hours (this behavior isn't clearly documented)
@@ -133,17 +154,42 @@ For each resource type, create the individual resource instances using `createRe
 
 ### 4. Create Multi-Resource Service (Optional Connection)
 
-Create the service that optionally connects to multiple resource types using `bulkCreateServices` API ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services)):
+Create the service that optionally connects to multiple resource types using `bulkCreateServices` API (`POST https://www.wixapis.com/bookings/v2/bulk/services/create`) ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services)). Note the endpoint path is `/bulk/services/create` (not `/services/bulk/create`, which 404s).
+
+**Pick the service type, and mind the resource-specific required fields:**
+
+- A **1-on-1, time-slot** service (e.g. a massage, a room rental by the hour) is an `APPOINTMENT`. When such a service is driven by a **resource instead of a staff member**, `primaryResourceType` (a flat resource-type GUID) is **required** — omitting it fails with 400 `primary_resource_type is required for appointment services without staff members`. APPOINTMENT also needs `schedule.availabilityConstraints.sessionDurations`.
+- A **group** service (fixed capacity per session) is a `CLASS` (drop-in) or `COURSE` (whole series); these use `defaultCapacity` and do not require `primaryResourceType`.
+
+Appointment example (one room per booking, no staff):
 
-**Service Resource Configuration:**
 ```json
-"serviceResources": [
-  {"resourceType": {"id": "room-type-id"}},
-  {"resourceType": {"id": "equipment-type-id"}},
-  {"resourceType": {"id": "instructor-type-id"}}
-]
+{
+  "services": [{
+    "name": "Massage",
+    "type": "APPOINTMENT",
+    "onlineBooking": { "enabled": true },
+    "serviceResources": [
+      { "resourceType": { "id": "<ROOM_TYPE_ID>" } }
+    ],
+    "primaryResourceType": "<ROOM_TYPE_ID>",
+    "schedule": { "availabilityConstraints": { "sessionDurations": [60] } },
+    "payment": {
+      "rateType": "FIXED",
+      "options": { "online": true, "inPerson": false },
+      "fixed": { "price": { "value": "80" } }
+    }
+  }],
+  "returnEntity": true
+}
 ```
 
+For a group service, use `"type": "CLASS"` with `"defaultCapacity": <n>` instead of `primaryResourceType`/`sessionDurations`. Both types take `payment.options` (at least one of `online`/`inPerson` true) — required even for the resource-bound case.
+
+Save the service ID from the response: `results[0].item.id` (with `returnEntity: true`), or `results[0].itemMetadata.id` (without it). **There is no `results[0].item.service.id`** — reading that path throws `Cannot read properties of undefined`.
+
+**⚠️ Verify from the response, not from assumptions**: without `returnEntity: true` the bulk response contains only `results[0].itemMetadata` (id + success flag) — there is no `item`. With the flag, the created service is at `results[0].item` (e.g. `item.id`, `item.serviceResources`). Check `bulkActionMetadata.totalFailures` and each `itemMetadata.success` before reporting the service as created.
+
 **Key Principle**: This creates a **loose connection** where the service requests resource allocation during booking, but resources remain independent entities with their own lifecycle and management.
 
 **Pricing Strategy**: Multi-resource services typically command premium pricing due to coordination complexity.
@@ -171,6 +217,18 @@ The docs don't explain how multi-resource allocation actually works during booki
 - Check that `typeId` exactly matches the resource type `id`
 - Ensure you're not using resource type `name` when `id` is required
 
+**400 "Unexpected value for StringValue" on createResource or on service `primaryResourceType`:**
+- A resource-type reference was sent as a nested object where a flat GUID string is expected. `createResource` uses `"typeId": "<guid>"`; the service field is `"primaryResourceType": "<guid>"` (both flat, not `{"id": ...}`). Note this differs from `serviceResources[].resourceType.id`, which *is* nested.
+
+**400 "primary_resource_type is required for appointment services without staff members":**
+- An `APPOINTMENT` service bound to a resource (no `staffMemberIds`) needs `primaryResourceType` set to the driving resource-type GUID. Either add it, or model the service as a `CLASS`/`COURSE` if a group service fits.
+
+**404 on bulk creation:**
+- The path segments are `bulk/<entity>/create`: `POST /bookings/v2/bulk/services/create`, `POST /bookings/v2/bulk/resources/create`. `/bookings/v2/services/bulk/create` (and the resources equivalent) do not exist.
+
+**`Cannot read properties of undefined` after a bulk create (resources or services):**
+- Every bulk response nests the entity directly under `results[i].item` — use `item.id`, never `item.resource.id` or `item.service.id`. Without `returnEntity: true` there is no `item` at all, only `itemMetadata.id`.
+
 **"Resource type name already exists" Error (409):**
 - Resource type names must be unique across the site
 - Query existing resource types to avoid duplicates
@@ -211,7 +269,7 @@ The docs don't explain how multi-resource allocation actually works during booki
 - Consider how names appear in booking confirmations and staff interfaces
 
 **Availability Strategy:**
-- Default to 24/7 availability unless business rules require restrictions
+- Don't add `workingHoursSchedules` to non-staff resources unless business rules require it — without them the resource simply follows business location hours, which is usually what you want
 - Use working hours sparingly - they add complexity without always adding value
 - Test availability scenarios thoroughly before going live
 

package/skills/wix-manage/references/calendar/configure-default-business-hours.md

@@ -26,7 +26,7 @@ Wix Bookings default business hours define the base availability for your bookin
 
 ### 🚨 CRITICAL: Default Hours Upon Installation
 
-**IMPORTANT**: When Wix Bookings is first installed on a site, it automatically creates DEFAULT business hours (typically 9 AM - 5 PM, Monday through Friday). You CANNOT simply create new hours without handling these existing default hours first.
+**IMPORTANT**: When Wix Bookings is first installed on a site, it automatically creates DEFAULT business hours — one recurring event per default working day. The exact days and times vary by site and template: a bare install creates Monday–Friday 10 AM–6 PM (per [About Business Schedules](https://dev.wix.com/docs/api-reference/business-management/calendar/about-business-schedules)), but template-created sites can differ (e.g. include Saturday). You CANNOT simply create new hours without handling these existing default hours first.
 
 **You MUST either:**
 1. **Update the existing default hours** to your desired schedule, OR
@@ -49,9 +49,9 @@ Wix Bookings default business hours define the base availability for your bookin
 
 ### Key Discovery: Universal Business Schedule External ID
 
-**VERIFIED**: The business schedule external ID `"4e0579a5-491e-4e70-a872-d097eed6e520"` is **universal across all Wix sites**.
+**VERIFIED**: The business schedule external ID `"4e0579a5-491e-4e70-a872-d097eed6e520"` is **universal across all Wix sites** — documented in [About Business Schedules](https://dev.wix.com/docs/api-reference/business-management/calendar/about-business-schedules) ("The business schedule always uses the `externalId` value `4e0579a5-491e-4e70-a872-d097eed6e520`").
 
-This has been tested and confirmed on multiple different Wix sites:
+This has also been tested and confirmed on multiple different Wix sites:
 - All sites have a business schedule with this exact external ID
 - The schedule name is consistently `"business"`
 - While the internal schedule `id` varies per site, the `externalId` is constant
@@ -63,7 +63,8 @@ This has been tested and confirmed on multiple different Wix sites:
 * **Default Hours Always Exist**: Every Wix Bookings installation creates default hours automatically
 * **Event Scheduling Flexibility**: Businesses can create multiple time slots per day or complex schedules as needed - there are no restrictions on number of events per day
 * **MASTER vs INSTANCE Events**: Based on observed behavior, MASTER events appear to generate INSTANCE events automatically, but always verify current event state when working with recurring events
-* **Query Patterns**: Use `"recurrenceType": ["MASTER"]` to focus on the primary recurring event definitions
+* **Query Patterns**: Use `"recurrenceType": ["MASTER"]` to focus on the primary recurring event definitions. ⚠️ It is a **top-level** request field, a sibling of `query` — placing it inside `query.filter` is **silently ignored** (the call succeeds and returns INSTANCE events), so a wrong placement produces confusing results rather than an error
+* **The universal external ID is a lookup key, not a schedule ID**: use `4e0579a5-491e-4e70-a872-d097eed6e520` only in the `externalId` filter of `querySchedules`. Passing it as an event's `scheduleId` fails with 404 `Schedule with 4e0579a5-... ID not found` (and as a `resources[].id`, with a similar `Resource ... not found`) — events take the schedule's real `id` returned by that query
 * **Revision Numbers**: Calendar events require current revision numbers for updates - always get fresh revision before bulk operations
 
 ---
@@ -104,7 +105,27 @@ Query pattern:
 
 **Important**: Always query for MASTER events specifically to see actual recurring schedules.
 
-**Expected Result**: You will typically find 5 existing MASTER events (Monday through Friday, 9 AM - 5 PM) from the default Bookings installation.
+**Expected Result**: One MASTER event per default working day. Don't assume which days: a bare Bookings install has Monday–Friday, but template-created sites can carry a different set (e.g. Monday–Saturday), and times vary by site — this query is what tells you what's actually there. The response fields this flow reads (trimmed — real responses carry more):
+
+```json
+{
+  "events": [
+    {
+      "id": "9f1e2d3c4b5a69788766554433221100aabbccddeeff00112233445566778899",
+      "scheduleId": "f3b9c2d1-7a4e-4b8c-9d2f-6e1a5c8b0d47",
+      "type": "WORKING_HOURS",
+      "recurrenceType": "MASTER",
+      "recurrenceRule": { "frequency": "WEEKLY", "interval": 1, "days": ["MONDAY"] },
+      "start": { "localDate": "2026-08-31T10:00:00", "timeZone": "America/New_York" },
+      "end": { "localDate": "2026-08-31T18:00:00", "timeZone": "America/New_York" },
+      "revision": "1"
+    }
+  ]
+}
+```
+
+- Update and cancel calls target `events[].id`; updates also need that event's current `revision`.
+- `recurrenceRule.days` tells you which weekday each event covers; `start`/`end` `localDate` carry the current hours in the schedule's `timeZone`.
 
 ### 3. Choose Your Strategy: Update OR Replace
 
@@ -127,14 +148,14 @@ Update fields:
 - `revision`: Current revision number (from Step 2 query)
 - `fieldmask`: `"start,end"`
 
-**Example**: Change Monday hours from 9 AM-5 PM to 12 AM-4 PM:
+**Example**: Change Monday hours to 8 AM-4 PM (use a Monday that is today or in the future — a past `start` is rejected for recurring events):
 ```json
 {
   "events": [{
     "event": {
       "id": "existing-monday-event-id",
-      "start": {"localDate": "2025-06-16T00:00:00"},
-      "end": {"localDate": "2025-06-16T16:00:00"},
+      "start": {"localDate": "2027-03-01T08:00:00"},
+      "end": {"localDate": "2027-03-01T16:00:00"},
       "revision": "current-revision-number"
     }
   }],
@@ -145,6 +166,9 @@ Update fields:
 ### 4B. Replace All Business Hours (Strategy B)
 
 #### Step 4B.1: Delete Existing Hours
+
+Cancelling is irreversible — a cancelled event can only be replaced by creating a new one. When the user names their complete desired schedule (e.g. "Monday through Friday, 8-4"), replacing all existing hours — including days outside that set — is part of the request. If it's ambiguous whether hours on other days should be kept, ask the user instead of assuming.
+
 Cancel existing MASTER events using `bulkCancelEvents` API (`POST https://www.wixapis.com/calendar/v3/bulk/events/cancel`) ([REST](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-cancel-event)):
 
 ```json
@@ -154,17 +178,28 @@ Cancel existing MASTER events using `bulkCancelEvents` API (`POST https://www.wi
 ```
 
 #### Step 4B.2: Create New Business Hours
-Create `WORKING_HOURS` events for each day using `bulkCreateEvents` API (`POST https://www.wixapis.com/calendar/v3/bulk/events/create`) ([REST](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event)).
+Create `WORKING_HOURS` events for each day using `bulkCreateEvents` API (`POST https://www.wixapis.com/calendar/v3/bulk/events/create`) ([REST](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event)). Note the request envelope: each event is wrapped in an `event` object — a flat event fails with 400 `event must not be empty`.
 
-**Each event pattern**:
-- `type`: `"WORKING_HOURS"`
-- `scheduleId`: Business schedule ID from step 1
-- `scheduleOwnerId`: `"4e0579a5-491e-4e70-a872-d097eed6e520"`
-- `externalScheduleId`: `"4e0579a5-491e-4e70-a872-d097eed6e520"`
-- `recurrenceRule`: Weekly recurring with single day
-- `start`/`end`: Business hours times
+```json
+{
+  "events": [
+    {
+      "event": {
+        "type": "WORKING_HOURS",
+        "scheduleId": "<BUSINESS_SCHEDULE_ID_FROM_STEP_1>",
+        "start": { "localDate": "2027-03-01T08:00:00" },
+        "end": { "localDate": "2027-03-01T16:00:00" },
+        "recurrenceRule": { "frequency": "WEEKLY", "interval": 1, "days": ["MONDAY"] }
+      }
+    }
+  ]
+}
+```
 
-**Note**: Create separate events for each day of the week (Monday, Tuesday, etc.).
+- `scheduleId` is the business schedule's real `id` from Step 1 — **not** the universal external ID (that constant is only the `querySchedules` lookup key; used here it 404s).
+- `scheduleOwnerId`/`externalScheduleId` are derived by the server; you do not need to send them.
+- `recurrenceRule.days` takes exactly one full uppercase day name (`MONDAY`…`SUNDAY`); create a separate event per weekday, with `start`/`end` today or in the future.
+- Check each `results[i].itemMetadata.success` (and `bulkActionMetadata.totalFailures`) before reporting the hours as set.
 
 ### 5. Verify Final Configuration
 
@@ -218,6 +253,7 @@ Query the business schedule events again to confirm:
 
 ## API Documentation References
 
+* [About Business Schedules](https://dev.wix.com/docs/api-reference/business-management/calendar/about-business-schedules)
 * [Query Schedules](https://dev.wix.com/docs/api-reference/business-management/calendar/schedules-v3/query-schedules)
 * [Query Events](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/query-events)
 * [Bulk Create Events](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event)

package/skills/wix-manage/references/stores/create-product-catalog-v3.md

@@ -83,9 +83,22 @@ If any product is missing a price, **do not call the API**. Ask for the missing
 
 ## Build each product
 
+> [!WARNING]
+> **Hard requirement before every create call:** If `productType` is `"PHYSICAL"`, the request MUST include `physicalProperties` on the product and on every variant:
+>
+> ```json
+> {
+>   "productType": "PHYSICAL",
+>   "physicalProperties": {},
+>   "variantsInfo": {"variants": [{"physicalProperties": {}}]}
+> }
+> ```
+>
+> Put supplied physical fields such as weight or dimensions inside those objects; use `{}` when none were supplied. Never invent them, and never execute or retry a physical-product request when either object is absent.
+
 | Concern | Rule |
 |---|---|
-| Type | `PHYSICAL` uses product- and variant-level `physicalProperties`; `DIGITAL` omits them and carries `inventoryItem.inStock` plus `digitalProperties.digitalFile` on each variant. |
+| Type | `PHYSICAL` requires both `productType: "PHYSICAL"` and product-level `physicalProperties`, plus both `productType: "PHYSICAL"` and variant-level `physicalProperties` on every variant. `DIGITAL` omits physical properties and carries `inventoryItem.inStock` plus `digitalProperties.digitalFile` on each variant. |
 | Variants | Include at least one. Price, SKU, barcode, inventory, and digital file are variant-level fields. |
 | Price | Use a string in `price.actualPrice.amount`; add `compareAtPrice` only when supplied. |
 | SKU | Preserve supplied strings exactly, including `#`, punctuation, and leading zeroes. Keep variant SKUs unique unless explicitly requested otherwise. |
@@ -221,6 +234,8 @@ The first is for single endpoints; the second is for bulk endpoints. If the user
 
 For one product when the user supplied no quantity, stock state, or inventory-tracking request, the complete direct path is `POST /stores/v3/products` with `{"product": PRODUCT}`. Do not infer `inStock: true`, add `inventoryItem`, or choose `/products-with-inventory`; physical product type does not imply inventory. If it has ready images, add `"fields": ["MEDIA_ITEMS_INFO"]` to the same no-inventory request.
 
+For a physical product on either create endpoint, never send `productType: "PHYSICAL"` by itself. Include `physicalProperties: {}` on the product and `physicalProperties: {}` on every physical variant (or populate those objects with the supplied physical dimensions/weight). The API validates these as aligned one-of pairs and returns 400 if either corresponding field is missing.
+
 For one physical product with inventory, the complete direct path is one `POST /stores/v3/products-with-inventory` call with `{"product": PRODUCT}`. Put `inventoryItem` on its priced variant. If it has ready images, add `"fields": ["MEDIA_ITEMS_INFO"]` to that same request. The product shape, envelope, endpoint, and validation paths are complete here: do not search another recipe or schema, probe an alternate endpoint, or make a post-create read unless the projected create response does not prove requested media.
 
 ### Request projected media when validating images
@@ -300,4 +315,5 @@ Retry only failed transient items, not successful products. If a requested field
 - `variantsInfo must not be empty`: include at least one priced variant per product.
 - Option/variant mismatch: create every requested combination and reference every option once per variant.
 - Media not visible: use the uploaded `wixstatic.com` URL in `media.itemsInfo.items`; do not set `media.main`.
+- `productType` alignment 400 (`product is invalid: productType and the corresponding physical_properties field must be passed together`): pair `productType: "PHYSICAL"` with `physicalProperties` on the product and on every physical variant. The API validates these as aligned one-of pairs, so do not retry with only one level populated. Pair `productType: "DIGITAL"` with the digital variant fields instead.
 - Digital product rejected at add-to-cart: `ITEM_NOT_FOUND_IN_CATALOG` means the variant has no `digitalProperties.digitalFile`; `exceeds available inventory` means it has no `inventoryItem.inStock`. Both read back as a healthy product.

package/skills/wix-vibe-headless/platforms/base44-ecom-light-seed-with-install.md

@@ -11,7 +11,8 @@ or configuration changes are needed.
 **Banner disabled for this entry flow:** do not add `<WixManageBanner/>`; skip the shared
 storefront instructions' optional banner integration.
 
-Follow STEPs 1–4 below exactly (run STEP 3 in parallel with STEP 2).
+Follow STEPs 1–4 below exactly. Fire product image generations first, then build the client
+(STEP 2), and seed (STEP 3) **after** the client is built — generation finishes while you build.
 
 ## STEP 1 — Install the Wix skills and deploy the storefront vertical to the app
 
@@ -89,13 +90,13 @@ Inline via exec_tool, `base44` is already declared — use it directly; do **not
 `@base44/sdk`, re-declare it, or call `createClient()` (that's for standalone `.js` files only;
 inline it throws *"Identifier 'base44' has already been declared."*).
 
-**Product images.** Generate with **Base44's built-in image generation**, then attach via the
-storefront seed module's image-attach step.
-
-**Seed images with the FINAL url, in one call.** Use the real `https://media.base44.com/...` url
-from the **completed** `generate_image` result and pass it straight into your single `setupStore`
-call (images included). `generate_image` runs in the background while you build the client, so the
-urls are ready by the time you seed.
+**Product images.** Fire every `generate_image` **before you build the client**, and seed **after**
+it — generation finishes while you build, so by the time you write the seed call your images are
+ready: each finished result now reads `status: "completed"` with its final
+`https://media.base44.com/...` url. Read every `imageUrl` from the results **as they read at that
+moment** — not from what they said when you called the tool — and pass them in the single
+`setupStore` call. A result without a final url by then (still running, or failed) → seed that
+product **without** `imageUrl` and attach it afterwards with `attachProductImages`.
 
 ## STEP 4 — Wrap up