@wix/agent-skills 1.9.0 → 1.10.0

package/skills/wix-headless/references/astro/templates/global.css

@@ -10,10 +10,12 @@
 
 @theme {
   /* {{theme}} — Composer substitutes the full palette here from designTokens:
-     every --color-*, --font-*, --spacing-* (2xs..4xl), --container-*, and
-     --radius-* line. The required-token set (enforced by compose.mjs)
-     MUST all be present, or components render unstyled. Container scale is
-     separate from spacing — never alias --container-3xl to --spacing-3xl. */
+     every --color-*, --font-*, --container-*, and --radius-* line. The
+     required-token set (enforced by compose.mjs) MUST all be present, or
+     components render unstyled. Spacing is NOT a token here — it uses
+     Tailwind's built-in numeric scale (gap-4, py-24, …); never add a named
+     --spacing-* scale, since that namespace also powers the width utilities
+     (max-w-*/w-*) and would shadow them. */
 }
 
 /* Reading-width helper so prose pages center without guessing Tailwind sizes. */
@@ -25,7 +27,7 @@
 /* Shared button primitive — declared with @utility so the variants below can
    @apply it (a plain contract class is NOT @apply-able in Tailwind v4). */
 @utility btn {
-  @apply inline-flex items-center justify-center px-lg py-md rounded-md font-medium;
+  @apply inline-flex items-center justify-center px-6 py-4 rounded-md font-medium;
   transition: background-color 200ms ease, color 200ms ease, border-color 200ms ease;
 }
 
@@ -130,7 +132,7 @@
   height: 1px;
   background: var(--color-accent);
   opacity: 0.6;
-  margin-block: var(--spacing-lg);
+  margin-block: 1.5rem;
 }
 
 /* ── Universal site chrome ────────────────────────────────────────────────── */
@@ -204,8 +206,8 @@ body[data-navigating="true"] .product-grid {
   min-width: 12rem;
   display: flex;
   flex-direction: column;
-  gap: var(--spacing-2xs);
-  padding: var(--spacing-sm);
+  gap: 0.25rem;
+  padding: 0.75rem;
   background: var(--color-paper);
   border: 1px solid var(--color-rule);
   border-radius: var(--radius-md);
@@ -223,7 +225,7 @@ body[data-navigating="true"] .product-grid {
 .site-nav-sublink {
   font-size: 0.875rem;
   color: var(--color-ink-soft, var(--color-mute));
-  padding-block: var(--spacing-2xs);
+  padding-block: 0.25rem;
 }
 .site-nav-sublink:hover,
 .site-nav-sublink[aria-current="page"] {
@@ -237,13 +239,13 @@ body[data-navigating="true"] .product-grid {
 .category-rail-inner {
   display: flex;
   flex-wrap: wrap;
-  gap: var(--spacing-sm);
-  padding-block: var(--spacing-md);
+  gap: 0.75rem;
+  padding-block: 1rem;
 }
 .category-pill {
   display: inline-flex;
   align-items: center;
-  padding: var(--spacing-2xs) var(--spacing-md);
+  padding: 0.25rem 1rem;
   border: 1px solid var(--color-rule);
   border-radius: var(--radius-sm);
   font-size: 0.8125rem;
@@ -262,12 +264,12 @@ body[data-navigating="true"] .product-grid {
   border-color: var(--color-ink);
 }
 .pagination {
-  margin-block: var(--spacing-xl);
+  margin-block: 2rem;
 }
 .pagination-inner {
   display: flex;
   justify-content: space-between;
-  gap: var(--spacing-md);
+  gap: 1rem;
 }
 .pagination-link {
   color: var(--color-ink);
@@ -282,5 +284,5 @@ body[data-navigating="true"] .product-grid {
 .breadcrumbs {
   font-size: 0.8125rem;
   color: var(--color-mute);
-  margin-bottom: var(--spacing-sm);
+  margin-bottom: 0.75rem;
 }

package/skills/wix-headless/references/astro/templates/index.astro

@@ -17,8 +17,8 @@ import Layout from '../layouts/Layout.astro';
 ---
 <Layout>
   <section class="relative">
-    <div class="max-w-6xl mx-auto px-lg py-4xl grid grid-cols-1 md:grid-cols-2 gap-3xl items-center">
-      <div class="flex flex-col gap-lg">
+    <div class="max-w-6xl mx-auto px-6 py-24 grid grid-cols-1 md:grid-cols-2 gap-16 items-center">
+      <div class="flex flex-col gap-6">
         <h1 class="font-display text-4xl md:text-5xl leading-tight">{{shell.heroHeadline}}</h1>
         <p class="text-lg text-mute max-w-prose">{{shell.heroSub}}</p>
       </div>
@@ -34,7 +34,7 @@ import Layout from '../layouts/Layout.astro';
 
   {{home-markers}}
 
-  <section class="max-w-6xl mx-auto px-lg py-4xl grid grid-cols-1 md:grid-cols-2 gap-3xl items-center">
+  <section class="max-w-6xl mx-auto px-6 py-24 grid grid-cols-1 md:grid-cols-2 gap-16 items-center">
     <div
       class="about-image rounded-md order-last md:order-first"
       data-decorative-slot="about"
@@ -42,7 +42,7 @@ import Layout from '../layouts/Layout.astro';
     >
       <!-- orchestrator injects <img src={decorativeImages.about} …> here -->
     </div>
-    <div class="flex flex-col gap-md max-w-prose">
+    <div class="flex flex-col gap-4 max-w-prose">
       <hr class="editorial-rule w-16 ml-0" />
       <h2 class="font-display text-3xl leading-tight">The story behind {{brand.name}}</h2>
       <p class="text-ink leading-relaxed">

package/skills/wix-headless/references/astro/templates/stores/components-stores.css

@@ -28,7 +28,7 @@
 .product-grid {
   display: grid;
   grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
-  gap: var(--spacing-xl);
+  gap: 2rem;
   transition: opacity 200ms ease;
 }
 body[data-navigating="true"] .product-grid {
@@ -40,8 +40,8 @@ body[data-navigating="true"] .product-grid {
   position: relative;
   display: flex;
   flex-direction: column;
-  gap: var(--spacing-md);
-  padding-bottom: var(--spacing-md);
+  gap: 1rem;
+  padding-bottom: 1rem;
   background: var(--color-paper, var(--color-cream));
   border-radius: var(--radius-xl);
   overflow: hidden;
@@ -59,7 +59,7 @@ body[data-navigating="true"] .product-grid {
 
 .product-card-media {
   position: relative;
-  margin: var(--spacing-md);
+  margin: 1rem;
   aspect-ratio: 4 / 5;
   background: var(--color-paper-warm, var(--color-cream));
   border-radius: var(--radius-md);
@@ -75,8 +75,8 @@ body[data-navigating="true"] .product-grid {
 .product-card-body {
   display: flex;
   flex-direction: column;
-  gap: var(--spacing-xs);
-  padding-inline: var(--spacing-md);
+  gap: 0.5rem;
+  padding-inline: 1rem;
 }
 .product-card-name {
   margin: 0;
@@ -95,8 +95,8 @@ body[data-navigating="true"] .product-grid {
 
 .product-card-ribbon {
   position: absolute;
-  top: var(--spacing-md);
-  left: var(--spacing-md);
+  top: 1rem;
+  left: 1rem;
   padding: 0.375rem 0.625rem;
   background: var(--color-accent);
   color: var(--color-ink);
@@ -110,8 +110,8 @@ body[data-navigating="true"] .product-grid {
 }
 .product-card-index {
   position: absolute;
-  top: var(--spacing-md);
-  right: var(--spacing-md);
+  top: 1rem;
+  right: 1rem;
   padding: 0.375rem 0.5rem;
   background: rgba(255, 255, 255, 0.85);
   color: var(--color-ink);
@@ -132,19 +132,19 @@ body[data-navigating="true"] .product-grid {
   background: var(--color-paper-warm, var(--color-cream));
   border: 1px solid var(--color-rule);
   border-left: 2px solid var(--color-accent);
-  padding: var(--spacing-lg);
+  padding: 1.5rem;
   border-radius: var(--radius-md);
   display: flex;
   flex-direction: column;
-  gap: var(--spacing-md);
+  gap: 1rem;
 }
 .offer-callout-item {
   display: flex;
   flex-direction: column;
-  gap: var(--spacing-xs);
+  gap: 0.5rem;
 }
 .offer-callout-item + .offer-callout-item {
-  padding-top: var(--spacing-md);
+  padding-top: 1rem;
   border-top: 1px solid var(--color-rule);
 }
 .offer-callout-badge {
@@ -190,7 +190,7 @@ body[data-navigating="true"] .product-grid {
    of this template used `@apply font-heading text-bark/70 bg-parchment …`,
    which assumed a different token vocabulary than current designer output
    (`paper`/`ink`/`font-display` …) and built-failed on every run that loaded
-   it. Direct `var(--color-paper)` / `var(--spacing-sm)` calls work against
+   it. Direct `var(--color-paper)` / `0.75rem` calls work against
    any designer-published token set as long as the core scales exist (they
    always do). Use fallback chains (`var(--color-paper-warm, var(--color-cream))`)
    when a token is sometimes-published.
@@ -200,8 +200,8 @@ body[data-navigating="true"] .product-grid {
 .option-group {
   display: flex;
   flex-direction: column;
-  gap: var(--spacing-sm);
-  margin-bottom: var(--spacing-lg);
+  gap: 0.75rem;
+  margin-bottom: 1.5rem;
 }
 .option-label {
   font-family: var(--font-display);
@@ -213,10 +213,10 @@ body[data-navigating="true"] .product-grid {
 .option-choices {
   display: flex;
   flex-wrap: wrap;
-  gap: var(--spacing-sm);
+  gap: 0.75rem;
 }
 .option-pill {
-  padding: var(--spacing-sm) var(--spacing-md);
+  padding: 0.75rem 1rem;
   border: 1px solid var(--color-ink);
   background: transparent;
   color: var(--color-ink);
@@ -255,14 +255,14 @@ body[data-navigating="true"] .product-grid {
   cursor: not-allowed;
 }
 .quantity-value {
-  padding: var(--spacing-sm) var(--spacing-md);
+  padding: 0.75rem 1rem;
   font-variant-numeric: tabular-nums;
 }
 
 /* --- Modifier free-text input (ProductPurchase.tsx, FREE_TEXT render type) --- */
 .modifier-text {
   width: 100%;
-  padding: var(--spacing-sm);
+  padding: 0.75rem;
   font-family: var(--font-body);
   font-size: 0.875rem;
   border: 1px solid var(--color-rule);
@@ -290,9 +290,9 @@ body[data-navigating="true"] .product-grid {
 .back-in-stock-form {
   display: flex;
   flex-direction: column;
-  gap: var(--spacing-md);
-  margin-top: var(--spacing-md);
-  padding: var(--spacing-lg);
+  gap: 1rem;
+  margin-top: 1rem;
+  padding: 1.5rem;
   border: 1px solid var(--color-rule);
   border-radius: var(--radius-md);
   background: var(--color-paper, var(--color-cream));
@@ -300,7 +300,7 @@ body[data-navigating="true"] .product-grid {
 .back-in-stock-headline {
   display: flex;
   flex-direction: column;
-  gap: var(--spacing-sm);
+  gap: 0.75rem;
 }
 .back-in-stock-eyebrow {
   font-family: var(--font-display);
@@ -326,11 +326,11 @@ body[data-navigating="true"] .product-grid {
   display: flex;
   flex-direction: row;
   flex-wrap: wrap;
-  gap: var(--spacing-sm);
+  gap: 0.75rem;
 }
 .back-in-stock-input {
   flex: 1;
-  padding: var(--spacing-sm) var(--spacing-md);
+  padding: 0.75rem 1rem;
   font-family: var(--font-body);
   font-size: 0.875rem;
   border: 1px solid var(--color-rule);
@@ -345,7 +345,7 @@ body[data-navigating="true"] .product-grid {
   border-color: var(--color-ink);
 }
 .back-in-stock-submit {
-  padding: var(--spacing-sm) var(--spacing-lg);
+  padding: 0.75rem 1.5rem;
   font-family: var(--font-display);
   font-size: 0.75rem;
   text-transform: uppercase;
@@ -370,8 +370,8 @@ body[data-navigating="true"] .product-grid {
   color: var(--color-error, var(--color-accent));
 }
 .back-in-stock-success {
-  margin-top: var(--spacing-md);
-  padding: var(--spacing-lg);
+  margin-top: 1rem;
+  padding: 1.5rem;
   border: 1px solid var(--color-rule);
   border-radius: var(--radius-md);
   background: var(--color-paper, var(--color-cream));
@@ -390,7 +390,7 @@ body[data-navigating="true"] .product-grid {
   margin: 0;
 }
 .stock-status.back-in-stock-alt {
-  margin-top: var(--spacing-sm);
+  margin-top: 0.75rem;
   font-family: var(--font-body);
   font-size: 0.875rem;
   font-style: italic;

package/skills/wix-headless/references/astro/templates/stores/products/[slug].astro

@@ -89,14 +89,14 @@ const viewContentPayload = {
   hasSeoTags={hasSeoTags}
 >
   {hasSeoTags && <SeoTags slot="head" tags={seoTags} />}
-  <main class="py-3xl">
-    <div class="max-w-wide mx-auto px-xl">
+  <main class="py-16">
+    <div class="max-w-wide mx-auto px-8">
       <a href="/products" class="text-mute text-sm tracking-wide uppercase">&larr; Back to products</a>
-      <div class="grid grid-cols-1 md:grid-cols-[7fr_5fr] gap-2xl md:gap-4xl mt-xl items-start">
+      <div class="grid grid-cols-1 md:grid-cols-[7fr_5fr] gap-12 md:gap-24 mt-8 items-start">
         <div class="aspect-[4/5] bg-cream rounded-sm overflow-hidden">
           {imageUrl && <img src={imageUrl} alt={product.name ?? "Product"} class="w-full h-full object-cover" />}
         </div>
-        <div class="flex flex-col gap-lg md:sticky md:top-2xl">
+        <div class="flex flex-col gap-6 md:sticky md:top-12">
           <h1 class="font-display text-4xl leading-tight">{product.name}</h1>
           {price && <p class="text-xl text-ink-soft">{price}</p>}
           {description && <p class="text-ink-soft leading-relaxed">{description}</p>}

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

@@ -13,27 +13,32 @@ 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.
+The flow covers **appointments and classes**. APPOINTMENT and CLASS share the
+same booking sequence; they differ only in the availability call (`availabilityTimeSlots`
+vs `eventTimeSlots`, noted inline). **Courses and add-ons are out of scope.**
 
 ---
 
 ## 1. The step model
 
-A single customer journey, five steps, holding one shared selection:
+A single customer journey, holding one shared selection. The catalog optionally
+filters by **location** and **category**; the slots step optionally filters by
+**staff**. All three auto-skip when there's nothing to choose (≤1 location, ≤1
+category, ≤1 staff), so a plain single-location single-staff site sees the simple
+five-step path:
 
 ```
-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
+0. Location   (optional) pick a location — only shown when the site has >1 locations → scopes the catalog + availability
+1. Catalog    list bookable services (optionally filtered by location/category) → pick a service
+2. Slots      availability calendar (optionally filtered by staff)               → 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 location/category filters and the staff picker are covered in §§7–8.
+
 **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.
@@ -49,8 +54,8 @@ for SEO and run slots + form + book in a `client:only` island.
 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? }`.
+- **`service`** — the chosen service object (the booking step reads `service.payment` + `service.bookingPolicy`; the slots step reads `service.staffMemberDetails.staffMembers` for the staff picker — §8).
+- **`slot`** — `{ serviceType, serviceId, localStartDate, localEndDate, timezone, scheduleId?, eventId?, locationId?, locationType?, resource? }`. `resource = { _id, name }` is set only when a specific staff was chosen (§8); otherwise the driver emits the ANY_RESOURCE fallback. `locationId`/`locationType` come from the slot's own `location` (the booking books at that location).
 - **`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
@@ -89,11 +94,12 @@ Key facts the driver encodes (do not deviate):
   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" }]`
+- **ANY_RESOURCE fallback (staff)** — when no staff is chosen (the default, and on
+  single-staff services), `createBooking` sends
+  `resourceSelections:[{ resourceTypeId:"1cd44cf8-756f-41c3-bd90-3e2ffcaf1155", 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.)
+  `availableResources:[]` yet book fine this way). A specific staff choice sets
+  `slot.resource` instead (§8).
 - **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`
@@ -106,9 +112,11 @@ Key facts the driver encodes (do not deviate):
 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():
+// Catalog (list) — the filter MUST include appId; pass conditionalFields, then .find().
+// Merge the optional category/location filters into the SAME filter object (§7):
 services.queryServices({
-  query: { filter: { appId: BOOKING_APP_ID }, paging: { limit: 100 } },
+  query: { filter: { appId: BOOKING_APP_ID /* , "category.id": { $eq: catId },
+                       "locations.business.id": { $hasSome: [locId] } */ }, paging: { limit: 100 } },
   conditionalFields: ["STAFF_MEMBER_DETAILS"],
 }).find();                                   // → result.items ; filter out s.hidden
 
@@ -116,13 +124,21 @@ services.queryServices({
 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:
+// Availability (APPOINTMENT) — serviceId is a single GUID STRING. The staff (§8)
+// and location filters are OPTIONAL params on the same call:
 availabilityTimeSlots.listAvailabilityTimeSlots({
   serviceId, fromLocalDate, toLocalDate, timeZone, bookable: true, cursorPaging: { limit: 100 },
+  // staff:    resourceTypes: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, resourceIds: [staffResourceId] }],
+  //           includeResourceTypeIds: [STAFF_MEMBER_RESOURCE_TYPE_ID],
+  // location: locations: [{ _id: locationId, locationType: "BUSINESS" }],
 });                                          // 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 });
+// Availability (CLASS) — different namespace, PLURAL serviceIds; slots carry eventInfo.eventId, no scheduleId.
+// CLASS filters staff + location via eventFilter instead:
+eventTimeSlots.listEventTimeSlots({
+  serviceIds: [serviceId], fromLocalDate, toLocalDate, timeZone, includeNonBookable: false,
+  // eventFilter: { "resources.id": { $hasSome: [staffResourceId] }, "location.id": [locationId] },
+});
 ```
 
 `fromLocalDate`/`toLocalDate` are **local** date strings `YYYY-MM-DDThh:mm:ss`
@@ -157,14 +173,16 @@ The booking form is a **`@wix/forms` form** attached to the service
 `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)
+## 5. The availability 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:
+**Group slots by day — don't render a flat list of every slot with time-only
+labels** (the visitor can't tell which day a slot is on; that flat grid was the
+original usability failure). The calendar **shape is your / the brand's choice** —
+week, month, or N-day. The reference example uses a **week view** (a 7-day strip
+with week navigation → the picked day's times); fetch availability for the visible
+window (`fromLocalDate`/`toLocalDate` = that window's bounds), group by calendar
+day, and offer a **"check next availability"** action that probes forward when the
+window is empty. Reference example:
 `../astro/templates/bookings/AvailabilityCalendar.tsx`.
 
 ## 6. Client identity (per framework)
@@ -178,8 +196,51 @@ The SDK calls are identical everywhere; only how you get the client differs:
   `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.
+## 7. Catalog filters — location & category (both auto-skip)
+
+Both filter the **catalog query** and re-render the list. The cleanest
+framework-agnostic shape is a re-query driven by a query param (`?locationId`,
+`?category`) — links/SSR on a static catalog, or a store/router on a SPA. **Show
+each filter only when there is more than one choice**, exactly as the SoT does.
+
+**Location** (the SoT is location-first; here it auto-skips ≤1 location):
+1. `services.queryLocations()` → `{ businessLocations: { locations: [{ _id, type, business: { name } }] }, customLocations: { exists }, customerLocations: { exists } }`.
+2. Count = `businessLocations.locations.length + (customLocations.exists ? 1 : 0) + (customerLocations.exists ? 1 : 0)`. **Show the selector only when count > 1.**
+3. The chosen location filters the catalog query:
+   - a real business id → `filter["locations.business.id"] = { $hasSome: [id] }`;
+   - the synthetic `"custom"` / `"customer"` → `filter["locations.type"] = { $hasSome: ["CUSTOM"|"CUSTOMER"] }` (the SoT's synthetic-id mapping).
+4. **Scope availability to exactly ONE location — always, on a multi-location service.** `listAvailabilityTimeSlots` returns **one slot per location** per time ("if `locations` is not specified, returns time slots for all locations where the service is available"), so an unscoped call on a 2-location service shows every time **twice**. Pass a single-element filter: APPOINTMENT → `locations: [{ _id, locationType: "BUSINESS" }]`; CLASS → `eventFilter: { "location.id": [id] }`. (Staff does **not** multiply rows — one slot carries many `availableResources`; only location does.) The slots step builds its location list from **`queryLocations()`** (the site's real business locations, whose ids the availability engine recognizes) **intersected with the service's own location ids** — not from `service.locations` alone, whose entries can carry an id the availability engine doesn't recognize (scoping to it returns zero slots). A **location picker** defaults to the catalog-carried location (or the first) and scopes the call when there's a real location to scope to; when the site has no business locations the list is empty and the call stays unscoped (one location → no duplicates). The booked slot carries its own `location`, so the booking books at that location (the driver maps it).
+
+**Category:**
+1. `categoriesV2.queryCategories().find()` → `result.items: [{ _id, name }]`. **Non-fatal** — if it fails, render the catalog without the bar.
+2. **Show the bar only when `items.length > 1`** (a fresh site has one default category).
+3. The chosen category filters the catalog query: `filter["category.id"] = { $eq: categoryId }`. A service carries its category at `service.category._id`.
+
+Reference example: `../astro/templates/bookings/services/index.astro` (both filters, link-driven, auto-skipping).
+
+## 8. Staff / resource selection (auto-skips ≤1 staff)
+
+A service carries its staff on the service object via the **`STAFF_MEMBER_DETAILS`
+conditional field** (already requested in the catalog/detail query):
+`service.staffMemberDetails.staffMembers: [{ staffMemberId, name }]`. The id used
+for filtering and booking is **`staffMemberId`** — which, **despite the name, IS the
+resource GUID** (it matches the service's `staffMemberIds` and the Staff Members API
+`resourceId`). Below, `resourceId` is that value.
+
+1. Show a "Any staff member / pick one" control above the calendar **only when
+   there is more than one staff**.
+2. Selecting a staff re-fetches availability filtered to that resource:
+   - APPOINTMENT → `resourceTypes: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, resourceIds: [resourceId] }]` (plus `includeResourceTypeIds: [STAFF_MEMBER_RESOURCE_TYPE_ID]`);
+   - CLASS → `eventFilter: { "resources.id": { $hasSome: [resourceId] } }`.
+3. When a slot is picked **with a specific staff selected**, set `slot.resource = { _id: resourceId, name }`. The driver books that resource. With **"any staff"**, leave `resource` unset — the driver emits the **ANY_RESOURCE fallback** and Wix auto-assigns a bookable resource (appointment slots can return `availableResources: []` yet book fine this way).
+
+`STAFF_MEMBER_RESOURCE_TYPE_ID = "1cd44cf8-756f-41c3-bd90-3e2ffcaf1155"` (exported from `bookingDriver.ts`). Reference example: `../astro/templates/bookings/AvailabilityCalendar.tsx` (the staff `<select>` + the filtered fetch).
+
+## 9. Out of scope
+
+Waitlist, on-site manage/cancel, payment/deposit breakdown, and multi-service /
+day-range are out of scope. (Waitlist and manage/cancel have **no headless SoT** —
+neither the components nor the vibe plugin implement join/cancel logic, only
+display-only policy flags — so they are deliberately not built here.) 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

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Implements the Wix Bookings vertical — services catalog (with optional location + category filters), a service detail page with a week-calendar availability picker (with optional staff selection), a schema-driven booking form, and confirmation, for appointments and classes. 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
@@ -82,9 +82,14 @@ Bookings-specific CSS lives in `src/styles/components-bookings.css` (pre-copied
 | 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. |
+| Dump every slot in one flat, time-only grid | **Group slots by day** — a flat time-only grid hides which day a slot is on. The calendar shape (week / month / N-day) is your choice; the example uses a week strip → the picked day's times. |
+| Read the staff id from `staffMember._id` / `.resourceId` on `staffMemberDetails.staffMembers` | The field is **`staffMemberId`** (on `service.staffMemberDetails.staffMembers[]`) — despite the name it IS the resource GUID (matches the service's `staffMemberIds`). Filter availability: APPOINTMENT `resourceTypes:[{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, resourceIds:[staffMemberId] }]`; CLASS `eventFilter:{ "resources.id": { $hasSome:[staffMemberId] } }`. Record the choice as `slot.resource = { _id: staffMemberId, name }`; leave it unset for "any staff" (ANY_RESOURCE fallback). Show the picker only when >1 staff. |
+| Always show the location selector / staff picker / category bar | **Auto-skip** each when there's nothing to choose: location count ≤1 (`businessLocations.length + custom?.exists + customer?.exists`), staff ≤1, categories ≤1. Single-location single-staff sites see the simple flow. |
+| Filter the catalog by a synthetic location id, or hardcode the location filter | Real business id → `filter["locations.business.id"] = { $hasSome:[id] }`; synthetic `"custom"`/`"customer"` → `filter["locations.type"] = { $hasSome:["CUSTOM"|"CUSTOMER"] }`. Carry the choice to the detail page so availability is scoped too. |
+| Call `listAvailabilityTimeSlots` **without** a `locations` filter on a multi-location service | It returns **one slot per location** per time → every time appears **N×** (duplicated rows). **Always scope availability to one business location** (`locations: [{ _id, locationType:"BUSINESS" }]`; CLASS: `eventFilter:{ "location.id":[id] }`). Build the calendar's location list from **`queryLocations()`** (the site's real business locations) intersected with the service's location ids — NOT from `service.locations` alone (its entries can carry an id the availability engine doesn't recognize → scoping to it returns 0 slots even though the service has availability). Default to the carried/first, picker when >1; no business locations → unscoped. Staff does **not** cause duplicates — one slot carries many `availableResources`; only location multiplies rows. |
+| Let a `queryCategories` failure break the catalog | Categories are **non-fatal** — wrap in try/catch and render the catalog without the bar. Category filter: `filter["category.id"] = { $eq: categoryId }`; a service's category is `service.category._id`. |
 | 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. |
+| Ship a payment/deposit breakdown, multi-service stacking, waitlist, or on-site manage/cancel | Out of scope. **Waitlist and manage/cancel have no headless SoT** (the components + vibe plugin expose only display-only policy flags — no join/cancel logic) — do not invent them on the REST/anonymous-token layer. Post-booking self-service is handled by the Wix-hosted flow / member area. |

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

@@ -93,6 +93,66 @@ curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "wix-site-id: <siteId>" -H
 
 ---
 
+## Step 3b — Create categories (OPTIONAL — only to surface the catalog category filter)
+
+A fresh Bookings install has **one** default category ("Our Services"), so the
+front-end's category filter bar stays hidden (it shows only when >1 category
+exists). Create extra categories **only when the build wants a category filter**
+(e.g. `intent.bookings.categories` is set, or several distinct service groups).
+Skip this step otherwise — it's not needed for a basic seed.
+
+```bash
+# Create a category. Returns { category: { id, ... } } — save the id.
+curl -sS -X POST \
+  -H "Authorization: Bearer $TOKEN" -H "wix-site-id: <siteId>" -H "Content-Type: application/json" \
+  -d '{ "category": { "name": "<Category name, e.g. Massage>" } }' \
+  "https://www.wixapis.com/bookings/v2/categories"
+```
+
+Then **assign each service to a category** by including `category` in the Step-4
+create payload: `"category": { "id": "<categoryId>" }`. (If a create rejects
+`category`, assign it after creation via Update Service — `PATCH
+/_api/bookings/v2/services/{id}` with `service.category.id` + the current
+`revision` — per the docs' "create a category and connect a service" flow.) A
+service can belong to **one** category. Distribute services across 2+ categories
+so the filter is meaningful.
+
+> The front-end reads categories via `categoriesV2.queryCategories().find()` and
+> filters services with `filter["category.id"] = { $eq: id }`. No category data →
+> no filter bar (graceful).
+
+---
+
+## Step 3c — Multiple business locations (OPTIONAL — only for a multi-location demo)
+
+The front-end's location selector auto-skips when the site has ≤1 location, so a
+single-location seed needs nothing here (and the booking flow is unaffected).
+Create a second business location **only** for a multi-location build
+(`intent.bookings.multiLocation`):
+
+```bash
+# Create a business location. Returns { location: { id, ... } }.
+curl -sS -X POST \
+  -H "Authorization: Bearer $TOKEN" -H "wix-site-id: <siteId>" -H "Content-Type: application/json" \
+  -d '{ "location": { "name": "<Branch name>", "status": "ACTIVE", "locationType": "BUSINESS",
+        "address": { "city": "<City>", "country": "<ISO country>" } } }' \
+  "https://www.wixapis.com/locations/v1/locations"
+```
+
+Then attach locations to each service's `locations` array on create (Step 4):
+`"locations": [ { "type": "BUSINESS", "business": { "id": "<locationId>" } }, … ]`.
+
+> **Caveat (verified-behavior limitation, not a bug):** filtering *availability*
+> by location also depends on each staff member's **working-hours location
+> coverage** (the `STAFF_WORKING_HOURS_LOCATIONS` setting). Seeding that reliably
+> is as fragile as custom working hours (see Step 3's warning), so for a seed,
+> create the location + attach it to services to exercise the **catalog** location
+> filter, and configure per-location staff hours from the Bookings dashboard if you
+> need per-location availability to differ. The selector + service filtering work
+> from the seed alone; per-location *slot* differences need the dashboard step.
+
+---
+
 ## Step 4 — Create services (Services V2 API)
 
 **Endpoint:** `POST https://www.wixapis.com/_api/bookings/v2/services`