@wix/agent-skills 1.8.0 → 1.10.0

package/skills/wix-headless/references/custom/bookings/WIRING.md

@@ -1,88 +1,197 @@
 ---
 name: custom-bookings-wiring
-description: "Integration-mode wiring subagent for the bookings capability. Wires a services list + availability + a book action into a brought-in site — @wix/bookings reads client-side via @wix/sdk, and a redirect to Wix-hosted bookings checkout for the booking itself (mirrors the ecom checkout-redirect pattern). No server runtime required."
+description: "Integration-mode wiring subagent for the bookings capability. Wires a services list + availability + a schema-driven booking form into a brought-in site, then books via the ecom Cart V2 sequence (createBooking → cart → placeOrder / hosted-checkout redirect). Client-side @wix/sdk; no server runtime, no confirmBooking."
 ---
 
-# Bookings — integration wiring
+# Bookings — integration wiring (own / static)
 
-You wire the **bookings capability** (services list + availability + book) into a brought-in site (`frontend = "custom"`). Client-side `@wix/sdk` — CDN imports for `none`-build, bundled imports for `own`-build (same calls). Read `INSTRUCTIONS.md` § "The technical spine" + § "Wiring discipline" first.
+You wire the **bookings capability** into a brought-in site (`frontend = "custom"`).
+Client-side `@wix/sdk` — CDN imports for `none`-build, bundled for `own`-build
+(same calls). Read `INSTRUCTIONS.md` § "The technical spine" + § "Wiring discipline".
 
-> **Scope.** Beta does **services display + availability + redirect-to-Wix-hosted bookings checkout**. The hosted checkout owns payment, the seat-holding confirm, and the customer email — exactly the pieces a client-only site cannot do itself: `confirmBooking` requires the Manage Bookings scope (server-side elevation), and a bare client `createBooking` leaves the booking **`CREATED`, which holds no seat** (the class/slot stays bookable → overbooking). Do NOT ship a client-side `createBooking` as a complete flow. An on-site booking flow (calendar + form + elevated confirm, as in the astro vertical) needs the server runtime — **deferred**.
+> **The logic is shared.** The step model, the booking SDK sequence, the
+> schema-driven form, and the gotchas are in `../../bookings/FLOW.md` — read it
+> first. The astro vertical's React examples
+> (`../../astro/templates/bookings/*` incl. `bookingDriver.ts`) are the reference
+> implementation; here you run the **same SDK calls** through an `OAuthStrategy`
+> visitor client (adapt the React idiom to whatever framework the site uses).
 
-## Inputs (inlined in your prompt)
+> **Scope (same as the astro vertical — the astro/own distinction collapses).**
+> Services display + a week-calendar availability picker + a schema-driven booking
+> form + the **ecom Cart V2 booking sequence**, all client-side under the visitor
+> identity (no server elevation): `createBooking` (→ `CREATED`) → `createCart` →
+> `calculateCart` → `isCheckoutRequired ? ecomCheckout redirect : placeOrder`.
+> **No `confirmBooking`** — the cart holds the seat, so a client-only site
+> completes the whole flow.
 
+## Inputs (inlined in your prompt)
 - **`appId`** — `OAuthStrategy` `clientId`.
-- **Seeded services** — read your `bookings` slice from `.wix/seeded.json` (`services[{id, slug, name, type, durationMinutes, price, currency}]`).
+- **Seeded services** — read your `bookings` slice from `.wix/seeded.json`.
 - The site's CSS token names (style additively from them).
 
-## Render services (wire an existing region, or inject a section)
-
-```html
-<script type="module">
-  import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk@1";
-  import { services } from "https://esm.sh/@wix/bookings@1";
-
-  const wix = createClient({ modules: { services }, auth: OAuthStrategy({ clientId: "REPLACE_WITH_APP_ID" }) });
-
-  // Query BUILDER + .find() — the { query: {...} } object form returns 0 items silently.
-  const { items } = await wix.services.queryServices().limit(100).find();
-  const visible = items.filter((s) => !s.hidden);
-  // Bind into the existing markup: name s.name, tagline s.tagLine, slug s.mainSlug?.name,
-  // duration s.schedule?.availabilityConstraints?.sessionDurations?.[0] (APPOINTMENT),
-  // price s.payment?.fixed?.price ({ value, currency } — value is a string; format from
-  // the returned currency, the site business locale wins over what was seeded).
-</script>
+## The client (acquire once)
+```js
+import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk@1"; // bundled for own-build
+import { services, availabilityTimeSlots, eventTimeSlots, bookings, categoriesV2 } from "https://esm.sh/@wix/bookings@1";
+import { forms } from "https://esm.sh/@wix/forms@1";
+import * as cartV2 from "https://esm.sh/@wix/auto_sdk_ecom_cart-v-2@1";
+import { redirects } from "https://esm.sh/@wix/redirects@1";
+
+const wix = createClient({
+  modules: { services, availabilityTimeSlots, eventTimeSlots, bookings, categoriesV2, forms, redirects, ...cartV2 },
+  auth: OAuthStrategy({ clientId: "REPLACE_WITH_APP_ID" }),
+});
 ```
+(`categoriesV2` + `services.queryLocations` power the optional catalog filters; drop them if you don't surface filters.)
 
-## Availability (per selected service)
+## Render services
+```js
+// The filter MUST include appId; pass conditionalFields, then .find().
+const BOOKING_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+const { items } = await wix.services.queryServices({
+  query: { filter: { appId: BOOKING_APP_ID }, paging: { limit: 100 } },
+  conditionalFields: ["STAFF_MEMBER_DETAILS"],
+}).find();
+const visible = items.filter((s) => !s.hidden);
+// name s.name · tagline s.tagLine · slug s.mainSlug?.name ·
+// duration s.schedule?.availabilityConstraints?.sessionDurations?.[0] ·
+// price s.payment?.fixed?.price ({ value, currency } — value is a string) ·
+// staff s.staffMemberDetails?.staffMembers ([{ staffMemberId, name }] — staffMemberId IS the resource id).
+```
 
+## Optional catalog filters — location & category
+Both auto-skip when there's nothing to choose (see `../../bookings/FLOW.md` §7).
+Merge the chosen filter into the **same** `queryServices` filter and re-query.
 ```js
-import { availabilityTimeSlots, eventTimeSlots } from "https://esm.sh/@wix/bookings@1";
-// register the module(s) in createClient({ modules: { ... } })
+// Locations — show the selector only when count > 1.
+const loc = await wix.services.queryLocations();
+const businessLocations = loc.businessLocations?.locations ?? []; // [{ _id, type, business: { name } }]
+const count = businessLocations.length + (loc.customLocations?.exists ? 1 : 0) + (loc.customerLocations?.exists ? 1 : 0);
+// Categories — non-fatal; show the bar only when > 1.
+const cats = (await wix.categoriesV2.queryCategories().find()).items ?? []; // [{ _id, name }]
+
+// Merge into the services filter:
+const filter = { appId: BOOKING_APP_ID };
+if (categoryId) filter["category.id"] = { $eq: categoryId };
+if (locationId === "custom") filter["locations.type"] = { $hasSome: ["CUSTOM"] };
+else if (locationId === "customer") filter["locations.type"] = { $hasSome: ["CUSTOMER"] };
+else if (locationId) filter["locations.business.id"] = { $hasSome: [locationId] };
+// → wix.services.queryServices({ query: { filter, paging: { limit: 100 } }, conditionalFields: ["STAFF_MEMBER_DETAILS"] }).find()
+// Carry locationId/locationType into the availability call so slots are scoped to it.
+```
 
-// APPOINTMENT — serviceId is a single GUID STRING (NOT an array):
+## Availability (week calendar)
+Render a **week calendar** (day strip → the day's times), not a flat grid — see
+`../../bookings/FLOW.md` § 5. `fromLocalDate`/`toLocalDate` are **local** strings
+(`YYYY-MM-DDThh:mm:ss`, no `Z`) + a `timeZone`.
+
+> **Multi-location: scope to ONE business location.** Unscoped,
+> `listAvailabilityTimeSlots` returns **one slot per location** per time → duplicate
+> rows. Source the 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 (its entries can
+> carry an id the engine doesn't recognize → scoping returns 0 slots). Default to the
+> carried/first and pass the single-location filter below; with no business locations,
+> leave it unscoped. (Staff does NOT multiply rows — only location does.) See FLOW.md §7.
+```js
+// APPOINTMENT — serviceId is a single GUID STRING. Staff (§8) OPTIONAL; location ALWAYS when >1:
 const a = await wix.availabilityTimeSlots.listAvailabilityTimeSlots({
-  serviceId, fromLocalDate, toLocalDate, timeZone, bookable: true, cursorPaging: { limit: 50 },
+  serviceId, fromLocalDate, toLocalDate, timeZone, bookable: true, cursorPaging: { limit: 100 },
+  // staff:    resourceTypes: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, resourceIds: [resourceId] }], includeResourceTypeIds: [STAFF_MEMBER_RESOURCE_TYPE_ID],
+  // location: locations: [{ _id: locationId, locationType: "BUSINESS" }],
 });
-// slots: a.timeSlots[] — localStartDate/localEndDate/scheduleId at the TOP level.
-
-// CLASS — different namespace, PLURAL serviceIds; slots carry eventInfo.eventId, no scheduleId:
+// slots a.timeSlots[] — localStartDate/localEndDate/scheduleId at the TOP level.
+// CLASS — different namespace, PLURAL serviceIds; slots carry eventInfo.eventId, no scheduleId.
+// CLASS filters staff + location via eventFilter:
 const c = await wix.eventTimeSlots.listEventTimeSlots({
   serviceIds: [serviceId], fromLocalDate, toLocalDate, timeZone, includeNonBookable: false,
+  // eventFilter: { "resources.id": { $hasSome: [resourceId] }, "location.id": [locationId] },
 });
 ```
 
-`fromLocalDate`/`toLocalDate` are **local** date strings (`YYYY-MM-DDThh:mm:ss`, no `Z`) with an explicit `timeZone`.
-
-## Book — redirect to Wix-hosted bookings checkout
-
-Same pattern as the ecom guide's hosted checkout: create a redirect session for the chosen slot and send the visitor to Wix.
-
+## Optional staff selection
+The staff list is on the service (`s.staffMemberDetails.staffMembers` → `[{ staffMemberId, name }]`;
+`staffMemberId` IS the resource id despite the name). Show a picker only when >1 staff.
+Filtering uses that `staffMemberId` (the `resourceId`/`resourceIds` above).
+When a specific staff is chosen, set `slot.resource = { _id: staffMemberId, name }` on the
+slot you pass to `createBooking` (the booking books that resource); leave it unset for
+"any staff" → the **ANY_RESOURCE fallback** already in the booking snippet below.
+
+## Booking form — schema-driven
+The booking form is a `@wix/forms` form on the service (`service.form._id`). Read
+its schema and render fields by `componentType`, collecting values keyed by
+`target` (`../../bookings/FLOW.md` § 4):
 ```js
-import { redirects } from "https://esm.sh/@wix/redirects@1"; // register in modules
-
-const { redirectSession } = await wix.redirects.createRedirectSession({
-  bookingsCheckout: {
-    slotAvailability: {
-      slot: {
-        serviceId: slot.serviceId,
-        scheduleId: slot.scheduleId,        // APPOINTMENT slots
-        startDate: slot.localStartDate,
-        endDate: slot.localEndDate,
-        timezone: timeZone,
-      },
-    },
-    timezone: timeZone,
-  },
-  callbacks: { postFlowUrl: window.location.href }, // return to the brought-in site after checkout
-});
-window.location.href = redirectSession.fullUrl;
+const { form } = await wix.forms.getForm(service.form._id);
+const RENDERABLE = ["TEXT_INPUT", "PHONE_INPUT", "DROPDOWN"];
+const fields = (form.formFields ?? []).filter(
+  (f) => f.fieldType === "INPUT" && !f.hidden &&
+         RENDERABLE.includes(f.inputOptions?.stringOptions?.componentType),
+);
+// render each by f.inputOptions.stringOptions.componentType; collect values by f.inputOptions.target.
+// SKIP complex object-valued fields (e.g. multi-line ADDRESS, no string componentType) —
+// 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.
 ```
 
-The hosted flow collects contact details, takes payment when the service is paid, **confirms the booking (holds the seat)**, and sends the customer email — none of which the client site has to implement.
-
-> **CLASS sessions:** the verified `slotAvailability.slot` shape above is the APPOINTMENT one. For a CLASS service, slots come from `eventTimeSlots` with `eventInfo.eventId` and no `scheduleId` — verify the class slot→redirect mapping against the redirects SDK docs at wiring time before wiring a CLASS service; don't guess the shape.
+## Book — the ecom Cart V2 sequence
+Mirror `../../astro/templates/bookings/bookingDriver.ts` (the exact payloads).
+Run the same sequence through `wix.*`; the cart holds the seat, so no elevation.
+```js
+const BOOKING_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+const STAFF_MEMBER_RESOURCE_TYPE_ID = "1cd44cf8-756f-41c3-bd90-3e2ffcaf1155";
+
+// Build the slot. APPOINTMENT carries scheduleId; CLASS carries eventId (Wix
+// derives the rest). No staff chosen → the ANY_RESOURCE fallback.
+// When a specific staff was chosen, use `resource: { _id: resourceId, name }`
+// INSTEAD of `resourceSelections` (drop the ANY_RESOURCE fallback for that slot).
+const slot =
+  slotType === "CLASS"
+    ? { serviceId, eventId, timezone }
+    : {
+        serviceId, scheduleId, startDate, endDate, timezone,
+        resourceSelections: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, selectionMethod: "ANY_RESOURCE" }],
+        location: { locationType: "OWNER_BUSINESS" },
+      };
+
+// selectedPaymentOption must match the service: online-only → ONLINE,
+// in-person-only → OFFLINE, else ONLINE. DERIVE it — do not hardcode ONLINE: a
+// free / pay-in-person service booked ONLINE is rejected by the cart with
+// INSUFFICIENT_INVENTORY (it's the only service kind that reaches placeOrder).
+const o = service.payment?.options;
+const selectedPaymentOption =
+  o?.online && !o?.inPerson ? "ONLINE" : !o?.online && o?.inPerson ? "OFFLINE" : "ONLINE";
+
+// 1. createBooking → CREATED. Arg 1 is the BOOKING object (slot nested under
+//    bookedEntity); formSubmission/sendSmsReminder go in the options arg.
+const { booking } = await wix.bookings.createBooking(
+  { selectedPaymentOption, totalParticipants: 1, bookedEntity: { slot } },
+  { formSubmission, sendSmsReminder: true }, // formSubmission keyed by each field's `target`
+);
+// 2. createCart — one catalog item per booking._id, catalogReference.appId = BOOKING_APP_ID, channel WEB.
+const cart = await wix.createCart({ catalogItems: [{ quantity: 1, catalogReference: { catalogItemId: booking._id, appId: BOOKING_APP_ID } }], cart: { source: { channelType: "WEB" } } });
+// 3. calculateCart → { cart, summary }, then compute the checkout decision.
+const { cart: calc, summary } = await wix.calculateCart(cart._id);
+const checkoutRequired =
+  service.bookingPolicy?.cancellationFeePolicy?.enabled
+    ? true
+    : Number(summary?.priceSummary?.total?.amount ?? 0) === 0
+      ? false
+      : calc?.lineItems?.[0]?.paymentConfig?.paymentOption !== "FULL_PAYMENT_OFFLINE";
+// 4. paid → redirect (ecomCheckout.checkoutId = cartId) ; free/offline → placeOrder.
+if (checkoutRequired) {
+  const { redirectSession } = await wix.redirects.createRedirectSession({ ecomCheckout: { checkoutId: cart._id }, callbacks: { postFlowUrl: window.location.href } });
+  window.location.href = redirectSession.fullUrl;
+} else {
+  await wix.placeOrder(cart._id); // booked — no redirect
+}
+```
 
-## Deferred (needs the server runtime — `@wix/astro`)
+> Confirm the `@wix/auto_sdk_ecom_cart-v-2` function registration shape on a
+> CDN/own client at wiring time; the payloads above match the astro `bookingDriver.ts`.
 
-On-site booking flow (calendar + form + elevated `confirmBooking` seat-hold), manage/cancel via anonymous action tokens, and the native waitlist (v1, Manage Bookings scope) — all implemented in the astro vertical (`references/astro/bookings/`); out of scope for client-only integration.
+## Out of scope
+Waitlist and on-site manage/cancel — out of scope (same as the astro vertical;
+neither has a headless SoT — display-only policy flags only, no join/cancel logic).
+Show bookable slots only; post-booking self-service is handled by the Wix-hosted
+flow / member area.

package/skills/wix-headless/references/shared/DESIGN_MD.md

@@ -21,8 +21,6 @@ typography:
     fontWeight: <number>         # optional
     lineHeight: <Dimension|number>  # optional
     letterSpacing: <Dimension>   # optional
-spacing:
-  <scale-level>: <Dimension|number>
 rounded:                # corner radii (DESIGN.md's name for radius tokens)
   <scale-level>: <Dimension>
 containers:             # EXTENSION (this skill): content/reading widths
@@ -51,11 +49,12 @@ googleFontsHref: <string>   # EXTENSION (this skill): the ready Google Fonts <li
 |---|---|---|
 | `colors` | `--color-<key>` | semantic role keys (see color roles below) |
 | `typography.<level>.fontFamily` | `--font-<level>` | `display` + `body` required; `mono` optional |
-| `spacing` | `--spacing-<key>` | full `2xs…4xl` rhythm scale |
 | `rounded` | `--radius-<key>` | `sm` + `md` required |
 | `containers` | `--container-<key>` | **extension** — content widths, a separate axis from spacing (`prose, md, 3xl, 6xl`) |
 | `googleFontsHref` | the Layout `<link>` href | **extension** — the ready stylesheet URL for the chosen families |
 
+> **Spacing is not a DESIGN.md token.** The build uses Tailwind v4's built-in numeric spacing scale directly (`gap-4`, `py-24`, `px-6`, …). A named `--spacing-<size>` scale was removed because its t-shirt names (`md`, `3xl`, …) collided with the width utilities (`max-w-3xl` resolved to `--spacing-3xl` instead of `--container-3xl`). Do not author a `spacing` group.
+
 ### Color roles — wix-native keys are the contract
 
 The skill's component-CSS templates reference a fixed set of `--color-*` names (`STYLING.md` § "Required tokens"). So the **canonical color token keys in our DESIGN.md are the wix editorial roles** — and these are valid DESIGN.md color token names (the format leaves token names free-form):

package/skills/wix-headless/references/shared/IMPLEMENTER.md

@@ -41,7 +41,7 @@ Every input you need is either inlined in your prompt or — for seeded entity I
 | Scope | Where its inputs come from |
 |---|---|
 | `seed` | All **inlined**: `brand`, `intent.<pack>`, `siteId`, recipe path(s). Do NOT re-derive these. |
-| `components` | **Inlined**: `brand`. **Read from disk**: the design tokens (the DESIGN.md vocabulary — `colors`/`typography`/`spacing`/`rounded`/`containers`) from `.wix/design-tokens.css` (gate-verified present; also the CSS variables the build consumes). Components do not need seeded IDs. |
+| `components` | **Inlined**: `brand`. **Read from disk**: the design tokens (the DESIGN.md vocabulary — `colors`/`typography`/`rounded`/`containers`; spacing is Tailwind's numeric scale, not a token) from `.wix/design-tokens.css` (gate-verified present; also the CSS variables the build consumes). Components do not need seeded IDs. |
 | `pages` / `pages-*` | **Inlined:** `brand`. **Read from disk:** the design tokens (`.wix/design-tokens.css`, DESIGN.md vocabulary); your `seeded.<vertical>` slice from `.wix/seeded.json` (products, posts, collections IDs). Page data wiring uses live SDK queries; the `seeded` data is for path resolution + demo content authoring. |
 
 If a required **inlined** input is missing from your prompt, or your **`.wix/seeded.json` slice** is absent (e.g. you are dispatched as `pages-products` but `.wix/seeded.json` has no `seeded.stores`), fail fast — return `status: "failed"` with `errors: [{ code: "SEEDED_JSON_SLICE_MISSING", missing: "seeded.stores.products" }]` (or `PROMPT_INCOMPLETE` for an inlined gap). Do NOT re-fetch via curl — the gap means an upstream phase didn't complete, and re-querying would mask the real bug.
@@ -120,11 +120,11 @@ The full styling contract (tokens-as-utilities default, when global semantic cla
 
 - **camelCase for identifiers, kebab-case for filenames, PascalCase for components.** Example: `ProductCard.astro`, `queryBlogPosts` function, `cart-updated` event.
 - **No inline styles beyond design-token CSS variables.** `style={{ color: "red" }}` is forbidden; `style={{ color: "var(--color-accent)" }}` is fine.
-- **Tailwind v4 `@reference` is mandatory in any scoped CSS that uses `@apply`.** Tailwind v4 isolates `@apply` per file — utilities defined in the main entry CSS (where `@theme` lives) are NOT visible to `components-*.css` unless that file prepends `@reference "./global.css";` on line 1. If your scope writes a `components-<vertical>.css` that uses `@apply` with theme tokens (e.g., `@apply gap-sm font-display text-sm`), the file MUST start with:
+- **Tailwind v4 `@reference` is mandatory in any scoped CSS that uses `@apply`.** Tailwind v4 isolates `@apply` per file — utilities defined in the main entry CSS (where `@theme` lives) are NOT visible to `components-*.css` unless that file prepends `@reference "./global.css";` on line 1. If your scope writes a `components-<vertical>.css` that uses `@apply` with theme tokens (e.g., `@apply gap-3 font-display text-sm`), the file MUST start with:
   ```css
   @reference "./global.css";
   ```
-  Without it, the build breaks at release time with `Cannot apply unknown utility class 'gap-sm' …` even though `tsc` and `astro check` pass clean — only the bundler catches it.
+  Without it, the build breaks at release time with `Cannot apply unknown utility class 'gap-3' …` even though `tsc` and `astro check` pass clean — only the bundler catches it.
 - **Fail loud, never silently.** If data is missing, a required field is absent, or an REST call returns an unexpected shape, return `status: "failed"` with details. Do not invent placeholders or swallow errors.
 
 ## Return contract
@@ -188,7 +188,7 @@ The `data` shapes for the scopes this file owns — `components` and `pages`/`pa
 | Issuing REST calls from a `components` or `pages` scope | Components/Pages are frontend-only; read `seeded` data from your `.wix/seeded.json` slice (pages only) — never curl |
 | Re-querying when your `seeded.<vertical>` slice is missing from `.wix/seeded.json` | Fail fast with `SEEDED_JSON_SLICE_MISSING` — an upstream phase didn't complete (do NOT re-query) |
 | Depending on mutable shared state the orchestrator holds in scratch | Every input is inlined; the one shared file you may read is your `.wix/seeded.json` slice (read-only) |
-| Inventing class names for layout/spacing/typography (`.productCard`, `.heroSection`) | Tailwind utilities derived from `@theme` tokens (`class="flex flex-col gap-md"`, `class="py-4xl"`). For one-off page decoration, co-located `<style>` block. |
+| Inventing class names for layout/spacing/typography (`.productCard`, `.heroSection`) | Tailwind utilities derived from `@theme` tokens (`class="flex flex-col gap-4"`, `class="py-24"`). For one-off page decoration, co-located `<style>` block. |
 | Removing a marker after inserting at it | Marker stays; other verticals may contribute after you |
 | Trailing narrative prose after the return JSON | JSON block must be the last content |
 | Fabricated timestamps in the return JSON | Do not include timing fields — orchestrator captures them |

package/skills/wix-headless/references/shared/STYLING.md

@@ -8,15 +8,15 @@ Every visual decision in a generated site falls into one of three categories. Ea
 
 | Category | Lives in | Owned by | Use for |
 |---|---|---|---|
-| **Tokens (composed as utilities)** | the canonical `DESIGN.md` + its projections: the `@theme` block in `src/styles/global.css` (written by `scripts/compose.mjs`), plus `.wix/design-tokens.css` and `.wix/site.d.ts` (written by `scripts/emit-design-tokens.mjs`) — all from Designer's `DESIGN.md` | Designer picks values (Phase 2); `compose.mjs` writes `@theme` | All color, spacing, typography scale, radii, aspect ratios, shadows, transitions. Pages compose tokens at call sites as Tailwind utilities — `class="py-4xl bg-sand aspect-[16/5]"`. |
+| **Tokens (composed as utilities)** | the canonical `DESIGN.md` + its projections: the `@theme` block in `src/styles/global.css` (written by `scripts/compose.mjs`), plus `.wix/design-tokens.css` and `.wix/site.d.ts` (written by `scripts/emit-design-tokens.mjs`) — all from Designer's `DESIGN.md` | Designer picks values (Phase 2); `compose.mjs` writes `@theme` | All color, typography scale, radii, aspect ratios, shadows, transitions (spacing is Tailwind's built-in numeric scale). Pages compose tokens at call sites as Tailwind utilities — `class="py-24 bg-sand aspect-[16/5]"`. |
 | **Global semantic classes** | `src/styles/global.css` (outside `@theme`) and `src/styles/components-<pack>.css` | Designer + Phase 3 component agents | Compound multi-element patterns, interactive states (`:hover`, `:focus`, `:disabled`), and JS/React DOM query targets. |
 | **Co-located styles** | `<style>` block at the bottom of the same `.astro` file (or component CSS module for islands) | Page or component author | One-off page decoration: hero stamps, custom dividers, ornamental overlays that won't be reused elsewhere. |
 
 ## Default direction
 
-**Tokens-as-utilities is the default.** When you're about to write a class for layout, spacing, typography, alignment, simple background/text color, or aspect ratio, write Tailwind utilities derived from `@theme` instead. The site's design tokens give you `py-4xl`, `gap-sm`, `bg-paper-warm`, `text-ink`, `font-display`, `aspect-[16/5]` etc. Compose them in markup; do not invent semantic classes for these concerns.
+**Tokens-as-utilities is the default.** When you're about to write a class for layout, spacing, typography, alignment, simple background/text color, or aspect ratio, write Tailwind utilities derived from `@theme` instead. The site's design tokens give you `bg-paper-warm`, `text-ink`, `font-display`, `aspect-[16/5]` etc.; spacing is Tailwind-numeric (`py-24`, `gap-3`). Compose them in markup; do not invent semantic classes for these concerns.
 
-The token namespace is the contract. The design tokens (the DESIGN.md token vocabulary — `colors`/`typography`/`spacing`/`rounded`/`containers`) live on disk at `.wix/design-tokens.css` (gate-verified present before the build wave) — **read that file at the start of any pages or components scope** to know which tokens this run published. The orchestrator does **not** inline them in your prompt. (`.wix/site.d.ts` is also on disk for the build.) If a token you need isn't in `.wix/design-tokens.css`, that's a designer-side gap — flag it in your return JSON, don't paper over it with a custom class.
+The token namespace is the contract. The design tokens (the DESIGN.md token vocabulary — `colors`/`typography`/`rounded`/`containers`) live on disk at `.wix/design-tokens.css` (gate-verified present before the build wave) — **read that file at the start of any pages or components scope** to know which tokens this run published. The orchestrator does **not** inline them in your prompt. (`.wix/site.d.ts` is also on disk for the build.) If a token you need isn't in `.wix/design-tokens.css`, that's a designer-side gap — flag it in your return JSON, don't paper over it with a custom class.
 
 ## Decision tree
 
@@ -32,24 +32,22 @@ If none fit, you're probably trying to do something the tokens don't support yet
 
 These are layout/spacing/typography concerns that should always be utilities, never standalone classes:
 
-- Section padding / margins (`py-4xl`, `mt-3xl`, `mb-2xl`)
-- Flex / grid layouts (`flex flex-col gap-md`, `grid grid-cols-3 gap-lg`)
+- Section padding / margins (`py-24`, `mt-16`, `mb-12`)
+- Flex / grid layouts (`flex flex-col gap-4`, `grid grid-cols-3 gap-6`)
 - Aspect ratios (`aspect-[4/5]`, `aspect-square`)
 - Plain typography choices (`text-display-lg font-display`, `text-mute uppercase tracking-wide`)
 - Background / foreground color application without state (`bg-paper`, `text-ink-soft`)
-- Container widths derived from tokens (`max-w-prose`, `w-full`) **only when** the designer declared matching `--container-*` keys in `@theme`
+- Container widths (`max-w-prose`, `max-w-6xl`, `max-w-3xl`, `w-full`) — these resolve to the `--container-*` keys the designer declared.
 
-### Prose / reading width (CMS, FAQ, About)
+### Spacing & reading width
 
-Tailwind v4 resolves `max-w-3xl` to `var(--container-3xl)`, **not** `var(--spacing-3xl)`. If the designer published `--spacing-3xl: 5rem` but no `--container-3xl`, FAQ/About columns collapse to ~80px.
+**Spacing is Tailwind's built-in numeric scale** — `gap-4`, `py-24`, `px-6`, `mt-16`, etc. There is **no** named `--spacing-<size>` scale (it was removed: its t-shirt names `md`/`3xl`/… collided with the width utilities, so `max-w-3xl` resolved to `--spacing-3xl` ≈ 96px). Common steps: `1`=0.25rem, `2`=0.5, `3`=0.75, `4`=1rem, `6`=1.5, `8`=2, `12`=3, `16`=4, `24`=6rem.
 
-**Page agents (Phase 4):**
+> **Never reintroduce a named `--spacing-*` scale.** In Tailwind v4 the `--spacing-*` namespace also generates the width/sizing families (`max-w-*`, `w-*`, `min-w-*`, …), so any `--spacing-<key>` token shadows the matching `max-w-<key>`. The current fix works because the skill's spacing steps happen to equal Tailwind's numeric defaults — but if a brand ever needs genuinely *custom* spacing **values**, put them under a different namespace (e.g. `--rhythm-*`) or use arbitrary values (`py-[5.5rem]`); do not revive `--spacing-*`.
 
-- **Do not** use `max-w-2xl`, `max-w-3xl`, etc. unless `global.css` `@theme` documents the matching `--container-*` key (grep `@theme` before choosing).
-- **Prefer** `container-reading` (designer `@utility`), `max-w-6xl` when `--container-6xl` exists, or explicit arbitrary width `max-w-[48rem]`.
-- **Do not** confuse spacing scale with container scale — `py-3xl` uses `--spacing-3xl`; `max-w-3xl` uses `--container-3xl`.
+**Width / reading columns:** `max-w-md`, `max-w-3xl`, `max-w-6xl`, `max-w-prose` now resolve correctly to the `--container-*` keys (no spacing collision), so use them freely; `container-reading` (the designer `@utility`) or an arbitrary `max-w-[48rem]` also work.
 
-If a designer's `global.css` contains rules like `.featured-section { padding-block: var(--spacing-4xl); }` or `.product-card-body { display: flex; flex-direction: column; gap: var(--spacing-xs); }`, those are misplaced — they belong in markup as utilities. Inventing such classes ships broken layouts: every consumer needs the designer to have pre-declared the class, and Tailwind v4 silently drops the references when the rule is missing.
+If a designer's `global.css` contains rules like `.featured-section { padding-block: 6rem; }` or `.product-card-body { display: flex; flex-direction: column; gap: 0.5rem; }`, those are misplaced — they belong in markup as utilities (`py-24`, `flex flex-col gap-2`). Inventing such classes ships broken layouts: every consumer needs the designer to have pre-declared the class, and Tailwind v4 silently drops the references when the rule is missing.
 
 ## Required tokens — the component-CSS template contract
 
@@ -68,11 +66,10 @@ The per-pack `components-<pack>.css` templates at `<SKILL_ROOT>/references/astro
 | `--color-error` | optional | `var(--color-accent)` or hardcode | ecom cart-item-unavailable, stores back-in-stock-error |
 | `--font-display` | **required** | — | every pack — headings + labels |
 | `--font-body` | **required** | — | every pack — body text + UI |
-| `--spacing-2xs` … `--spacing-4xl` | **required (full scale)** | — | every template uses `gap: var(--spacing-md)` and similar |
 | `--radius-sm`, `--radius-md` | **required** | — | buttons, inputs, cards |
 | `--radius-lg`, `--radius-xl` | optional | — | stores product-card |
 
-The templates do NOT use `@apply` — every rule is `property: var(--token);` directly. This means missing utilities don't fail at build time (the way `@apply gap-sm` would). Missing tokens degrade silently to `var(missing) → unset → initial`. That makes the failure mode "ugly component" not "broken build" — easier to recover from but harder to detect, so verify the full set above is in `@theme` before returning.
+The templates do NOT use `@apply` — every rule is `property: var(--token);` directly. This means missing utilities don't fail at build time (the way `@apply gap-3` would). Missing tokens degrade silently to `var(missing) → unset → initial`. That makes the failure mode "ugly component" not "broken build" — easier to recover from but harder to detect, so verify the full set above is in `@theme` before returning.
 
 **Why this contract exists.** The component templates are authored against a stable, brand-agnostic token vocabulary so they don't need to be regenerated per run. Using `@apply` against brand-specific tokens (e.g. `bark`, `cream`, `parchment`) that designers don't publish fails the build with `Cannot apply unknown utility class`. Direct `var()` against the required-token list above avoids that class of failure entirely.
 
@@ -119,15 +116,15 @@ For any listed class the Composer's `global.css` declares: if a template referen
 Astro's `<style>` blocks scope automatically to the `.astro` file by default — no class-name collision risk across routes. When a page needs decoration that doesn't fit utilities and isn't reusable, the rule lives next to its only caller:
 
 ```astro
-<section class="relative py-4xl">
+<section class="relative py-24">
   <div class="hero-stamp">Made in small batches</div>
 </section>
 
 <style>
   .hero-stamp {
     position: absolute;
-    bottom: var(--spacing-lg);
-    right: var(--spacing-lg);
+    bottom: 1.5rem;
+    right: 1.5rem;
     background: rgba(27, 26, 23, 0.75);
     color: var(--color-paper);
     padding: 0.5rem 0.875rem;

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

@@ -95,8 +95,8 @@ If you find one of these missing at runtime, that's an orchestrator-side bug —
 
 Stores-specific component CSS lives in `src/styles/components-stores.css` (pre-copied from the template by the orchestrator before Step 4.5 — see the `components` scope-routing note above and `../astro/stores/COMPONENTS_CSS.md`), NOT in the designer's `global.css`. The classes the pack owns:
 
-- `.product-card`, `.product-card-media`, `.product-card-ribbon`, `.product-card-index` — the product card itself, including the `overflow: hidden` + `border-radius` clipping context. Whoever writes the `border-radius` here also writes any inner padding required to keep child content inside the rounded edges. Without inner padding, a price `<p>` sits flush against the rounded bottom corner and descenders get clipped. Add `padding-bottom: var(--spacing-md)` on the card plus horizontal padding on each text block when you set the radius. See `references/shared/STYLING.md` § "Component-specific CSS is owned by the component, not the designer".
-- `.product-grid` — the layout that lists product cards. Both `/products` (pages-products scope) and `/category/[slug]` (pages-categories scope) consume it from one place. Include `display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: var(--spacing-xl);` plus the View-Transitions opacity fade for in-flight navigations.
+- `.product-card`, `.product-card-media`, `.product-card-ribbon`, `.product-card-index` — the product card itself, including the `overflow: hidden` + `border-radius` clipping context. Whoever writes the `border-radius` here also writes any inner padding required to keep child content inside the rounded edges. Without inner padding, a price `<p>` sits flush against the rounded bottom corner and descenders get clipped. Add `padding-bottom: 1rem` on the card plus horizontal padding on each text block when you set the radius. See `references/shared/STYLING.md` § "Component-specific CSS is owned by the component, not the designer".
+- `.product-grid` — the layout that lists product cards. Both `/products` (pages-products scope) and `/category/[slug]` (pages-categories scope) consume it from one place. Include `display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 2rem;` plus the View-Transitions opacity fade for in-flight navigations.
 - `.offer-callout` family (`.offer-callout`, `-item`, `-badge`, `-name`, `-detail`, `-foot`) — discount panel rendered above `<ProductPurchase>` on `/products/[slug]`.
 
 The designer's `global.css` declares only tokens, the `.btn` family, decorative slots, the editorial-rule, and the site-shell shells. If `global.css` ships with a partial rule for any class above, that's a designer bug — flag it in your return JSON's `errors` array (`{code: "GLOBAL_CSS_LEAK", class: "<name>"}`) and override with the complete rule in `components-stores.css`.

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

@@ -1,18 +1,18 @@
 ---
 name: bookings
-description: "Service-based booking — services catalog, availability calendar, and booking flow via Wix Bookings."
+description: "Service-based booking — services catalog (with location + category filters and staff selection), availability calendar, and booking flow for appointments and classes via Wix Bookings."
 triggers: ["booking", "appointment", "schedule", "reserve", "class", "session", "consult", "therapy", "lesson", "coaching", "trainer", "tutor", "salon", "spa", "clinic"]
 requires: []
 
 features:
   - name: "Services catalog"
-    description: "Browse bookable services (appointments or group classes) with descriptions, duration, pricing, and instructor info."
+    description: "Browse bookable appointment and class services with descriptions, duration, and pricing — filterable by category and (for multi-location businesses) by location."
+  - name: "Staff selection"
+    description: "On multi-staff services, choose a specific staff member (or any) and see that staff's availability."
   - name: "Online booking"
-    description: "Pick an available time slot, complete a booking form, and receive confirmation — all without leaving your site."
-  - name: "Group classes"
-    description: "Capacity-aware class sign-up with party size, the leading instructor per session, and a waitlist when a session is full."
-  - name: "Manage booking"
-    description: "View and cancel a booking from the confirmation page or a shared manage link, no account login required."
+    description: "Pick an available time slot on a day-grouped availability calendar, complete the service's booking form, and confirm."
+  - name: "Secure checkout"
+    description: "Free or pay-in-person bookings confirm instantly; paid services hand off to Wix's secure hosted checkout."
 
 apps:
   - name: "Wix Bookings"
@@ -24,8 +24,8 @@ routes:
     name: "Service Detail"
   - route: "/booking-confirmation"
     name: "Booking Confirmation"
-  - route: "/manage-booking"
-    name: "Manage Booking"
+  - route: "Hosted by Wix"
+    name: "Secure Checkout"
 
 disabled: false
 ---

package/skills/wix-headless/scripts/compose.mjs

@@ -192,7 +192,6 @@ function designMdToTokens(fm) {
   return {
     colors,
     fonts,
-    spacing: fm.spacing ?? {},
     radii: fm.rounded ?? {},        // DESIGN.md calls corner radii `rounded`
     containers: fm.containers ?? {}, // custom group
     ...(typeof fm.googleFontsHref === "string" ? { googleFontsHref: fm.googleFontsHref } : {}),
@@ -241,7 +240,6 @@ const SYSTEM_FONTS = new Set([
 
 const colors = { ...(designTokens.colors ?? {}) };
 const fonts = { ...(designTokens.fonts ?? {}) };
-const spacing = { ...(designTokens.spacing ?? {}) };
 const radii = { ...(designTokens.radii ?? {}) };
 const containers = { ...(designTokens.containers ?? {}) };
 
@@ -272,12 +270,10 @@ ensure(colors, "error", "#c0392b", "--color-");
 ensure(fonts, "display", "Georgia, serif", "--font-");
 ensure(fonts, "body", "system-ui, sans-serif", "--font-");
 
-// Spacing — full 2xs..4xl scale.
-const SPACING_DEFAULTS = {
-  "2xs": "0.25rem", xs: "0.5rem", sm: "0.75rem", md: "1rem", lg: "1.5rem",
-  xl: "2rem", "2xl": "3rem", "3xl": "4rem", "4xl": "6rem",
-};
-for (const [k, v] of Object.entries(SPACING_DEFAULTS)) ensure(spacing, k, v, "--spacing-");
+// Spacing is NOT a named scale — Tailwind v4's built-in numeric spacing
+// (`--spacing` base → gap-4, py-24, …) is used directly. Emitting named
+// --spacing-<t-shirt> tokens collided with the width utilities (max-w-3xl etc.
+// drew from --spacing-3xl), so the named scale was removed (CODEAI-696).
 
 // Radii — sm + md required.
 ensure(radii, "sm", "0.25rem", "--radius-");
@@ -296,8 +292,6 @@ emitGroup("--color-", colors);
 themeLines.push("");
 emitGroup("--font-", fonts);
 themeLines.push("");
-emitGroup("--spacing-", spacing);
-themeLines.push("");
 emitGroup("--radius-", radii);
 themeLines.push("");
 emitGroup("--container-", containers);
@@ -310,14 +304,12 @@ const errors = [];
 const REQUIRED = [
   ...["paper", "paper-warm", "ink", "mute", "rule", "accent"].map((k) => `--color-${k}`),
   "--font-display", "--font-body",
-  ...["2xs", "xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl"].map((k) => `--spacing-${k}`),
   "--radius-sm", "--radius-md",
   ...["prose", "md", "3xl", "6xl"].map((k) => `--container-${k}`),
 ];
 const present = new Set([
   ...Object.keys(colors).map((k) => `--color-${k}`),
   ...Object.keys(fonts).map((k) => `--font-${k}`),
-  ...Object.keys(spacing).map((k) => `--spacing-${k}`),
   ...Object.keys(radii).map((k) => `--radius-${k}`),
   ...Object.keys(containers).map((k) => `--container-${k}`),
 ]);
@@ -325,12 +317,6 @@ for (const tok of REQUIRED) {
   if (!present.has(tok)) errors.push({ code: "MISSING_REQUIRED_TOKEN", token: tok });
 }
 
-// Container ≠ spacing: a --container-* value must never equal a --spacing-* value.
-const spacingValues = new Set(Object.values(spacing));
-for (const [k, v] of Object.entries(containers)) {
-  if (spacingValues.has(v)) errors.push({ code: "CONTAINER_EQUALS_SPACING", token: `--container-${k}`, value: v });
-}
-
 // ── skeleton load + substitution helpers ──────────────────────────────────────
 function readTemplate(name) {
   const p = join(TEMPLATES, name);
@@ -526,7 +512,6 @@ const manifest = {
     homeMarkers: homeMarkerPacks.map((p) => `home:${p}`),
     tokensApplied: {
       colors: Object.keys(colors).length,
-      spacing: Object.keys(spacing).length,
       containers: Object.keys(containers).length,
       radii: Object.keys(radii).length,
       fonts: Object.keys(fonts).length,

package/skills/wix-headless/scripts/emit-design-tokens.mjs

@@ -115,7 +115,6 @@ if (!design || typeof design !== "object" || Object.keys(design).length === 0) {
 
 const colors = design.colors ?? {};
 const typography = design.typography ?? {};
-const spacing = design.spacing ?? {};
 const rounded = design.rounded ?? {};
 const containers = design.containers ?? {};
 const fontFamilyOf = (lvl) => (typography[lvl] && typeof typography[lvl] === "object" ? typography[lvl].fontFamily : typography[lvl]);
@@ -136,7 +135,6 @@ for (const lvl of Object.keys(typography)) {
   if (fam) cssLines.push(`  --font-${lvl}: ${fam};`);
 }
 for (const [k, v] of Object.entries(rounded)) cssLines.push(`  --radius-${k}: ${v};`);
-for (const [k, v] of Object.entries(spacing)) cssLines.push(`  --spacing-${k}: ${v};`);
 for (const [k, v] of Object.entries(containers)) cssLines.push(`  --container-${k}: ${v};`);
 cssLines.push("}", "");
 writeFileSync(join(wixDir, "design-tokens.css"), cssLines.join("\n"));
@@ -151,7 +149,6 @@ export type DesignTokens = {
   colors: ${recordType(Object.keys(colors))};
   fonts: ${recordType(Object.keys(typography))};
   radii: ${recordType(Object.keys(rounded))};
-  spacing: ${recordType(Object.keys(spacing))};
   containers: ${recordType(Object.keys(containers))};
 };
 `;

package/skills/wix-manage/SKILL.md

@@ -52,6 +52,18 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Create and Update Booking Services](references/bookings/create-and-update-booking-services.md)
 **Technical:** Full CRUD operations for Wix Bookings services using Services API. Covers service types (APPOINTMENT, CLASS, COURSE), pricing configuration, location setup, and schedule management.
 
+### [Create Booking Service from Prompt](references/bookings/create-booking-service-from-prompt.md)
+**Technical:** Use when the user wants to create a booking service — e.g. "create a yoga class for $50", "set up consultations", "add a personal training appointment". Routes to the correct type-specific recipe (APPOINTMENT, CLASS, or COURSE), gathers business context, applies defaults, and creates the service.
+
+### [Create Appointment Service](references/bookings/create-appointment-service.md)
+**Technical:** Use when the user wants to create an appointment/consultation/1-on-1 service — e.g. "set up consultations for $75", "create a meeting service". Handles staff assignment, session duration, and pricing via bulkCreateServices API.
+
+### [Create Class Service](references/bookings/create-class-service.md)
+**Technical:** Use when the user wants to create a group class — e.g. "create a yoga class for $50", "set up a pilates class". Handles group capacity, recurring sessions, and pricing via bulkCreateServices API.
+
+### [Create Course Service](references/bookings/create-course-service.md)
+**Technical:** Use when the user wants to create a multi-session course — e.g. "create a 6-week workshop", "set up a training program for $300". Handles group capacity, full-course pricing, and fixed series via bulkCreateServices API.
+
 ### [End-to-End Booking Flow](references/bookings/end-to-end-booking-flow.md)
 **Technical:** Complete booking flow from service discovery to payment. Query services, check availability with Time Slots V2, create bookings, and process payment via eCommerce checkout.