@wix/agent-skills 1.13.0 → 1.15.0

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

@@ -1,101 +0,0 @@
----
-import Layout from "../../layouts/Layout.astro";
-import ProductCard from "../../components/ProductCard.astro";
-import CategoryRail from "../../components/CategoryRail.astro";
-import { productsV3 } from "@wix/stores";
-import { listStoreCategories } from "../../utils/categories";
-
-const PAGE_SIZE = 24;
-const cursor = Astro.url.searchParams.get("cursor") ?? undefined;
-
-let productList: any[] = [];
-let nextCursor: string | null = null;
-let prevCursor: string | null = null;
-try {
-  let builder = productsV3
-    .queryProducts({ fields: ["CURRENCY"] })
-    .limit(PAGE_SIZE);
-  if (cursor) builder = builder.skipTo(cursor);
-  const result = await builder.find();
-  productList = result.items ?? [];
-  nextCursor = result.cursors?.next ?? null;
-  prevCursor = result.cursors?.prev ?? null;
-} catch (err) {
-  console.error("[products] listing query failed:", err);
-}
-
-// Drop the Wix Gift Card app's auto-mirror products. When the app is enabled,
-// it provisions 5 DIGITAL Stores products (one per denomination) tagged with
-// the "Gift Card" ribbon. Buying them yields a dud line item that does not
-// trigger gift-card issuance — the customer-facing surface for gift cards
-// is /gift-cards (gift-cards pack), not /products.
-productList = productList.filter((p) => p.ribbon?.name !== "Gift Card");
-
-const allCategories = await listStoreCategories();
-
-// Payload for the client-side AddProductImpression event.
-const impressionContents = productList.map((p, index) => ({
-  id: p._id,
-  name: p.name,
-  price: Number(p.actualPriceRange?.minValue?.amount ?? 0),
-  currency: p.actualPriceRange?.minValue?.currency ?? undefined,
-  position: index + 1,
-}));
-
-function pageHref(c: string | null): string | null {
-  if (!c) return null;
-  const params = new URLSearchParams();
-  params.set("cursor", c);
-  return `/products?${params.toString()}`;
-}
----
-
-<Layout title="Products">
-  <section class="page-header">
-    <div class="container-page">
-      <h1 class="page-header-title">Our Products</h1>
-    </div>
-  </section>
-
-  <CategoryRail
-    categories={allCategories}
-    activeSlug={null}
-    prevHref={pageHref(prevCursor)}
-    nextHref={pageHref(nextCursor)}
-  />
-
-  <section class="section-pad">
-    <div class="container-page">
-      {productList.length === 0 ? (
-        <p class="products-empty">
-          No products yet &mdash; please check back shortly.
-        </p>
-      ) : (
-        <div class="product-grid">
-          {productList.map((product, idx) => (
-            <ProductCard product={product} index={idx} />
-          ))}
-        </div>
-      )}
-    </div>
-  </section>
-</Layout>
-
-<script
-  type="application/json"
-  id="analytics-impressions"
-  is:inline
-  set:html={JSON.stringify(impressionContents)}
-/>
-<script>
-  import { trackEvent } from "../../utils/analytics";
-  function fireImpressions() {
-    const el = document.getElementById("analytics-impressions");
-    if (!el?.textContent) return;
-    trackEvent("AddProductImpression", {
-      contents: JSON.parse(el.textContent),
-      origin: "Product Listing",
-    });
-  }
-  document.addEventListener("astro:page-load", fireImpressions);
-</script>

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

@@ -1,161 +0,0 @@
-# Recipe: Seed Initial Blog Posts via REST
-
-Create 3 on-brand blog posts so the blog has real content on first preview.
-
-> **Critical Rules — Read Before Starting**
-> 1. **Seed content is required** — a blog with zero posts on first preview is a build failure. Do not skip this section.
-> 2. **Re-publish after PATCH** — updating a published post sets `hasUnpublishedChanges: true`. Call `publish` again or visitors see the old version.
-> 3. **Use `@wix/blog`, not `@wix/data`** — blog posts are NOT CMS collections.
-> 4. **`RICH_CONTENT` fieldset required** — without it, `post.richContent` is undefined and rendering fails.
-
-> **Required in the Seed phase.** When dispatched with `Scope: seed`, the CLI-minted REST token and discovery context are guaranteed available. Always execute this section — do not skip. A blog with zero posts on first preview is a build failure.
->
-> **Skip only for standalone invocations** where the Blog skill is invoked directly AND CLI token mint fails after recovery. In that case, the user can create posts manually in the Wix dashboard.
-
-## Step 0: Ensure Blog App Is Installed
-
-Before querying blog data, verify the Blog app is installed:
-
-1. **Probe** — `REST: POST https://www.wixapis.com/blog/v3/posts/query`
-2. **If the API returns a "REQUIRED_APP_NOT_INSTALLED" error** → install the Wix Blog app:
-   ```
-   REST: POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install
-   body: {
-     "tenant": { "tenantType": "SITE", "id": "<siteId>" },
-     "appInstance": { "appDefId": "14bcded7-0066-7c35-14d7-466cb3f09103", "enabled": true }
-   }
-   ```
-   > Translate this prose-HTTP form into the full `curl` tool-call shape — pass `body` as JSON in `-d` (NOT a stringified JSON). See `../shared/AUTHENTICATION.md` for the standard REST headers.
-
-   Then retry the probe query to confirm installation succeeded.
-3. **If the probe succeeds** → proceed to Step 1.
-
----
-
-## Step 1: Get Member ID
-
-Blog posts require a `memberId` (the post author). Fetch the first site member:
-
-```
-REST: GET https://www.wixapis.com/members/v1/members
-```
-
-Extract the first member's `_id` from the response. This will be used as the author for all posts.
-
-## Step 2: Design 3 On-Brand Blog Posts
-
-No API call — use discovery context (business type, brand name, tone, industry) to plan 3 posts:
-
-- Titles, summaries, and rich content appropriate for the business
-- Content should demonstrate different Ricos node types (paragraphs, headings, code blocks, lists, blockquotes)
-- Posts should feel like real content a reader would engage with, not placeholder text
-
-**Post design guidelines by business type:**
-
-| Business Type | Post 1 | Post 2 | Post 3 |
-|--------------|--------|--------|--------|
-| AI / tech blog | Architecture deep-dive | Practical comparison (X vs Y) | Lessons learned / field report |
-| Skincare / beauty | Ingredient science spotlight | Routine guide (morning/evening) | Myth-busting or FAQ |
-| Food / restaurant | Behind the recipe | Seasonal menu spotlight | Sourcing / farm-to-table story |
-| Fitness / wellness | Training methodology breakdown | Nutrition or recovery guide | Client transformation story |
-| Fashion / retail | Trend analysis | Styling guide | Behind the brand / process |
-| General business | Industry insight | How-to guide | Company news / milestone |
-
-Adapt titles, tone, and content to match the brand's voice and style.
-
-## Step 3: Create Posts
-
-For each post, call `POST /blog/v3/draft-posts` with `publish: true` to create and immediately publish.
-
-> Do not include the `media` field — cover images are handled separately by the image agent after post creation.
-
-```
-REST: POST https://www.wixapis.com/blog/v3/draft-posts
-body: {
-  "draftPost": {
-    "title": "<Post Title>",
-    "memberId": "<member-id-from-step-1>",
-    "richContent": {
-      "nodes": [
-        {
-          "type": "HEADING",
-          "id": "<unique-id>",
-          "nodes": [
-            { "type": "TEXT", "id": "", "nodes": [], "textData": { "text": "Section Heading", "decorations": [] } }
-          ],
-          "headingData": { "level": 2 }
-        },
-        {
-          "type": "PARAGRAPH",
-          "id": "<unique-id>",
-          "nodes": [
-            { "type": "TEXT", "id": "", "nodes": [], "textData": { "text": "Paragraph content here.", "decorations": [] } }
-          ],
-          "paragraphData": {}
-        }
-      ]
-    }
-  },
-  "publish": true
-}
-```
-
-### Ricos JSON Node Reference
-
-Use these node types to build rich, varied content:
-
-| Node Type | Structure | Use For |
-|-----------|-----------|---------|
-| `PARAGRAPH` | `{ type: "PARAGRAPH", id, nodes: [TEXT], paragraphData: {} }` | Body text |
-| `HEADING` | `{ type: "HEADING", id, nodes: [TEXT], headingData: { level: 2 } }` | Section headers (level 2–4) |
-| `CODE_BLOCK` | `{ type: "CODE_BLOCK", id, nodes: [TEXT], codeBlockData: { language: "javascript" } }` | Code snippets |
-| `BULLETED_LIST` | `{ type: "BULLETED_LIST", id, nodes: [LIST_ITEM] }` | Unordered lists |
-| `LIST_ITEM` | `{ type: "LIST_ITEM", id, nodes: [PARAGRAPH] }` | Items inside BULLETED_LIST |
-| `BLOCKQUOTE` | `{ type: "BLOCKQUOTE", id, nodes: [PARAGRAPH] }` | Pull quotes, callouts |
-| `TEXT` | `{ type: "TEXT", id: "", nodes: [], textData: { text: "...", decorations: [] } }` | Inline text (leaf node inside paragraphs, headings, etc.) |
-
-**Tips:**
-- Container nodes (PARAGRAPH, HEADING, etc.) need a unique `id` (use any string, e.g., `"n1"`, `"n2"`). TEXT nodes can use an empty string `""` for `id`.
-- TEXT nodes are always leaf nodes inside PARAGRAPH, HEADING, CODE_BLOCK, etc.
-- LIST_ITEM nodes contain PARAGRAPH nodes (not TEXT directly)
-- Mix at least 3 different node types per post for visual variety
-- Create all 3 posts in sequence (one `curl` call per post)
-
-> **Re-publish after PATCH:** If you update a published post (e.g., the image agent adds a cover image via PATCH after creation), it becomes `hasUnpublishedChanges: true`. The agent that PATCHes must call `POST /blog/v3/draft-posts/{draftPostId}/publish` to re-publish. (This seed scope does not attach media — see Step 3.)
-
-## Step 4: Verify
-
-Query published posts to confirm all 3 exist:
-
-```
-REST: POST https://www.wixapis.com/blog/v3/posts/query
-body: {
-  "query": {
-    "paging": { "limit": 10 }
-  }
-}
-```
-
-Confirm 3 posts are returned. Report post titles to the user.
-
-## Step 5: Return Results
-
-Emit a structured JSON block at the end of your completion message per `../shared/RETURN_CONTRACT.md`. Do **not** write a sidecar file. Include the created posts' `id` and `title` so the image agent can attach cover images by ID:
-
-```json
-{
-  "status": "complete",
-  "phase": "blog-seed",
-  "scope": "seed",
-  "summary": "Created and published {n} on-brand blog posts",
-  "data": {
-    "blogPosts": [
-      { "id": "<uuid>", "title": "<title>" }
-    ]
-  },
-  "files": [],
-  "errors": []
-}
-```
-
-The JSON block MUST be the last content in your message.

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

@@ -1,32 +0,0 @@
----
-name: blog-implementer
-description: "Implements blog vertical via Wix Blog app — @wix/blog SDK, @wix/ricos rich content, RSS/sitemap. Scopes: seed, components, pages. Extends references/shared/IMPLEMENTER.md."
----
-
-# Blog Implementer
-
-Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, prompt-inlined inputs (read only your `.wix/seeded.json` slice), return contract, style conventions, and common failure modes.
-
-## Scope routing
-
-| Scope | Phase | Reference |
-|-------|-------|-----------|
-| `seed` | Seed (post seeding via REST with Ricos content) | `./BLOG_CONTENT.md` |
-| `components` | Components (blog service module, RicosViewer, consts, astro.config sitemap) | `../astro/blog/BLOG_SETUP.md` |
-| `pages` | Pages (listing, detail, RSS, BlogPost layout — all under `src/pages/blog/*`; no shared-shell patch, so blog merges into one private build agent) | `../astro/blog/BLOG_PAGES.md` |
-
-Cover images are generated by the shared image agent (`image-phase-2-entity` scope) AFTER `seed` completes — not by this agent.
-
-## Files this vertical creates / contributes
-
-The `components` and `pages` scopes enumerate their own file lists — see `../astro/blog/BLOG_SETUP.md` (components) and `../astro/blog/BLOG_PAGES.md` (pages).
-
-## Blog-specific failure modes
-
-| Wrong | Right |
-|---|---|
-| `import { items } from "@wix/data"` for blog queries | `import { posts } from "@wix/blog"` — use the Blog SDK |
-| `<article set:html={post.content} />` | `<RicosViewer client:only="react" content={post.richContent} />` — content is Ricos format |
-| Skip `wixMetadata` on `[...slug].astro` | Required for Wix page routing + SEO |
-| Query posts without `RICH_CONTENT` fieldset | Always request `RICH_CONTENT` or `post.richContent` is undefined |
-| Scoped `<style>` for RicosViewer overrides | `<style is:global>` — React islands don't inherit scoped Astro styles |

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

@@ -1,246 +0,0 @@
-# Bookings — the booking flow (framework-agnostic logic)
-
-The booking logic — the step model, the shared state, and the exact `@wix` SDK
-sequence — is the **same on every frontend** (astro, react/vite, vue, plain HTML).
-This file is that shared logic. The per-framework wiring layers on top:
-
-- **astro** (`frontendBuild: wix`): `../astro/bookings/SERVICES_PAGES.md` (SSR read pages) + `../astro/bookings/COMPONENTS.md` (the client islands).
-- **own / static** (`frontendBuild: own`/`none`): `../custom/bookings/WIRING.md`.
-
-**Code examples are React** (`../astro/templates/bookings/*.tsx` + `bookingDriver.ts`).
-React is directly usable on astro islands and on react/vite. **On any other
-framework, translate the examples** — the SDK calls and payloads are identical;
-only the UI idiom (`useState`/`useEffect` → a store / `onMounted` / signals) and
-the client acquisition differ (see "Client identity" below).
-
-The flow 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, 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:
-
-```
-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.
-
-Mapping the steps onto pages/routes is the **target framework's choice** — translate
-the step model to whatever router the framework uses. The skill recommends the routes
-`/services`, `/services/[slug]`, `/booking-confirmation` (advertised in
-`../verticals/bookings.md`). On astro specifically, SSR the catalog + detail pages
-for SEO and run slots + form + book in a `client:only` island.
-
-## 2. Shared booking state
-
-Steps 1–4 build up one selection (this is exactly `BookParams` + `SelectedSlot`
-in `../astro/templates/bookings/bookingDriver.ts`):
-
-- **`service`** — the chosen service object (the booking step reads `service.payment` + `service.bookingPolicy`; 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
-store, route loaders + a provider, query-params). **Two rules that bite:**
-
-1. **Persist the selection before navigating.** When a step lives on its own
-   route, write the selection into the shared state (or the URL) *before* moving
-   on, and let the next step **rehydrate from the slug/URL** on direct load /
-   refresh. A persistent provider that does not re-init on in-app navigation will
-   otherwise show an empty next step.
-2. **The slug is the carry-across key.** `serviceSlug` (the service's
-   `mainSlug.name`) identifies the service across the slots + details steps;
-   resolve the full service from it when state is lost.
-
-## 3. The booking SDK sequence — `bookingDriver.ts`
-
-The whole booking — `createBooking → createCart → calculateCart → checkout-or-place`
-— is in **`../astro/templates/bookings/bookingDriver.ts`**, in plain `@wix` SDK
-calls (no React, no UI). **Use it as-is** (it is framework-agnostic); the booking
-step calls `book(params)` then branches on the result. Do not re-author the
-sequence — the payload shapes are exact and easy to get subtly wrong.
-
-```
-book({ service, slot, formSubmission, timezone }) →
-  createBooking(...)            // booking lands CREATED — the cart holds the seat
-  createCart(...)               // one catalog item per bookingId, appId = BOOKING_APP_ID, channel WEB
-  calculateCart(cartId)         // → { cart, summary }; totals on summary.priceSummary.total.amount
-  isCheckoutRequired(...) ?
-     → { CheckoutRequired, cartId }  // paid → navigateToCheckout(cartId, postFlowUrl) → Wix-hosted checkout
-     : placeOrder(cartId) → { CheckoutSkipped, orderId }   // free / pay-in-person → confirmation
-```
-
-Key facts the driver encodes (do not deviate):
-- **No `confirmBooking`** — `confirmBooking` is the classic Bookings server-side
-  confirm step (it moves a booking from `CREATED` to `CONFIRMED`). Here the **ecom
-  cart holds the seat** instead — `placeOrder` (free/offline) or the hosted checkout
-  (paid) drives confirmation — so a client-only site completes the whole flow with no
-  server elevation.
-- **ANY_RESOURCE fallback (staff)** — 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). 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`
-  → place; else checkout.
-- **Redirect shape** — paid bookings hand the cart to the Wix-hosted **ecom**
-  checkout: `createRedirectSession({ ecomCheckout: { checkoutId: cartId }, callbacks:{ postFlowUrl } })`.
-
-### Browse + availability (the read calls the steps make)
-
-Mirror what the Bookings SDK does (`services.queryServices` is the raw SDK, not a component):
-
-```js
-// Catalog (list) — the filter MUST include appId; pass conditionalFields, then .find().
-// Merge the optional category/location filters into the SAME filter object (§7):
-services.queryServices({
-  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
-
-// Single service by slug — the .eq() builder chain:
-services.queryServices({ conditionalFields: ["STAFF_MEMBER_DETAILS"] })
-  .eq("mainSlug.name", slug).eq("appId", BOOKING_APP_ID).limit(1).find();
-
-// Availability (APPOINTMENT) — serviceId is a single GUID STRING. 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.
-// 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`
-(no `Z`) with an explicit `timeZone`.
-
-## 4. The booking form — schema-driven (`@wix/forms`)
-
-The booking form is a **`@wix/forms` form** attached to the service
-(`service.form._id`, namespace `wix.bookings.v2.bookings`). Render it
-**schema-driven** — read the field list and render inputs by field type — the
-**same renderer the forms vertical uses** (`../astro/forms/CONTACT_FORM.md`):
-
-1. Fetch the form by `service.form._id` (`@wix/forms` `getForm`; server-side/elevated
-   where the framework allows). Read `form.formFields`.
-2. Keep `fieldType === "INPUT" && !hidden` **and** a recognized string
-   `componentType` (`TEXT_INPUT` / `PHONE_INPUT` / `DROPDOWN`). For each, take
-   `inputOptions.target`, `inputOptions.required`, `inputOptions.stringOptions.componentType`,
-   and the label from `inputOptions.stringOptions.{textInputOptions|dropdownOptions|phoneInputOptions}.label`.
-   **Skip complex, object-valued fields** — e.g. a multi-line `ADDRESS` — they carry
-   no string `componentType`; rendering them as a text input sends a string and
-   `createBooking` rejects it with **"must be object"**. The booking enforces only
-   the contact basics (`first_name`/`last_name`/`email`), so omitting an optional
-   complex field is safe (do **not** default unknown field types to a text input).
-3. Render generic inputs by `componentType`: `TEXT_INPUT` → text input,
-   `DROPDOWN` → select, `PHONE_INPUT` → `type=tel`; treat `identifier === "TEXT_AREA"`
-   (or `target` containing `message`) as a textarea (its `componentType` is still `TEXT_INPUT`).
-4. Collect the values into an object **keyed by each field's `target`** — that is
-   `formSubmission`. Pass it to `book()`. Only include fields the visitor filled;
-   never send a value for a field you didn't render.
-
-**Do not** submit `contactDetails`, and **do not** hardcode field names — key by
-`target`. The default booking form's targets are snake_case `first_name` /
-`last_name` / `email` / `phone`. Reference example: `../astro/templates/bookings/BookingForm.tsx`.
-
-## 5. The availability calendar (slots step)
-
-**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)
-
-The SDK calls are identical everywhere; only how you get the client differs:
-- **astro** — SSR read pages use the ambient `@wix/essentials` client
-  (`auth.elevate(services.queryServices)(...)`); browser islands call the `@wix`
-  modules **ambiently** too (the `@wix/astro` visitor client, like the ecom
-  `CartView` island) — no `createClient`/`OAuthStrategy`.
-- **own / static** — acquire a visitor client once:
-  `createClient({ modules, auth: OAuthStrategy({ clientId: appId }) })` and call
-  the same functions on it. CDN imports for `none`, bundled for `own`.
-
-## 7. 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,95 +0,0 @@
----
-name: bookings-implementer
-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
-
-Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, the `.wix/seeded.json` read pattern, the return contract, style conventions, and common failure modes.
-
-## The logic lives in one place
-
-The booking **logic** — the step model, the shared selection state, the exact
-`@wix` SDK sequence, and the schema-driven form — is framework-agnostic and lives
-in **`./FLOW.md`**. Read it first. The astro guides below are the astro *wiring* of
-that logic; the code examples under `<SKILL_ROOT>/references/astro/templates/bookings/`
-are React (the astro islands use them directly). For an own/static build, the wiring guide is
-`../custom/bookings/WIRING.md` (same logic, client-side `@wix/sdk`).
-
-## Scope routing
-
-| Scope | Phase | Reference |
-|-------|-------|-----------|
-| `seed` | Seed — create services (and staff) via the Wix Bookings REST API | `./SERVICES_DATA.md` |
-| `components` | Components — the client islands (week calendar, schema-driven form, the flow coordinator) | `./FLOW.md` + `../astro/bookings/COMPONENTS.md` |
-| `pages` | Pages — `/services` listing, `/services/[slug]` detail, `/booking-confirmation`, + nav/home links | `./FLOW.md` + `../astro/bookings/SERVICES_PAGES.md` |
-
-## Templates — read and adapt (don't invent)
-
-Canonical examples live at `<SKILL_ROOT>/references/astro/templates/bookings/`.
-Your `components` and `pages` scopes **read these and adapt them** — adapt brand
-copy, headings, and styling; keep the SDK calls, payload shapes, and the data
-flow (re-authoring the SDK wiring from scratch is the main source of API-shape bugs).
-
-Components (`components` scope — TSX only, no CSS):
-- `<SKILL_ROOT>/references/astro/templates/bookings/AvailabilityCalendar.tsx` — the week calendar (week strip → the day's slots; APPOINTMENT via `availabilityTimeSlots`, CLASS via `eventTimeSlots`).
-- `<SKILL_ROOT>/references/astro/templates/bookings/BookingForm.tsx` — the schema-driven form (renders the `@wix/forms` field list, keys values by `target`) that drives `bookingDriver.book()`.
-- `<SKILL_ROOT>/references/astro/templates/bookings/ServiceBookingFlow.tsx` — the coordinator island (holds the selected slot; calendar → form → redirect).
-
-Pages (`pages` scope):
-- `<SKILL_ROOT>/references/astro/templates/bookings/ServiceCard.astro`
-- `<SKILL_ROOT>/references/astro/templates/bookings/services/index.astro`, `<SKILL_ROOT>/references/astro/templates/bookings/services/[slug].astro`
-- `<SKILL_ROOT>/references/astro/templates/bookings/booking-confirmation.astro`
-
-### Pre-copied by the orchestrator (do NOT write these yourself)
-Mechanical, brand-agnostic — the orchestrator copies them before dispatch (BUILD-astro.md § build wave). Rely on them at the listed paths:
-- `src/components/bookingDriver.ts` ← `<SKILL_ROOT>/references/astro/templates/bookings/bookingDriver.ts` — the booking SDK sequence (`book()`, `navigateToCheckout()`). The islands import it; never re-author it.
-- `src/components/SeoTags.astro` ← `<SKILL_ROOT>/references/astro/templates/bookings/SeoTags.astro` — renders `service.seoData.tags`; imported by `services/[slug].astro`.
-- `src/styles/components-bookings.css` ← `<SKILL_ROOT>/references/astro/templates/bookings/components-bookings.css` — the flow's component classes.
-
-If a pre-copied file is missing at runtime, that's an orchestrator-side bug — return `status: "partial"` with `errors: [{code: "UTILITY_TEMPLATE_NOT_PRECOPIED", path: "<missing>"}]`; do not author your own version.
-
-## Pre-return file-existence assertion (pages scope)
-
-Before returning `status: "complete"` from `pages`, verify on disk:
-- `src/pages/services/index.astro`
-- `src/pages/services/[slug].astro`
-- `src/pages/booking-confirmation.astro`
-
-If any declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]`.
-
-## Dependencies (Setup installs these — see SETUP.md)
-
-`@wix/bookings @wix/essentials @wix/forms @wix/redirects @wix/auto_sdk_ecom_cart-v-2`.
-`@wix/forms` renders the booking-form schema; `@wix/redirects` + `@wix/auto_sdk_ecom_cart-v-2` run the cart/checkout sequence.
-
-## CSS ownership — bookings pack
-
-Bookings-specific CSS lives in `src/styles/components-bookings.css` (pre-copied — see above), NOT in `global.css`. Classes the pack owns: `.service-card*`, `.service-grid`, `.availability-*`, `.time-slot*`, `.booking-*`. If `global.css` ships a partial rule for any of these, flag it (`{code:"GLOBAL_CSS_LEAK", class:"<name>"}`) and override in `components-bookings.css`.
-
-## Bookings-specific failure modes
-
-| Wrong | Right |
-|-------|-------|
-| Stop after `createBooking` returns | `createBooking` leaves the booking **`CREATED`**. The seat is held by the **ecom Cart V2**: continue `createCart → calculateCart → isCheckoutRequired ? hosted-checkout redirect : placeOrder`. The whole sequence is in `bookingDriver.ts` — use it. |
-| Hardcode `selectedPaymentOption: "ONLINE"` on `createBooking` | **Derive** it from the service: `online && !inPerson → "ONLINE"`, `!online && inPerson → "OFFLINE"`, else `"ONLINE"`. A free / pay-in-person service is the only kind that reaches `placeOrder`, and booking it `ONLINE` makes the cart reject it with **`INSUFFICIENT_INVENTORY`** (`available_quantity: 0`). `bookingDriver.ts` derives this for you (don't pass `selectedPaymentOption` to `book()`). |
-| Pass `contactDetails` to `createBooking` | Pass **`formSubmission`**, keyed by each field's **`target`** (default booking form: snake_case `first_name`/`last_name`/`email`/`phone`). `contactDetails` is what Wix derives back onto the response. |
-| Hardcode the booking-form fields | Render the form **schema-driven**: read `service.form._id`'s fields via `@wix/forms`, render by `componentType`, key values by `target` (same renderer as `../astro/forms/CONTACT_FORM.md`). |
-| Render every form field as a text input (default unknown types to `TEXT_INPUT`) | Render **only** fields with a recognized string `componentType` (`TEXT_INPUT`/`PHONE_INPUT`/`DROPDOWN`). **Skip complex, object-valued fields** (e.g. the default booking form's multi-line `ADDRESS`) — sending a string for them fails `createBooking` with **"must be object"**. Only `first_name`/`last_name`/`email` are enforced, so skipping optional complex fields is safe. |
-| Call `queryServices` without an `appId` filter | Always include `appId` (`13d21c63-…`) in the filter. List: `queryServices({ query:{ filter:{ appId }, paging }, conditionalFields:["STAFF_MEMBER_DETAILS"] }).find()`. Single: the `.eq("mainSlug.name", slug).eq("appId", …).limit(1).find()` builder chain. |
-| Build `createClient({ auth: OAuthStrategy({ clientId: import.meta.env.* }) })` in `.astro` SSR | The `*_WIX_CLIENT_ID` env var is client-only → `undefined` at server render → 500. SSR reads use the ambient `@wix/essentials`: `auth.elevate(services.queryServices)(...)`. |
-| Build an `OAuthStrategy` client inside an astro browser island | Astro islands call the `@wix` modules **ambiently** (the `@wix/astro` visitor client, like the ecom `CartView`) — no `createClient`. (Own/static builds DO use `OAuthStrategy` — `../custom/bookings/WIRING.md`.) |
-| Pass UTC ISO strings to `listAvailabilityTimeSlots` | Use **local** date strings `YYYY-MM-DDThh:mm:ss` (no `Z`) + a separate `timeZone`. |
-| `availability.queryAvailability` / `import { availability }` | APPOINTMENT → `availabilityTimeSlots.listAvailabilityTimeSlots({ serviceId: <string> })`; CLASS → `eventTimeSlots.listEventTimeSlots({ serviceIds: [<string>] })`. The `availability` namespace does not exist. |
-| Read slot time from `timeSlot.slot.startDate` | Slot fields are at the **top level**: `localStartDate`, `localEndDate`, `scheduleId` (APPOINTMENT). CLASS slots carry `eventInfo.eventId` and have **no** `scheduleId`. |
-| Dump every slot in one flat, time-only grid | **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 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. |