@wix/agent-skills 1.7.0 → 1.8.0

package/skills/wix-headless/references/blog/BLOG_CONTENT.md

@@ -120,9 +120,8 @@ Use these node types to build rich, varied content:
 - LIST_ITEM nodes contain PARAGRAPH nodes (not TEXT directly)
 - Mix at least 3 different node types per post for visual variety
 - Create all 3 posts in sequence (one `curl` call per post)
-- **Best practice:** include all fields (title, content, media) in the initial creation call to avoid needing a re-publish
 
-> **Re-publish after PATCH:** If you update a published post (e.g., adding a cover image via PATCH after creation), it becomes `hasUnpublishedChanges: true`. You must call `POST /blog/v3/draft-posts/{draftPostId}/publish` to re-publish. To avoid this, include media in the initial creation call.
+> **Re-publish after PATCH:** If you update a published post (e.g., the image agent adds a cover image via PATCH after creation), it becomes `hasUnpublishedChanges: true`. The agent that PATCHes must call `POST /blog/v3/draft-posts/{draftPostId}/publish` to re-publish. (This seed scope does not attach media — see Step 3.)
 
 ## Step 4: Verify
 
@@ -139,13 +138,24 @@ body: {
 
 Confirm 3 posts are returned. Report post titles to the user.
 
-### Step 5: Log Results
+## Step 5: Return Results
 
-Write a sidecar file at `.wix/logs/blog-data.md` (see `../../shared/LIFECYCLE_LOG.md` for the sidecar contract). Do **not** append to `.wix/lifecycle.log.md` directly — the orchestrator concatenates all sidecars at the end. Use a `####` heading so the entry nests under `### features-orchestrator` in the assembled log:
+Emit a structured JSON block at the end of your completion message per `../shared/RETURN_CONTRACT.md`. Do **not** write a sidecar file. Include the created posts' `id` and `title` so the image agent can attach cover images by ID:
 
-```markdown
-## blog
-- Status: complete
-- Content: {n} posts published ({post titles})
-- Images: {generated (n/n attached) | skipped (user declined) | not attempted}
+```json
+{
+  "status": "complete",
+  "phase": "blog-seed",
+  "scope": "seed",
+  "summary": "Created and published {n} on-brand blog posts",
+  "data": {
+    "blogPosts": [
+      { "id": "<uuid>", "title": "<title>" }
+    ]
+  },
+  "files": [],
+  "errors": []
+}
 ```
+
+The JSON block MUST be the last content in your message.

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

@@ -5,7 +5,7 @@ description: "Implements blog vertical via Wix Blog app — @wix/blog SDK, @wix/
 
 # Blog 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
 
@@ -13,13 +13,13 @@ Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routi
 |-------|-------|-----------|
 | `seed` | Seed (post seeding via REST with Ricos content) | `./BLOG_CONTENT.md` |
 | `components` | Components (blog service module, RicosViewer, consts, astro.config sitemap) | `../astro/blog/BLOG_SETUP.md` |
-| `pages` | Pages (listing, detail, RSS, BlogPost layout, home contribution) | `../astro/blog/BLOG_PAGES.md` |
+| `pages` | Pages (listing, detail, RSS, BlogPost layout — all under `src/pages/blog/*`; no shared-shell patch, so blog merges into one private build agent) | `../astro/blog/BLOG_PAGES.md` |
 
 Cover images are generated by the shared image agent (`image-phase-2-entity` scope) AFTER `seed` completes — not by this agent.
 
 ## Files this vertical creates / contributes
 
-See `<SKILL_ROOT>/references/verticals/blog.md` frontmatter.
+The `components` and `pages` scopes enumerate their own file lists — see `../astro/blog/BLOG_SETUP.md` (components) and `../astro/blog/BLOG_PAGES.md` (pages).
 
 ## Blog-specific failure modes
 

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

@@ -0,0 +1,106 @@
+---
+name: bookings-implementer
+description: "Implements Wix Bookings vertical — services catalog, service detail with availability calendar and booking flow, and booking confirmation. 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, site.json read pattern, return contract, style conventions, and common failure modes.
+
+## Scope routing
+
+| Scope | Phase | Reference |
+|-------|-------|-----------|
+| `seed` | Seed (service creation via Wix Bookings REST API) | `./SERVICES_DATA.md` |
+| `components` | Components: `ServiceCard.astro`, `AvailabilityCalendar.tsx`, `BookingForm.tsx`, `ServiceBookingFlow.tsx`, `ManageBooking.tsx` (`SeoTags.astro` is pre-copied — see Templates) | `../astro/bookings/COMPONENTS.md` |
+| `pages` | Pages: `/services` listing, `/services/[slug]` detail, `/booking-confirmation`, `/manage-booking` | `../astro/bookings/SERVICES_PAGES.md` |
+
+## Files this vertical creates / contributes
+
+See `<SKILL_ROOT>/references/verticals/bookings.md` frontmatter.
+
+## Pre-return file-existence assertion (pages scope)
+
+Before returning `status: "complete"` from the `pages` scope, verify all route files exist on disk:
+- `src/pages/services/index.astro`
+- `src/pages/services/[slug].astro`
+- `src/pages/booking-confirmation.astro`
+- `src/pages/manage-booking.astro`
+
+If any declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]` rather than claiming success.
+
+## Templates
+
+Canonical templates live at `<SKILL_ROOT>/references/astro/templates/bookings/`. Your `components` and `pages` scopes **read these and adapt them — don't invent markup or SDK wiring** (the booking/confirm/availability/waitlist wiring is subtle and was verified against a live site; re-authoring from scratch is a common source of API-shape bugs). Adapt brand copy, headings, and styling; keep the SDK calls and the data flow.
+
+Components (`components` scope — `.tsx`/`.astro`, no CSS):
+- `…/templates/bookings/ServiceCard.astro`
+- `…/templates/bookings/AvailabilityCalendar.tsx` — branches on `serviceType` (APPOINTMENT → `availabilityTimeSlots`, CLASS → `eventTimeSlots`); capacity + instructor + full→waitlist
+- `…/templates/bookings/BookingForm.tsx` — `createBooking` → `/api/confirm-booking`; party size; waitlist on full
+- `…/templates/bookings/ServiceBookingFlow.tsx` — coordinator (threads `serviceType`)
+- `…/templates/bookings/ManageBooking.tsx` — cancel via anonymous token (used by `manage-booking.astro`)
+
+Pages (`pages` scope):
+- `…/templates/bookings/services/index.astro`, `…/services/[slug].astro`
+- `…/templates/bookings/booking-confirmation.astro`, `…/manage-booking.astro`
+
+### Pre-copied by the orchestrator (do NOT write these yourself)
+These are mechanical (no brand content) — the orchestrator copies them before dispatch (BUILD-astro.md § Step 4.5). Just rely on them at the listed paths:
+- `src/styles/components-bookings.css` ← `…/templates/bookings/components-bookings.css`
+- `src/components/SeoTags.astro` ← `…/templates/bookings/SeoTags.astro` (renders `service.seoData.tags`; imported by `services/[slug].astro`)
+- `src/pages/api/confirm-booking.ts` ← `…/templates/bookings/api/confirm-booking.ts` (elevated `confirmBooking` — holds the seat)
+- `src/pages/api/waitlist.ts` ← `…/templates/bookings/api/waitlist.ts` (elevated native v1 waitlist register)
+
+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.
+
+## CSS ownership — bookings pack
+
+Bookings-specific component CSS lives in `src/styles/components-bookings.css` (pre-copied by the orchestrator from the skill template — see above), NOT in the designer's `global.css`. Classes the pack owns:
+
+- `.service-card`, `.service-card-image`, `.service-card-meta`, `.service-card-price` — the service card itself, including image containment, price badge, and duration tag.
+- `.service-grid` — the layout that lists service cards on `/services`. Include `display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: var(--spacing-xl);` plus View-Transitions opacity fade.
+- `.availability-calendar` — the date-picker shell wrapping the calendar widget.
+- `.time-slot`, `.time-slot--available`, `.time-slot--selected`, `.time-slot--full` (full CLASS session → waitlist), plus the `.time-slot-time` / `.time-slot-capacity` spans inside each slot button.
+- `.booking-form` (+ `.booking-form-note`) — the booking/waitlist form revealed after a slot is selected.
+- `.manage-booking`, `.manage-booking-summary`, `.manage-booking-status`, `.manage-booking-note`, `.manage-booking-link` — the `/manage-booking` view/cancel UI.
+
+If `global.css` ships a partial rule for any class above, flag it in your return JSON's `errors` array (`{code: "GLOBAL_CSS_LEAK", class: "<name>"}`) and override with the complete rule in `components-bookings.css`.
+
+## Bookings-specific failure modes
+
+| Wrong | Right |
+|-------|-------|
+| Treat `createBooking` as the whole booking — stop after it returns | `createBooking` leaves the booking **`CREATED`**, which **does not hold a seat or block availability** (per the [lifecycle docs](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/introduction): only `CONFIRMED` blocks availability). Without a follow-up **`confirmBooking`**, the class overbooks and capacity never drops. After createBooking returns `CREATED`, call `bookings.confirmBooking(bookingId, revision, { paymentStatus: "NOT_PAID", flowControlSettings: { checkAvailabilityValidation: true } })`. `confirmBooking` needs Manage Bookings → run it **server-side, elevated** (`auth.elevate`), not from the visitor client. |
+| Build the waitlist on `createBooking` (expecting a `WAITING_LIST` status) | `createBooking` has **no** waitlist option (verified: only `participantNotification`/`sendSmsReminder`); a full session returns `SESSION_CAPACITY_EXCEEDED`. The native waitlist is the **legacy v1** API `POST /bookings/v1/waitlist/register` (there is no v2/v3 waitlist). It needs the **v1-encoded session id** as `waitingResource` (surfaced in the `SESSION_CAPACITY_EXCEEDED` message: *"…on session `<id>`"*) **+ a Wix `contactId`** (resolve via Contacts API by email, create if missing), and the **Manage Bookings** scope → server-side elevated. Class/EVENT only. |
+| Call the v1 waitlist (or any Manage-Bookings REST) with `auth.elevate(async () => fetchWithAuth(...))` | `auth.elevate()` only grants permissions for a real **SDK function** (it reads the method's required-permission metadata); a plain closure isn't one, so it runs **un-elevated (visitor)** and 403s. For raw REST with no SDK wrapper, elevate the authenticated fetch itself: `const ef = auth.elevate(httpClient.fetchWithAuth); await ef(url, init)`. (For calls that *do* have an SDK method — `confirmBooking`, `getAnonymousActionToken` — elevate the method directly.) |
+| Pass the v3 `eventId` as the waitlist `waitingResource` | The v1 waitlist can't decode a v3 GUID (`"id … cannot be decoded"`). Use the **v1-encoded session id** (e.g. `2mmoW0vw…`) from the `SESSION_CAPACITY_EXCEEDED` message. |
+| Use Services V1 API endpoint (`/bookings/v1/catalog/services`) | Services V2 is at `POST https://www.wixapis.com/_api/bookings/v2/services`. V1 has a different (nested `info.*`) payload shape. |
+| Nest service fields under `info` (`info.name`, `info.description`) | V2 uses flat fields: `name`, `description`, `tagLine` at the top level of the `service` object. |
+| Use `payment.fixed.price.amount` | V2 uses `payment.fixed.price.value` (a string like `"75.00"`). `amount` is the V1 field name. |
+| Omit `defaultCapacity` when creating a service | Required in V2. Set to `1` for APPOINTMENT; use participant count for CLASS. |
+| Omit `onlineBooking` when creating a service | Required in V2. At minimum `{ "enabled": true }`. |
+| Omit `sessionDurations` for an APPOINTMENT service | Required for APPOINTMENT: `schedule.availabilityConstraints.sessionDurations: [<minutes as int>]`. Do NOT specify for CLASS. |
+| Use `availability.queryAvailability` or `availability` SDK namespace | Branch by service type: APPOINTMENT → `availabilityTimeSlots.listAvailabilityTimeSlots()`; CLASS → **`eventTimeSlots.listEventTimeSlots()`** (a **different namespace** — `eventTimeSlots`, not `availabilityTimeSlots` — with plural `serviceIds` + `includeNonBookable`). The `availability` namespace does not exist in `@wix/bookings`. |
+| Pass UTC ISO strings to `listAvailabilityTimeSlots` | The method expects **local date strings** in `YYYY-MM-DDTHH:mm:ss` format (no `Z`), with a separate `timeZone` parameter. |
+| Read service slug from `service.slug` | V2 response puts slug at `service.mainSlug.name`. Fall back to `service.supportedSlugs[0].name`, then `service.id`. |
+| Call `queryServices({ query: { filter, paging } })` (object form) | In `@wix/bookings` the object form returns **0 items with no error**. Use the **query builder**: `await services.queryServices().limit(100).find()` → `result.items`. For a slug, fetch the (small) catalog and match `mainSlug.name` in JS, or `.eq("mainSlug.name", slug).find()`. |
+| Build a `createClient`/`OAuthStrategy` in `.astro` SSR frontmatter keyed off `import.meta.env.*_WIX_CLIENT_ID` | The `*_WIX_CLIENT_ID` env vars are client-only in `@wix/astro` and `undefined` at server render → `createClient` throws → HTTP 500 (only in the deployed runtime; dev has `.env.local`). SSR reads use `@wix/essentials` `auth.elevate(services.queryServices)()…` — the same ambient pattern as the CMS pages. |
+| Read the client ID in a browser island via `import.meta.env.*_WIX_CLIENT_ID` | Client islands import `{ WIX_CLIENT_ID } from "astro:env/client"`. `import.meta.env` is `undefined` in the browser bundle → `OAuthStrategy` sends an empty `client_id` → `oauth2/token` `400`. The var name is `WIX_CLIENT_ID` (no `PUBLIC_`). |
+| Read service name from `service.info.name` | V2 uses flat `service.name` (not `service.info.name`). Same for `description` and `tagLine`. |
+| Read duration from `service.schedule.sessions.duration` | V2 puts duration at `service.schedule.availabilityConstraints.sessionDurations[0]` (array of ints). |
+| Read media URL from `service.info.images[0].url` | V2 media: `service.media.mainMedia.image.url`. |
+| Use `import { availability } from '@wix/bookings'` | Use `import { availabilityTimeSlots } from '@wix/bookings'`. |
+| Call `availability.queryAvailability` server-side on every render | Availability is real-time and session-specific — always call from the client-side React island, NOT from `.astro` frontmatter SSR. |
+| Create a booking without `totalParticipants` | `createBooking` requires `totalParticipants: 1` (or `participantsChoices`). |
+| Read booking ID from `result.booking.id` | The booking ID field is `result.booking._id` (underscore prefix). |
+| Redirect to `/thank-you` (ecom route) after booking | Redirect to `/booking-confirmation?bookingId=<_id>`. The ecom thank-you page is unrelated to bookings. |
+| Re-fetch the booking with `getBooking` from the confirmation page | Don't. Pass booking details (bookingId, startDate, service name) as URL query params during the client-side redirect after `createBooking` succeeds, and render from those. (A server re-fetch of someone else's booking is out of scope.) NB: this is **not** because `auth.elevate` is unavailable — see next row. |
+| Assume `@wix/essentials` `auth.elevate` doesn't work in headless | It does. **Two different `elevate`s:** `@wix/essentials` `auth.elevate(fn)` works in `@wix/astro` SSR (it's how the listing/detail/CMS pages read data) — use it. What's unavailable is the **`wixClient.auth.elevate`** instance method on a hand-built `createClient({auth: OAuthStrategy})` (a Velo/Blocks API). Don't conflate them. |
+| Mount `AvailabilityCalendar` without `client:only="react"` | Calendar must be fully client-side — SSR renders before timezone is known and breaks slot display. Always use `client:only="react"`. |
+| Omit try/catch on `createBooking` | Booking creation can fail with 409 (slot taken) between slot fetch and submit. Catch and surface a friendly message; do not crash the page. |
+| Use `service.id` to pass the service ID | The Wix SDK uses `_id` (with underscore) for all entity IDs. The service's ID is `service._id`. Using `service.id` will be `undefined`. |
+| Read `resource._id` from `listAvailabilityTimeSlots` response | `availableResources` is EMPTY by default in list results. Omit `resource` from `createBooking` — Wix auto-assigns a resource during confirmation. |
+| Use `timeSlot.slot.startDate` to read slot time | Slot fields are at the TOP LEVEL — there is no nested `slot` on the list response. APPOINTMENT slots: `timeSlot.localStartDate`, `timeSlot.localEndDate`, `timeSlot.scheduleId`. |
+| Treat CLASS (event) slots like APPOINTMENT slots — guard clicks on `scheduleId`, book with `{scheduleId, startDate}` | CLASS event slots carry their session id at **`timeSlot.eventInfo.eventId`** and have **no `scheduleId`** (and no top-level `startDate`). Guarding the slot-click on `scheduleId` drops every CLASS click; the appointment-shaped `createBooking` payload doesn't apply. For CLASS: guard on `eventId`, and book with `bookedEntity.slot = { serviceId, eventId }` (Wix derives start/end/timezone/resource/location from the event). Keep `{ scheduleId, startDate, endDate, timezone, location }` for APPOINTMENT only. |
+| Pass `hidden: true` services to the listing | Always filter with `{ hidden: false }` in your `queryServices` filter to exclude hidden services from the public listing. |
+| Use `../../../` for imports in `[slug].astro` | `src/pages/services/[slug].astro` is two directories deep inside `src/`. Import Layout and components with `../../layouts/Layout.astro` and `../../components/…` — not three `../` which would escape `src/`. |

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.

package/skills/wix-headless/references/commands/known-apps.json

@@ -1,5 +1,6 @@
 {
   "wix-stores": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
   "wix-forms": "225dd912-7dea-4738-8688-4b8c6955ffc2",
-  "wix-blog": "14bcded7-0066-7c35-14d7-466cb3f09103"
+  "wix-blog": "14bcded7-0066-7c35-14d7-466cb3f09103",
+  "wix-gift-cards": "d80111c5-a0f4-47a8-b63a-65b54d774a27"
 }