@wix/agent-skills 1.9.0 → 1.11.0

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

@@ -32,16 +32,17 @@ Client-side `@wix/sdk` — CDN imports for `none`-build, bundled for `own`-build
 ## The client (acquire once)
 ```js
 import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk@1"; // bundled for own-build
-import { services, availabilityTimeSlots, eventTimeSlots, bookings } from "https://esm.sh/@wix/bookings@1";
+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, forms, redirects, ...cartV2 },
+  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.)
 
 ## Render services
 ```js
@@ -54,21 +55,68 @@ const { items } = await wix.services.queryServices({
 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).
+// 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
+// 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.
 ```
 
 ## 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:
-const a = await wix.availabilityTimeSlots.listAvailabilityTimeSlots({ serviceId, fromLocalDate, toLocalDate, timeZone, bookable: true, cursorPaging: { limit: 100 } });
+// 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: 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:
-const c = await wix.eventTimeSlots.listEventTimeSlots({ serviceIds: [serviceId], fromLocalDate, toLocalDate, timeZone, includeNonBookable: false });
+// 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] },
+});
 ```
 
+## 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
@@ -95,6 +143,8 @@ 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 }
@@ -140,7 +190,8 @@ if (checkoutRequired) {
 > 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`.
 
-## Out of v1
-Waitlist and on-site manage/cancel — out of scope (same as the astro vertical).
+## 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,14 +1,16 @@
 ---
 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 appointment services with descriptions, duration, and pricing."
+    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 on a calendar, complete the service's booking form, and confirm."
+    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."
 

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/references/bookings/create-appointment-service.md

@@ -13,7 +13,6 @@ description: "Create an appointment booking service — e.g. 'set up consultatio
 
 ## Prerequisites
 
-- **Wix Bookings app installed** (App ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`). Use [List Installed Apps](../app-installation/list-installed-apps.md) to verify, and [Install Wix Apps](../app-installation/install-wix-apps.md) to install if missing.
 - For full API field definitions, validation rules, and troubleshooting, see [Create and Update Booking Services](./create-and-update-booking-services.md)
 
 ---
@@ -47,16 +46,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/categories/query' \
   -d '{ "query": {} }'
 ```
 
-### 1c. Get Site Currency
-
-```bash
-curl -X GET 'https://www.wixapis.com/site-properties/v4/properties' \
-  -H 'Authorization: <AUTH>'
-```
-
-Extract `properties.paymentCurrency`. Fall back to `USD` if unavailable.
-
-### 1d. Query Existing Services (Duplicate Check)
+### 1c. Query Existing Services (Duplicate Check)
 
 ```bash
 curl -X POST 'https://www.wixapis.com/bookings/v2/services/query' \
@@ -82,7 +72,6 @@ For any fields the user did not explicitly specify:
 
 ### Pricing (if not specified)
 
-- Use the site's currency from Step 1c
 - If user specifies a price → `rateType: "FIXED"`
 - If user says "free" → `rateType: "NO_FEE"`, `options.inPerson: true`, `options.online: false`
 - If no price mentioned → infer from context (consultations ~$50-100, sessions ~$30-60) or default to free
@@ -136,7 +125,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
         "rateType": "FIXED",
         "options": { "online": true, "inPerson": false },
         "fixed": {
-          "price": { "value": "<PRICE>", "currency": "<CURRENCY>" }
+          "price": { "value": "<PRICE>" }
         }
       },
       "category": {
@@ -186,19 +175,7 @@ Save the `serviceId` from the response: `results[0].item.service.id`
 
 ---
 
-## Step 4: Navigate to Service Form
-
-Use the **RUN_IN_BROWSER** tool to navigate the user to the service form for final review:
-
-```javascript
-window.location.href = `/bookings/services/form/${serviceId}?fromAria=true`;
-```
-
-This executes in the user's browser and redirects them to the service editing page.
-
----
-
-## Step 5: Summary Message
+## Step 4: Summary Message
 
 Provide a summary including:
 
@@ -225,7 +202,6 @@ Provide a summary including:
 
 | Error | Cause | Action |
 |---|---|---|
-| 428 "App not installed" | Bookings not installed | Install using [Install Wix Apps](../app-installation/install-wix-apps.md) |
 | 400 "staffMemberIds required" | No staff assigned | Query staff; if none exist, create one via [Bookings Staff Setup](./bookings-staff-setup.md) |
 | 400 "INVALID_PAYMENT_OPTIONS" | Payment misconfigured | Free: `inPerson: true`, `online: false`. Paid: price > 0 |
 | 403 | Permission denied | Inform user they lack permission |
@@ -261,6 +237,5 @@ Provide a summary including:
 - [Create Category](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/create-category)
 - [Query Staff Members](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/query-staff-members)
 - [Create Staff Member](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/create-staff-member)
-- [Site Properties](https://dev.wix.com/docs/api-reference/business-management/site-management/site-properties/properties/read)
 - [About Service Types](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-types)
 - [About Service Payments](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-payments)

package/skills/wix-manage/references/bookings/create-booking-service-from-prompt.md

@@ -10,13 +10,6 @@ description: "Create a booking service from a user prompt — e.g. 'create a yog
 - User describes a service they want to create using natural language (e.g., "create a yoga class for $50", "set up consultation sessions", "add a personal training appointment")
 - The intent is autonomous creation — fill in reasonable defaults rather than asking the user for every field
 
-## Prerequisites
-
-- **Wix Bookings app installed** (App ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`)
-- If Bookings is not installed, use [Install Wix Apps](../app-installation/install-wix-apps.md) to install it first
-
----
-
 ## Step 1: Determine Service Type
 
 | User mentions | Type | Recipe |
@@ -30,7 +23,7 @@ description: "Create a booking service from a user prompt — e.g. 'create a yog
 
 Once the service type is determined, follow the corresponding recipe linked above. Each recipe covers:
 
-1. Gathering business context (staff, categories, currency, duplicate check)
+1. Gathering business context (staff where required, categories, duplicate check)
 2. Applying type-specific defaults (pricing, capacity, duration, staff assignment)
 3. Creating the service via `bulkCreateServices`
 4. Navigating to the service form for user review

package/skills/wix-manage/references/bookings/create-class-service.md

@@ -14,7 +14,6 @@ description: "Create a class booking service — e.g. 'create a yoga class for $
 
 ## Prerequisites
 
-- **Wix Bookings app installed** (App ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`). Use [List Installed Apps](../app-installation/list-installed-apps.md) to verify, and [Install Wix Apps](../app-installation/install-wix-apps.md) to install if missing.
 - For full API field definitions, validation rules, and troubleshooting, see [Create and Update Booking Services](./create-and-update-booking-services.md)
 
 ---
@@ -32,16 +31,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/categories/query' \
   -d '{ "query": {} }'
 ```
 
-### 1b. Get Site Currency
-
-```bash
-curl -X GET 'https://www.wixapis.com/site-properties/v4/properties' \
-  -H 'Authorization: <AUTH>'
-```
-
-Extract `properties.paymentCurrency`. Fall back to `USD` if unavailable.
-
-### 1c. Query Existing Services (Duplicate Check)
+### 1b. Query Existing Services (Duplicate Check)
 
 ```bash
 curl -X POST 'https://www.wixapis.com/bookings/v2/services/query' \
@@ -67,7 +57,6 @@ For any fields the user did not explicitly specify:
 
 ### Pricing (if not specified)
 
-- Use the site's currency from Step 1b
 - If user specifies a price → `rateType: "FIXED"` (per session)
 - If user says "free" → `rateType: "NO_FEE"`, `options.inPerson: true`, `options.online: false`
 - If no price mentioned → infer from context (yoga/fitness classes ~$15-30, art/music ~$20-40) or default to free
@@ -118,7 +107,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
         "rateType": "FIXED",
         "options": { "online": true, "inPerson": false },
         "fixed": {
-          "price": { "value": "<PRICE>", "currency": "<CURRENCY>" }
+          "price": { "value": "<PRICE>" }
         }
       },
       "category": {
@@ -164,19 +153,7 @@ Save the `serviceId` from the response: `results[0].item.service.id`
 
 ---
 
-## Step 4: Navigate to Service Form
-
-Use the **RUN_IN_BROWSER** tool to navigate the user to the service form for final review:
-
-```javascript
-window.location.href = `/bookings/services/form/${serviceId}?fromAria=true`;
-```
-
-This executes in the user's browser and redirects them to the service editing page.
-
----
-
-## Step 5: Summary Message
+## Step 4: Summary Message
 
 Provide a summary including:
 
@@ -205,7 +182,6 @@ Provide a summary including:
 
 | Error | Cause | Action |
 |---|---|---|
-| 428 "App not installed" | Bookings not installed | Install using [Install Wix Apps](../app-installation/install-wix-apps.md) |
 | 400 "INVALID_PAYMENT_OPTIONS" | Payment misconfigured | Free: `inPerson: true`, `online: false`. Paid: price > 0 |
 | 403 | Permission denied | Inform user they lack permission |
 
@@ -240,6 +216,5 @@ Provide a summary including:
 - [Query Categories](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/query-categories)
 - [Create Category](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/create-category)
 - [Bulk Create Events](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event)
-- [Site Properties](https://dev.wix.com/docs/api-reference/business-management/site-management/site-properties/properties/read)
 - [About Service Types](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-types)
 - [About Service Payments](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-payments)