@wix/agent-skills 1.7.0 → 1.9.0

package/skills/wix-headless/references/bookings/FLOW.md

@@ -0,0 +1,185 @@
+# Bookings — the booking flow (framework-agnostic logic)
+
+The booking logic — the step model, the shared state, and the exact `@wix` SDK
+sequence — is the **same on every frontend** (astro, react/vite, vue, plain HTML).
+This file is that shared logic. The per-framework wiring layers on top:
+
+- **astro** (`frontendBuild: wix`): `../astro/bookings/SERVICES_PAGES.md` (SSR read pages) + `../astro/bookings/COMPONENTS.md` (the client islands).
+- **own / static** (`frontendBuild: own`/`none`): `../custom/bookings/WIRING.md`.
+
+**Code examples are React** (`../astro/templates/bookings/*.tsx` + `bookingDriver.ts`).
+React is directly usable on astro islands and on react/vite. **On any other
+framework, translate the examples** — the SDK calls and payloads are identical;
+only the UI idiom (`useState`/`useEffect` → a store / `onMounted` / signals) and
+the client acquisition differ (see "Client identity" below).
+
+The flow is **appointment booking**. CLASS sign-up reuses the same sequence with
+an event-slot branch (noted inline) and is a fast-follow, not v1. **Location and
+staff selection are likewise a fast-follow (a separate PR); add-ons are out of
+scope.** v1 threads a single service selection — the shared state below holds no
+location / staff / add-on choice yet.
+
+---
+
+## 1. The step model
+
+A single customer journey, five steps, holding one shared selection:
+
+```
+1. Catalog    list bookable services                         → pick a service
+2. Slots      week calendar of availability for that service → pick a time slot
+3. Details    the service's booking form (collect contact)   → submit
+4. Book       run the SDK sequence (§3)
+5a. paid      → redirect to the Wix-hosted checkout → returns to the confirmation page
+5b. free/offline → place the order → confirmation page
+```
+
+**The catalog is the entry point but optional** — a visitor can land directly on a
+service page and start at the Slots step. Every step rehydrates from the URL (§2),
+so deep links work.
+
+Mapping the steps onto pages/routes is the **target framework's choice** — translate
+the step model to whatever router the framework uses. The skill recommends the routes
+`/services`, `/services/[slug]`, `/booking-confirmation` (advertised in
+`../verticals/bookings.md`). On astro specifically, SSR the catalog + detail pages
+for SEO and run slots + form + book in a `client:only` island.
+
+## 2. Shared booking state
+
+Steps 1–4 build up one selection (this is exactly `BookParams` + `SelectedSlot`
+in `../astro/templates/bookings/bookingDriver.ts`):
+
+- **`service`** — the chosen service object (the booking step reads `service.payment` + `service.bookingPolicy`).
+- **`slot`** — `{ serviceType, serviceId, localStartDate, localEndDate, timezone, scheduleId?, eventId?, locationId?, locationType? }`.
+- **`formSubmission`** — the booking-form values, **keyed by each field's `target`** (§4).
+
+Hold it however the framework prefers (React state lifted to a coordinator, a
+store, route loaders + a provider, query-params). **Two rules that bite:**
+
+1. **Persist the selection before navigating.** When a step lives on its own
+   route, write the selection into the shared state (or the URL) *before* moving
+   on, and let the next step **rehydrate from the slug/URL** on direct load /
+   refresh. A persistent provider that does not re-init on in-app navigation will
+   otherwise show an empty next step.
+2. **The slug is the carry-across key.** `serviceSlug` (the service's
+   `mainSlug.name`) identifies the service across the slots + details steps;
+   resolve the full service from it when state is lost.
+
+## 3. The booking SDK sequence — `bookingDriver.ts`
+
+The whole booking — `createBooking → createCart → calculateCart → checkout-or-place`
+— is in **`../astro/templates/bookings/bookingDriver.ts`**, in plain `@wix` SDK
+calls (no React, no UI). **Use it as-is** (it is framework-agnostic); the booking
+step calls `book(params)` then branches on the result. Do not re-author the
+sequence — the payload shapes are exact and easy to get subtly wrong.
+
+```
+book({ service, slot, formSubmission, timezone }) →
+  createBooking(...)            // booking lands CREATED — the cart holds the seat
+  createCart(...)               // one catalog item per bookingId, appId = BOOKING_APP_ID, channel WEB
+  calculateCart(cartId)         // → { cart, summary }; totals on summary.priceSummary.total.amount
+  isCheckoutRequired(...) ?
+     → { CheckoutRequired, cartId }  // paid → navigateToCheckout(cartId, postFlowUrl) → Wix-hosted checkout
+     : placeOrder(cartId) → { CheckoutSkipped, orderId }   // free / pay-in-person → confirmation
+```
+
+Key facts the driver encodes (do not deviate):
+- **No `confirmBooking`** — `confirmBooking` is the classic Bookings server-side
+  confirm step (it moves a booking from `CREATED` to `CONFIRMED`). Here the **ecom
+  cart holds the seat** instead — `placeOrder` (free/offline) or the hosted checkout
+  (paid) drives confirmation — so a client-only site completes the whole flow with no
+  server elevation.
+- **ANY_RESOURCE fallback (staff)** — v1 has **no staff picker**, so `createBooking`
+  always sends `resourceSelections:[{ resourceTypeId:"1cd44cf8-…", selectionMethod:"ANY_RESOURCE" }]`
+  and Wix auto-assigns a bookable staff resource (appointment slots return
+  `availableResources:[]` yet book fine this way). (Explicit staff selection is a
+  fast-follow.)
+- **Checkout decision** — `isCheckoutRequired`: if the service's booking policy charges
+  a **cancellation fee** (`service.bookingPolicy.cancellationFeePolicy.enabled`) →
+  checkout (a card must be on file); else total 0 → place; else `FULL_PAYMENT_OFFLINE`
+  → place; else checkout.
+- **Redirect shape** — paid bookings hand the cart to the Wix-hosted **ecom**
+  checkout: `createRedirectSession({ ecomCheckout: { checkoutId: cartId }, callbacks:{ postFlowUrl } })`.
+
+### Browse + availability (the read calls the steps make)
+
+Mirror what the Bookings SDK does (`services.queryServices` is the raw SDK, not a component):
+
+```js
+// Catalog (list) — the filter MUST include appId; pass conditionalFields, then .find():
+services.queryServices({
+  query: { filter: { appId: BOOKING_APP_ID }, paging: { limit: 100 } },
+  conditionalFields: ["STAFF_MEMBER_DETAILS"],
+}).find();                                   // → result.items ; filter out s.hidden
+
+// Single service by slug — the .eq() builder chain:
+services.queryServices({ conditionalFields: ["STAFF_MEMBER_DETAILS"] })
+  .eq("mainSlug.name", slug).eq("appId", BOOKING_APP_ID).limit(1).find();
+
+// Availability (APPOINTMENT) — serviceId is a single GUID STRING:
+availabilityTimeSlots.listAvailabilityTimeSlots({
+  serviceId, fromLocalDate, toLocalDate, timeZone, bookable: true, cursorPaging: { limit: 100 },
+});                                          // slots: result.timeSlots[] (localStartDate/localEndDate/scheduleId at top level)
+
+// Availability (CLASS) — different namespace, PLURAL serviceIds; slots carry eventInfo.eventId, no scheduleId:
+eventTimeSlots.listEventTimeSlots({ serviceIds: [serviceId], fromLocalDate, toLocalDate, timeZone, includeNonBookable: false });
+```
+
+`fromLocalDate`/`toLocalDate` are **local** date strings `YYYY-MM-DDThh:mm:ss`
+(no `Z`) with an explicit `timeZone`.
+
+## 4. The booking form — schema-driven (`@wix/forms`)
+
+The booking form is a **`@wix/forms` form** attached to the service
+(`service.form._id`, namespace `wix.bookings.v2.bookings`). Render it
+**schema-driven** — read the field list and render inputs by field type — the
+**same renderer the forms vertical uses** (`../astro/forms/CONTACT_FORM.md`):
+
+1. Fetch the form by `service.form._id` (`@wix/forms` `getForm`; server-side/elevated
+   where the framework allows). Read `form.formFields`.
+2. Keep `fieldType === "INPUT" && !hidden` **and** a recognized string
+   `componentType` (`TEXT_INPUT` / `PHONE_INPUT` / `DROPDOWN`). For each, take
+   `inputOptions.target`, `inputOptions.required`, `inputOptions.stringOptions.componentType`,
+   and the label from `inputOptions.stringOptions.{textInputOptions|dropdownOptions|phoneInputOptions}.label`.
+   **Skip complex, object-valued fields** — e.g. a multi-line `ADDRESS` — they carry
+   no string `componentType`; rendering them as a text input sends a string and
+   `createBooking` rejects it with **"must be object"**. The booking enforces only
+   the contact basics (`first_name`/`last_name`/`email`), so omitting an optional
+   complex field is safe (do **not** default unknown field types to a text input).
+3. Render generic inputs by `componentType`: `TEXT_INPUT` → text input,
+   `DROPDOWN` → select, `PHONE_INPUT` → `type=tel`; treat `identifier === "TEXT_AREA"`
+   (or `target` containing `message`) as a textarea (its `componentType` is still `TEXT_INPUT`).
+4. Collect the values into an object **keyed by each field's `target`** — that is
+   `formSubmission`. Pass it to `book()`. Only include fields the visitor filled;
+   never send a value for a field you didn't render.
+
+**Do not** submit `contactDetails`, and **do not** hardcode field names — key by
+`target`. The default booking form's targets are snake_case `first_name` /
+`last_name` / `email` / `phone`. Reference example: `../astro/templates/bookings/BookingForm.tsx`.
+
+## 5. The day-calendar (slots step)
+
+Show a **week calendar**, not a flat list of every slot: a 7-day strip with
+week navigation → the picked day's times. A flat grid with time-only labels
+leaves the visitor unable to tell which day a slot is on. Fetch availability for
+the visible window (`fromLocalDate`/`toLocalDate` = the week bounds), group slots
+by calendar day, and offer a **"check next availability"** action that probes
+forward when a week is empty. Reference example:
+`../astro/templates/bookings/AvailabilityCalendar.tsx`.
+
+## 6. Client identity (per framework)
+
+The SDK calls are identical everywhere; only how you get the client differs:
+- **astro** — SSR read pages use the ambient `@wix/essentials` client
+  (`auth.elevate(services.queryServices)(...)`); browser islands call the `@wix`
+  modules **ambiently** too (the `@wix/astro` visitor client, like the ecom
+  `CartView` island) — no `createClient`/`OAuthStrategy`.
+- **own / static** — acquire a visitor client once:
+  `createClient({ modules, auth: OAuthStrategy({ clientId: appId }) })` and call
+  the same functions on it. CDN imports for `none`, bundled for `own`.
+
+## 7. Out of v1
+
+Waitlist, on-site manage/cancel, location selector, staff filter, payment
+breakdown, and CLASS sign-up are out of v1. Show bookable slots only;
+post-booking self-service is handled by the Wix-hosted flow / member area.

package/skills/wix-headless/references/bookings/INSTRUCTIONS.md

@@ -0,0 +1,90 @@
+---
+name: bookings-implementer
+description: "Implements the Wix Bookings vertical — services catalog, a service detail page with a week-calendar availability picker, a schema-driven booking form, and confirmation. The booking runs client-side via the @wix SDK (ecom Cart V2 — no confirmBooking). Scopes: seed, components, pages. Extends references/shared/IMPLEMENTER.md."
+---
+
+# Bookings Implementer
+
+Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, the `.wix/seeded.json` read pattern, the return contract, style conventions, and common failure modes.
+
+## The logic lives in one place
+
+The booking **logic** — the step model, the shared selection state, the exact
+`@wix` SDK sequence, and the schema-driven form — is framework-agnostic and lives
+in **`./FLOW.md`**. Read it first. The astro guides below are the astro *wiring* of
+that logic; the code examples under `<SKILL_ROOT>/references/astro/templates/bookings/`
+are React (the astro islands use them directly). For an own/static build, the wiring guide is
+`../custom/bookings/WIRING.md` (same logic, client-side `@wix/sdk`).
+
+## Scope routing
+
+| Scope | Phase | Reference |
+|-------|-------|-----------|
+| `seed` | Seed — create services (and staff) via the Wix Bookings REST API | `./SERVICES_DATA.md` |
+| `components` | Components — the client islands (week calendar, schema-driven form, the flow coordinator) | `./FLOW.md` + `../astro/bookings/COMPONENTS.md` |
+| `pages` | Pages — `/services` listing, `/services/[slug]` detail, `/booking-confirmation`, + nav/home links | `./FLOW.md` + `../astro/bookings/SERVICES_PAGES.md` |
+
+## Templates — read and adapt (don't invent)
+
+Canonical examples live at `<SKILL_ROOT>/references/astro/templates/bookings/`.
+Your `components` and `pages` scopes **read these and adapt them** — adapt brand
+copy, headings, and styling; keep the SDK calls, payload shapes, and the data
+flow (re-authoring the SDK wiring from scratch is the main source of API-shape bugs).
+
+Components (`components` scope — TSX only, no CSS):
+- `<SKILL_ROOT>/references/astro/templates/bookings/AvailabilityCalendar.tsx` — the week calendar (week strip → the day's slots; APPOINTMENT via `availabilityTimeSlots`, CLASS via `eventTimeSlots`).
+- `<SKILL_ROOT>/references/astro/templates/bookings/BookingForm.tsx` — the schema-driven form (renders the `@wix/forms` field list, keys values by `target`) that drives `bookingDriver.book()`.
+- `<SKILL_ROOT>/references/astro/templates/bookings/ServiceBookingFlow.tsx` — the coordinator island (holds the selected slot; calendar → form → redirect).
+
+Pages (`pages` scope):
+- `<SKILL_ROOT>/references/astro/templates/bookings/ServiceCard.astro`
+- `<SKILL_ROOT>/references/astro/templates/bookings/services/index.astro`, `<SKILL_ROOT>/references/astro/templates/bookings/services/[slug].astro`
+- `<SKILL_ROOT>/references/astro/templates/bookings/booking-confirmation.astro`
+
+### Pre-copied by the orchestrator (do NOT write these yourself)
+Mechanical, brand-agnostic — the orchestrator copies them before dispatch (BUILD-astro.md § build wave). Rely on them at the listed paths:
+- `src/components/bookingDriver.ts` ← `<SKILL_ROOT>/references/astro/templates/bookings/bookingDriver.ts` — the booking SDK sequence (`book()`, `navigateToCheckout()`). The islands import it; never re-author it.
+- `src/components/SeoTags.astro` ← `<SKILL_ROOT>/references/astro/templates/bookings/SeoTags.astro` — renders `service.seoData.tags`; imported by `services/[slug].astro`.
+- `src/styles/components-bookings.css` ← `<SKILL_ROOT>/references/astro/templates/bookings/components-bookings.css` — the flow's component classes.
+
+If a pre-copied file is missing at runtime, that's an orchestrator-side bug — return `status: "partial"` with `errors: [{code: "UTILITY_TEMPLATE_NOT_PRECOPIED", path: "<missing>"}]`; do not author your own version.
+
+## Pre-return file-existence assertion (pages scope)
+
+Before returning `status: "complete"` from `pages`, verify on disk:
+- `src/pages/services/index.astro`
+- `src/pages/services/[slug].astro`
+- `src/pages/booking-confirmation.astro`
+
+If any declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]`.
+
+## Dependencies (Setup installs these — see SETUP.md)
+
+`@wix/bookings @wix/essentials @wix/forms @wix/redirects @wix/auto_sdk_ecom_cart-v-2`.
+`@wix/forms` renders the booking-form schema; `@wix/redirects` + `@wix/auto_sdk_ecom_cart-v-2` run the cart/checkout sequence.
+
+## CSS ownership — bookings pack
+
+Bookings-specific CSS lives in `src/styles/components-bookings.css` (pre-copied — see above), NOT in `global.css`. Classes the pack owns: `.service-card*`, `.service-grid`, `.availability-*`, `.time-slot*`, `.booking-*`. If `global.css` ships a partial rule for any of these, flag it (`{code:"GLOBAL_CSS_LEAK", class:"<name>"}`) and override in `components-bookings.css`.
+
+## Bookings-specific failure modes
+
+| Wrong | Right |
+|-------|-------|
+| Stop after `createBooking` returns | `createBooking` leaves the booking **`CREATED`**. The seat is held by the **ecom Cart V2**: continue `createCart → calculateCart → isCheckoutRequired ? hosted-checkout redirect : placeOrder`. The whole sequence is in `bookingDriver.ts` — use it. |
+| Hardcode `selectedPaymentOption: "ONLINE"` on `createBooking` | **Derive** it from the service: `online && !inPerson → "ONLINE"`, `!online && inPerson → "OFFLINE"`, else `"ONLINE"`. A free / pay-in-person service is the only kind that reaches `placeOrder`, and booking it `ONLINE` makes the cart reject it with **`INSUFFICIENT_INVENTORY`** (`available_quantity: 0`). `bookingDriver.ts` derives this for you (don't pass `selectedPaymentOption` to `book()`). |
+| Pass `contactDetails` to `createBooking` | Pass **`formSubmission`**, keyed by each field's **`target`** (default booking form: snake_case `first_name`/`last_name`/`email`/`phone`). `contactDetails` is what Wix derives back onto the response. |
+| Hardcode the booking-form fields | Render the form **schema-driven**: read `service.form._id`'s fields via `@wix/forms`, render by `componentType`, key values by `target` (same renderer as `../astro/forms/CONTACT_FORM.md`). |
+| Render every form field as a text input (default unknown types to `TEXT_INPUT`) | Render **only** fields with a recognized string `componentType` (`TEXT_INPUT`/`PHONE_INPUT`/`DROPDOWN`). **Skip complex, object-valued fields** (e.g. the default booking form's multi-line `ADDRESS`) — sending a string for them fails `createBooking` with **"must be object"**. Only `first_name`/`last_name`/`email` are enforced, so skipping optional complex fields is safe. |
+| Call `queryServices` without an `appId` filter | Always include `appId` (`13d21c63-…`) in the filter. List: `queryServices({ query:{ filter:{ appId }, paging }, conditionalFields:["STAFF_MEMBER_DETAILS"] }).find()`. Single: the `.eq("mainSlug.name", slug).eq("appId", …).limit(1).find()` builder chain. |
+| Build `createClient({ auth: OAuthStrategy({ clientId: import.meta.env.* }) })` in `.astro` SSR | The `*_WIX_CLIENT_ID` env var is client-only → `undefined` at server render → 500. SSR reads use the ambient `@wix/essentials`: `auth.elevate(services.queryServices)(...)`. |
+| Build an `OAuthStrategy` client inside an astro browser island | Astro islands call the `@wix` modules **ambiently** (the `@wix/astro` visitor client, like the ecom `CartView`) — no `createClient`. (Own/static builds DO use `OAuthStrategy` — `../custom/bookings/WIRING.md`.) |
+| Pass UTC ISO strings to `listAvailabilityTimeSlots` | Use **local** date strings `YYYY-MM-DDThh:mm:ss` (no `Z`) + a separate `timeZone`. |
+| `availability.queryAvailability` / `import { availability }` | APPOINTMENT → `availabilityTimeSlots.listAvailabilityTimeSlots({ serviceId: <string> })`; CLASS → `eventTimeSlots.listEventTimeSlots({ serviceIds: [<string>] })`. The `availability` namespace does not exist. |
+| Read slot time from `timeSlot.slot.startDate` | Slot fields are at the **top level**: `localStartDate`, `localEndDate`, `scheduleId` (APPOINTMENT). CLASS slots carry `eventInfo.eventId` and have **no** `scheduleId`. |
+| Dump every slot in one flat, time-only grid | Show a **week calendar**: a day strip → the picked day's times. A flat grid hides which day a slot is on. |
+| Read service slug from `service.slug` / name from `service.info.name` | V2 is flat: slug `service.mainSlug.name` (fallback `supportedSlugs[0].name`), `service.name`, `service.description`, `service.tagLine`; duration `service.schedule.availabilityConstraints.sessionDurations[0]`; price `service.payment.fixed.price.value` (string); media `service.media.mainMedia.image.url`. |
+| Use `service.id` / `result.booking.id` | Entity ids are `_id` (underscore): `service._id`, `booking._id`. |
+| Mount the calendar/form without `client:only="react"` | Availability + booking are timezone/session-specific — always `client:only="react"`. SSR only the read pages (catalog/detail) for SEO. |
+| Omit try/catch on the booking | `createBooking` can reject (e.g. a slot taken between fetch and submit, or strict phone validation). Catch and surface a friendly message; don't crash. |
+| Ship a location selector, staff filter, payment breakdown, CLASS sign-up, or waitlist | Out of v1 — appointment booking only. |

package/skills/wix-headless/references/bookings/SERVICES_DATA.md

@@ -0,0 +1,295 @@
+# Bookings Seed — Services Data
+
+You are seeding Wix Bookings services for a headless site. Your job:
+1. Mint a site-scoped token once.
+2. **If `intent.bookings.hasStaff` is `true`** — create staff members FIRST (Step 3 below), then pass their `resourceId`s on each service. **Every APPOINTMENT service needs a non-empty `staffMemberIds`** or it's rejected with `MISSING_APPOINTMENT_RESOURCES` — even when `hasStaff` is false you must pass the default **Business Owner** `resourceId` (see § "When hasStaff is false"). (CLASS services don't need a resource at create time.)
+3. Create `intent.bookings.serviceCount` services via the Bookings V2 REST API. When staff exist, pass their `resourceId` values via `staffMemberIds`.
+4. Return all created IDs in the standard return contract.
+
+> **Order matters.** Steps 3 and 4 in this file are presented in the order you should execute them: staff first (when applicable), then services. The old "services-first then staff-optionally" order fails for APPOINTMENT with `MISSING_APPOINTMENT_RESOURCES`.
+
+---
+
+## Step 1 — Mint the token
+
+```bash
+TOKEN=$(npx @wix/cli@latest token --site "<siteId>")
+```
+
+Cache in subagent scratch. Every subsequent `curl` reuses it. Every call carries:
+```
+Authorization: Bearer $TOKEN
+wix-site-id: <siteId>
+Content-Type: application/json
+```
+
+---
+
+## Step 2 — Verify Wix Bookings is installed
+
+Query staff members as an installation check. A successful response (even an empty list) confirms Bookings is installed:
+
+```bash
+curl -sS -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "wix-site-id: <siteId>" \
+  -H "Content-Type: application/json" \
+  -d '{"query":{}}' \
+  "https://www.wixapis.com/bookings/v1/staff-members/query"
+```
+
+- **200 OK** → proceed.
+- **403 / "Business schedule not found"** → Bookings app is not installed. Return `status: "error"` with the response verbatim. Do not attempt to install it — the orchestrator's Setup phase handles app installation.
+
+---
+
+## Step 3 — Create staff members (when `intent.bookings.hasStaff` is `true`)
+
+Execute this step BEFORE Step 4 when staff are required. APPOINTMENT services need at least one resource to exist before they can be created.
+
+For each staff member to create (derive names from the brand; default to 2 staff):
+
+```bash
+# Build the payload — only include phone/email when non-empty.
+# The V1 staff-members API rejects "" as an invalid email/phone.
+curl -sS -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "wix-site-id: <siteId>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "staffMember": {
+      "name": "<First Last>",
+      "description": "<professional bio — 1–2 sentences, brand-appropriate>"
+    }
+  }' \
+  "https://www.wixapis.com/bookings/v1/staff-members"
+```
+
+> **Do NOT send `"phone": ""` or `"email": ""`** — V1 validates them as format-checked fields and rejects empty strings with `is not a valid email/phone`. Omit the keys entirely when you don't have a real value. If the merchant later wants to populate phone/email, they can do it from the dashboard or via a PATCH.
+
+**Important:** Staff inherit business working hours at creation time. For a basic seed, this is fine — the merchant can configure custom hours from the dashboard later.
+
+Save `staffMember.id` and `staffMember.resourceId` from each response. **You will pass the `resourceId` values into the `staffMemberIds` field on each service in Step 4.**
+
+> **Note:** `staffMemberIds` on services expects `resourceId` values (from `staffMember.resourceId`), NOT `staffMember.id`. Using `staffMember.id` here is the most common cause of "service has no provider" runtime errors.
+
+> **Do NOT attempt custom working hours setup during seed.** The two-step custom-hours workflow (assignWorkingHoursSchedule + WORKING_HOURS events) is complex and fragile. Default inherited hours are sufficient for an initial build. If you encounter "Business schedule not found", skip staff creation and return a warning in `notes`.
+
+### When `hasStaff` is `false`
+
+For `serviceType: "CLASS"`, no staff/resource is needed at service-creation time — skip this step.
+
+For `serviceType: "APPOINTMENT"` with `hasStaff: false`, you **still must pass a resource** in `staffMemberIds` — an empty `[]` is **rejected** with `MISSING_APPOINTMENT_RESOURCES` (*"service of type appointment requires at least one staff member or service resource"*). The Wix Bookings app provisions a default **Business Owner** resource at install; query it and pass **its** `resourceId`:
+
+```bash
+# Get the default Business-Owner resourceId (no staff were created).
+curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "wix-site-id: <siteId>" -H "Content-Type: application/json" \
+  -d '{"query":{}}' "https://www.wixapis.com/bookings/v1/staff-members/query"
+# → take the staffMember named "Business Owner" and use its `resourceId` as the single
+#   entry in each APPOINTMENT service's `staffMemberIds`.
+```
+
+(Do **not** rely on `[]` — the default resource does not auto-satisfy the requirement at create time. CLASS services don't need this.)
+
+---
+
+## Step 4 — Create services (Services V2 API)
+
+**Endpoint:** `POST https://www.wixapis.com/_api/bookings/v2/services`
+
+> **V2 payload is flat — NOT nested under `info`.** Fields are `name`, `description`, `tagLine` at the top level of the `service` object. The V1 shape (`info.name`, `info.description`) is rejected by V2. Price uses `value`, not `amount`.
+
+For each service to create (derive names, descriptions, and prices from `brand` + `intent.bookings`):
+
+```bash
+curl -sS -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "wix-site-id: <siteId>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "service": {
+      "type": "<APPOINTMENT|CLASS>",
+      "name": "<service name>",
+      "description": "<brand-appropriate description>",
+      "tagLine": "<short tagline>",
+      "defaultCapacity": 1,
+      "onlineBooking": {
+        "enabled": true,
+        "requireManualApproval": false,
+        "allowMultipleRequests": false
+      },
+      "schedule": {
+        "availabilityConstraints": {
+          "sessionDurations": [<duration as integer, e.g. 60>]
+        }
+      },
+      "payment": {
+        "rateType": "FIXED",
+        "fixed": {
+          "price": {
+            "value": "<price as string, e.g. \"75.00\">",
+            "currency": "USD"
+          }
+        },
+        "options": {
+          "online": true,
+          "inPerson": false,
+          "deposit": false,
+          "pricingPlan": false
+        }
+      },
+      "locations": [
+        {
+          "type": "BUSINESS"
+        }
+      ],
+      "staffMemberIds": [<resourceId values — staff from Step 3, OR the default Business-Owner resourceId when hasStaff is false. NEVER [] for APPOINTMENT — it 400s with MISSING_APPOINTMENT_RESOURCES>]
+    }
+  }' \
+  "https://www.wixapis.com/_api/bookings/v2/services"
+```
+
+> **`locations.type` enum:** the valid values are `UNKNOWN_LOCATION_TYPE`, `CUSTOM`, `BUSINESS`, and `CUSTOMER`. Use `"BUSINESS"` for "at the business address" (the seed default). Do NOT use `"OWNER_BUSINESS"` here — that string IS valid for `createBooking.bookedEntity.slot.location.locationType` on the bookings endpoint, but the **services** endpoint rejects it. Same field name, different enum.
+
+> **`staffMemberIds`:** pass `resourceId` values (not staffMember `id` values). For APPOINTMENT this array must be **non-empty** — when `hasStaff` is `false`, pass the default **Business Owner** `resourceId` (query it per § "When hasStaff is false"); `[]` is rejected with `MISSING_APPOINTMENT_RESOURCES` (verified live). CLASS services don't require it.
+
+**Response shape:**
+```json
+{
+  "service": {
+    "id": "<uuid>",
+    "name": "<name>",
+    "description": "<description>",
+    "mainSlug": { "name": "<url-slug>", "custom": false },
+    "supportedSlugs": [{ "name": "<url-slug>", "custom": false }],
+    "type": "APPOINTMENT",
+    "payment": { ... },
+    "schedule": { ... }
+  }
+}
+```
+
+> **Slug:** Extract from `service.mainSlug.name`. If absent, derive from the service name: lowercase, replace spaces and non-alphanumeric chars with hyphens, deduplicate hyphens.
+
+### Service creation guidelines
+
+- **Count**: Create exactly `intent.bookings.serviceCount` services (default 3 when not specified).
+- **Type**: Use `"APPOINTMENT"` for 1-on-1 services (the default); use `"CLASS"` when `intent.bookings.serviceType === "CLASS"`. For `CLASS`, set `defaultCapacity` to the max participants (e.g. `20`) instead of `1`.
+
+> **⚠️ CLASS services need scheduled sessions before anyone can sign up.** Creating a CLASS service does **not** create any bookable sessions. The front-end lists bookable sessions via `eventTimeSlots.listEventTimeSlots()`, which returns scheduled **session events** — a freshly created CLASS service has none, so its calendar is permanently empty. **For CLASS services you MUST run Step 4b below** to schedule sessions; otherwise the class calendar is a dead end. (APPOINTMENT services don't need this — their bookable times come from staff working hours + `availabilityTimeSlots`.)
+- **`sessionDurations`**: Required for APPOINTMENT. An array containing one integer (minutes). Do NOT specify for CLASS or COURSE services.
+- **Names + descriptions**: Derive from `brand.description`. Examples: a yoga studio → "60-min Vinyasa Flow" (60 min), "30-min Morning Meditation" (30 min), "90-min Deep Restore" (90 min). A hair salon → "Women's Cut & Style" (60 min, $85), "Men's Haircut" (30 min, $45), "Balayage Color" (120 min, $150). Make them brand-appropriate — not generic.
+- **Duration** (integers in minutes): Brand-appropriate. Consultation → 30; standard service → 60; premium/complex → 90–120.
+- **Price `value`**: A string, not a number. Brand-appropriate, non-trivial. A budget studio might charge `"25.00"`; a premium clinic `"250.00"`. Default to mid-range when unclear.
+- **Currency**: Set `"USD"` unless the brand's locale implies otherwise — **but note the site's business currency wins**: Services V2 silently stores the site-locale currency (e.g. a EUR-locale site stores `EUR` even when you send `USD`). This is not an error; the page templates format from the service's returned `currency`, so display stays correct. Don't fight it.
+- **Fire all service creates as a parallel batch** — they are independent calls.
+
+### Required fields summary (V2)
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `type` | Yes | `APPOINTMENT`, `CLASS`, or `COURSE` |
+| `name` | Yes | Display name |
+| `defaultCapacity` | Yes | `1` for APPOINTMENT; participant count for CLASS |
+| `onlineBooking.enabled` | Yes | Set to `true` for online booking |
+| `payment.rateType` | Yes | `FIXED`, `NO_FEE`, `VARIED`, or `CUSTOM` |
+| `payment.options.online` or `payment.options.inPerson` | Yes | At least one must be `true` |
+| `schedule.availabilityConstraints.sessionDurations` | APPOINTMENT only | Array with one integer (minutes) |
+
+---
+
+## Step 4b — Create class sessions (CLASS services only)
+
+A CLASS service is bookable only once its **schedule** has scheduled session events. Sessions are **Calendar Events V3** (not part of `@wix/bookings`), created via REST. Run this for every service you created with `type: "CLASS"`; skip it entirely for APPOINTMENT.
+
+**Endpoint:** `POST https://www.wixapis.com/calendar/v3/events`
+
+You need two things from earlier steps:
+- the service's **schedule id** — `service.schedule.id` from the Step 4 create response (every service has one);
+- a **resource id** — a CLASS event requires **at least one resource** (`resources` non-empty) or it's rejected. Use a staff `resourceId` from Step 3; if no staff were created, use the default Business-Owner resource's `resourceId` (query `POST /bookings/v1/staff-members/query` with `{"query":{}}` and take the one named `Business Owner`).
+
+```bash
+# One session. Repeat for several upcoming dates per class (e.g. 3 over the next
+# ~2 weeks) so the calendar isn't empty. `localDate` is local time, no `Z`.
+curl -sS -X POST \
+  -H "Authorization: Bearer $TOKEN" -H "wix-site-id: <siteId>" -H "Content-Type: application/json" \
+  -d '{
+    "event": {
+      "scheduleId": "<service.schedule.id>",
+      "type": "CLASS",
+      "start": { "localDate": "2026-06-05T09:00:00" },
+      "end":   { "localDate": "2026-06-05T10:00:00" },
+      "resources": [ { "id": "<staff resourceId>", "permissionRole": "WRITER" } ],
+      "totalCapacity": 12
+    }
+  }' \
+  "https://www.wixapis.com/calendar/v3/events"
+```
+
+> **Gotchas (verified against the live API):**
+> - `resources[].permissionRole` **must** be `"WRITER"` (or `"COMMENTER"`). Omitting it defaults to `UNKNOWN_ROLE` → `400 "resources.permissionRole must not be UNKNOWN_ROLE"`.
+> - `resources` must be **non-empty** for CLASS — a session with no resource is rejected.
+> - `start`/`end` use `{ "localDate": "YYYY-MM-DDThh:mm:ss" }` (local, no `Z`); seconds are ignored.
+> - For a recurring weekly schedule instead of one-off sessions, add `event.recurrenceRule` (`{ "frequency": "WEEKLY", "interval": 1, "days": ["MONDAY"], "until": { "localDate": "..." } }` — only `WEEKLY` and a **single** day are supported; this creates a `MASTER` event and Wix auto-generates the instances). One-off sessions are simpler and sufficient for a seed.
+> - `totalCapacity` defaults to the schedule's `defaultCapacity` if omitted; set it explicitly to the class size.
+
+Verify by fetching slots the way the front-end does (`eventTimeSlots.listEventTimeSlots({ serviceIds: [id], … })`) or `POST /calendar/v3/events/query` filtered by `scheduleId`. Record each session's event id in your return under `seeded.bookings.services[].sessionEventIds` if you want Phase 4 to deep-link.
+
+> **Booking-policy toggles (optional, CLASS).** Both live on the default booking policy — get it once via `POST /bookings/v1/booking-policies/query` with body `{"query":{}}` (an empty `{}` body is rejected with `query must not be empty`), then `PATCH /bookings/v1/booking-policies/<id>` with the relevant block + `fieldMask`:
+> - **Waitlist** (so a full session offers "join waitlist"): `"waitlistPolicy": { "enabled": true, "capacity": 10, "reservationTimeInMinutes": 10 }`, `fieldMask.paths: ["waitlistPolicy"]`.
+> - **Multi-participant** (party size > 1): `"participantsPolicy": { "maxParticipantsPerBooking": <N> }`, `fieldMask.paths: ["participantsPolicy"]`. **Defaults to `1`** — without raising it, the front-end party-size selector lets the user pick >1 but `createBooking` rejects it. Raise it (e.g. `4`) to actually enable multi-participant class booking.
+>
+> Skip whichever the build doesn't surface.
+
+---
+
+## Step 5 — Return contract
+
+**Return this JSON inline as your agent return** (per `references/shared/RETURN_CONTRACT.md`) — do **NOT** write a `.wix/seed-returns/` file; the orchestrator aggregates seeder returns and is the sole writer of `.wix/seeded.json`:
+
+```json
+{
+  "phase": "seed-bookings",
+  "status": "ok",
+  "seeded": {
+    "services": [
+      {
+        "id": "<uuid>",
+        "slug": "<mainSlug.name>",
+        "name": "<name>",
+        "type": "APPOINTMENT",
+        "durationMinutes": 60,
+        "price": "75.00",
+        "currency": "USD"
+      }
+    ],
+    "staff": [
+      { "id": "<uuid>", "resourceId": "<uuid>", "name": "<name>" }
+    ]
+  },
+  "recipeCalls": [
+    { "url": "https://www.wixapis.com/_api/bookings/v2/services", "status": 200 }
+  ]
+}
+```
+
+- `staff` is an empty array `[]` when `intent.bookings.hasStaff` is false or Step 3 was skipped.
+- **For `CLASS` services, schedule sessions in Step 4b** and report them (e.g. `seeded.bookings.services[].sessionEventIds`). Only if Step 4b is skipped or fails, add a `notes` entry so the orchestrator surfaces it: `"notes": ["CLASS sessions not scheduled — add session times in the Bookings dashboard before sign-up works."]`
+- On any REST error: set `status: "error"`, include the failing call's response verbatim under `"error"`.
+
+---
+
+## Common failure modes
+
+| Failure | Recovery |
+|---------|----------|
+| 403 on service create | Re-mint token and retry once. If still 403, Bookings app was not installed — return `status: "error"`. |
+| 400 `"defaultCapacity is required"` | Add `"defaultCapacity": 1` to the payload (required in V2, not obvious from V1 docs). |
+| 400 `"onlineBooking is required"` | Add `"onlineBooking": { "enabled": true }` — required in V2. |
+| 400 on `payment.options` | At least one of `online` or `inPerson` must be `true`. Set `"inPerson": true` as fallback. |
+| 400 `"sessionDurations is required"` | Add `"schedule": { "availabilityConstraints": { "sessionDurations": [60] } }` for APPOINTMENT types. |
+| 400 `MISSING_APPOINTMENT_RESOURCES` on service create | An APPOINTMENT service's `staffMemberIds` must be **non-empty**. Pass the created staff `resourceId`s (Step 3), or — when `hasStaff` is false — the default **Business Owner** `resourceId` (query `/bookings/v1/staff-members/query` with `{"query":{}}`). An empty `[]` always 400s here. |
+| 400 enum error on `locations.type` | Use `"BUSINESS"`, not `"OWNER_BUSINESS"`. The services endpoint accepts `UNKNOWN_LOCATION_TYPE`, `CUSTOM`, `BUSINESS`, `CUSTOMER`. `OWNER_BUSINESS` is valid on `createBooking.bookedEntity.slot.location.locationType` only. |
+| 400 `is not a valid email/phone` on staff create | Don't send `"phone": ""` or `"email": ""`. Omit the keys entirely when you don't have a real value. |
+| `mainSlug` absent in response | Derive slug from `service.name`: lowercase, replace spaces with hyphens, strip non-alphanumeric. |
+| Staff create returns "Business schedule not found" | Skip staff creation. Return partial seeded data with `notes: ["Staff creation skipped — business schedule not found; configure via Bookings dashboard"]`. |

package/skills/wix-headless/references/cms/CMS_FOUNDATIONS.md

@@ -50,7 +50,7 @@ body: {
 }
 ```
 
-The response returns the created item's `_id` — collect these for the Phase 1 return contract.
+The response returns the created item's `_id` — collect these for the seed return contract.
 
 **Every text field must be populated in the `data` object.** Do not create items with empty `data: {}` and expect Phase 2 or the image agent to fill in text fields — they only handle their own scope (pages and images respectively).
 
@@ -70,6 +70,8 @@ body: {
 }
 ```
 
+> **Bulk insert (N ≥ 2 items):** use the `wix-manage` skill's recipe — `wix-manage/references/cms/cms-data-items-crud.md` § "Bulk Insert Items" (`POST /wix-data/v2/bulk/items/insert`, up to 1000/call, one `dataCollectionId` per call → fire one bulk call per collection as a parallel batch). It also documents bulk update/patch/delete. Do not hand-roll N single inserts for a multi-item seed.
+
 ### Verify inserts with a live query (mandatory)
 
 After inserting all items, **query each collection once** and confirm every field you sent is present in the stored `data`. A POST without errors does NOT prove the content persisted — the API has accepted insert bodies with missing fields before, and the failure is invisible until a human opens the page.
@@ -140,7 +142,7 @@ Emit a structured JSON block at the end of your completion message per `../share
 {
   "status": "complete",
   "phase": "cms-seed",
-  "scope": "seed-seed",
+  "scope": "seed",
   "summary": "Created {N} collections; seeded {M} items; verified every field persisted",
   "data": {
     "collections": [

package/skills/wix-headless/references/cms/INSTRUCTIONS.md

@@ -5,7 +5,7 @@ description: "Implements structured content pages (About, FAQ, portfolios, team
 
 # CMS Implementer
 
-Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, prompt-inlined inputs (no site.json reads), return contract, style conventions, and common failure modes.
+Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, prompt-inlined inputs (read only your `.wix/seeded.json` slice), return contract, style conventions, and common failure modes.
 
 ## Scope routing
 
@@ -29,6 +29,32 @@ Pick based on the business type (the orchestrator names one in your prompt):
 
 See `<SKILL_ROOT>/references/verticals/cms.md` frontmatter.
 
+## Seed return
+
+The `seed` scope emits this `data` shape in its return JSON (envelope rules in `../shared/RETURN_CONTRACT.md`). Phase 4 CMS page agents reference these collection names; the image agent attaches entity images to CMS items by ID.
+
+```json
+{
+  "status": "complete",
+  "phase": "cms-seed",
+  "scope": "seed",
+  "data": {
+    "collections": [
+      {
+        "name": "about-content",
+        "itemIds": ["665f3363-..."],
+        "fields": ["heading", "body", "image"]
+      },
+      {
+        "name": "faq",
+        "itemIds": ["abc", "def", "ghi", "jkl", "mno", "pqr"],
+        "fields": ["question", "answer", "sortOrder"]
+      }
+    ]
+  }
+}
+```
+
 ## Page width (FAQ, About, long-form CMS)
 
 Read `references/shared/STYLING.md` § "Prose / reading width". **Do not** wrap FAQ/About body copy in `max-w-3xl` unless `--container-3xl` exists in `src/styles/global.css` `@theme`. Prefer `container-reading`, `max-w-6xl` (when `--container-6xl` is defined), or `max-w-[48rem]`. A bare `max-w-3xl` with only a spacing scale ships a ~80px column.