@wix/agent-skills 1.19.1 → 1.20.0

package/skills/wix-app/references/service-plugin/BOOKING-POLICY.md

@@ -0,0 +1,65 @@
+# Booking Policy Service Plugin Reference
+
+## Overview
+
+The Booking Policy SPI lets you provide dynamic booking policies instead of a service's single static policy. Wix calls your `listBookingPolicies` handler whenever it needs to know how early/late a service can be booked or whether online booking is allowed — for example, when a customer loads the booking calendar or books a service. Your implementation can return a different policy for the same service based on your own criteria (e.g., customer type, time of year).
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` on the docs URL to get the full request/response types.
+
+| Handler | Docs URL |
+| --- | --- |
+| `listBookingPolicies` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policy-service-plugin/list-booking-policies?apiView=SDK |
+
+The request's `serviceIds` array has 1–8 service GUIDs. Your response's `bookingPolicies` array must contain exactly one policy per requested service, **in the same order** — all fields are required unless the schema marks them optional.
+
+## Example: Different Early-Booking Windows by Service Category
+
+```typescript
+import { bookingPolicy } from "@wix/bookings/service-plugins";
+import { auth } from "@wix/essentials";
+import { services } from "@wix/bookings";
+
+bookingPolicy.provideHandlers({
+  listBookingPolicies: async (payload) => {
+    const { request } = payload;
+    const { serviceIds } = request;
+
+    // queryServices is a fluent query builder, not a request-object call — it returns { items }, not { services }.
+    const elevatedQueryServices = auth.elevate(services.queryServices);
+    const { items: matchedServices } = await elevatedQueryServices().in('_id', serviceIds).find();
+    const serviceById = new Map((matchedServices ?? []).map((s) => [s._id, s]));
+
+    const bookingPolicies = serviceIds.map((serviceId) => {
+      const isPremium = serviceById.get(serviceId)?.category?.name === "Premium";
+
+      return {
+        serviceId,
+        limitEarlyBooking: {
+          enabled: true,
+          earliestBookingInMinutes: isPremium ? 20160 : 10080, // 14 vs 7 days
+        },
+        limitLateBooking: {
+          enabled: true,
+          latestBookingInMinutes: 1440, // 1 day
+        },
+        onlineBooking: { enabled: true },
+      };
+    });
+
+    return { bookingPolicies };
+  },
+});
+```
+
+## Manual Setup Required
+
+None. Confirmed the overall availability/policy pipeline this plugin feeds into is live and enforcing real constraints (a dashboard booking attempt was correctly rejected for being outside staff working hours) — this SPI's own specific early/late-booking window differentiation wasn't isolated independently of that pipeline, but no dashboard configuration is needed beyond having the app installed and released.
+
+## Key Implementation Notes
+
+1. **One policy per service, same order** — the response array must line up positionally with the request's `serviceIds`; don't omit or reorder entries.
+2. **All fields required unless marked optional** — return `limitEarlyBooking`, `limitLateBooking`, and `onlineBooking` fully populated rather than partially.
+3. **Called on the hot path** — this handler runs whenever availability is queried or a booking is made, so keep it fast and avoid unnecessary external calls.
+4. **Elevate permissions** — use `auth.elevate` when querying Wix APIs (e.g., service details) from the handler.

package/skills/wix-app/references/service-plugin/BOOKINGS-PRICING.md

@@ -0,0 +1,71 @@
+# Bookings Pricing Provider Service Plugin Reference
+
+## ⚠️ Requires manual sign-up before it's live
+
+Unlike every other SPI in this skill, this integration isn't self-serve. Before Wix will ever call your handler on a real site, email `bookings-integration@wix.com` with subject "Bookings Pricing Integration" and include: your business type, a few words about your business/market, the URL of the site hosting your app, and your app ID. Wix reviews the request and replies by email. **Implement and build the plugin, but tell the user this sign-up step is required and still pending** — don't present the feature as live just because the code compiles and builds.
+
+## Overview
+
+The Bookings Pricing Provider lets your app calculate custom prices for bookings — regional tax, discounts for specific customer types, or any combination — instead of Wix's standard per-variant pricing. Once installed, your plugin becomes the **sole source of price** for the service: Wix does not hand you a pre-computed subtotal to adjust, so if you need a base price, derive or store it yourself (e.g. read it from the service via `@wix/bookings`, or from your own config).
+
+Wix calls your handler only *after* a booking already exists (`booking._id` is set) — this SPI cannot be used in advance to preview a price list. There is only one handler; there's no separate "preview" handler.
+
+**FQDN**: `wix.bookings.pricing.v1.pricing_provider`
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` on the docs URL to get the full request/response types. Note: the public docs page for this SPI still describes an older REST/webhook-only integration and does not yet reflect the `provideHandlers` SDK wrapper below — trust what `wix generate` actually scaffolds and the installed `@wix/auto_sdk_bookings_pricing-provider` types over the doc's prose/code samples, but its **field descriptions** (e.g. `booking.contactDetails.fullAddress.subdivision`) and the sign-up requirement above are still accurate.
+
+| Handler | Docs URL |
+| --- | --- |
+| `calculatePrice` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/pricing/pricing-integration-service-plugin/calculate-price |
+
+Your handler receives `{ request: { booking }, metadata }`, where `booking` is the full [booking object](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-writer-v2/booking-object) — pull whatever you need from it (e.g. `booking.contactDetails.fullAddress.subdivision` for regional tax, `booking.totalParticipants` / `booking.participantsChoices` for participant count). Return **either**:
+
+- `{ calculatedPrice: <number> }` — a numeric price. The site owner's dashboard can perform further calculations on top of it, but calling the Preview Price API on a booking priced this way fails.
+- `{ priceDescription: <string> }` — a textual price description — lets Preview Price succeed, but Wix cannot do further numeric calculations on it.
+
+Decide which shape to return before you write the handler; you can't mix both per request.
+
+## Example: Regional Tax From Contact Address
+
+```typescript
+import { pricingProvider } from "@wix/bookings/service-plugins";
+
+const TAX_RATE_BY_SUBDIVISION: Record<string, number> = {
+  CA: 0.0725,
+  NY: 0.08,
+};
+
+const BASE_PRICE_PER_PARTICIPANT = 100; // wire this to your real per-service price
+
+pricingProvider.provideHandlers({
+  calculatePrice: async (payload) => {
+    const { booking } = payload.request;
+    if (!booking) {
+      return { calculatedPrice: 0 };
+    }
+
+    const participants =
+      booking.totalParticipants ??
+      (booking.participantsChoices?.serviceChoices ?? []).reduce(
+        (sum, choice) => sum + (choice.numberOfParticipants ?? 0),
+        0
+      ) ??
+      1;
+
+    const subdivision = booking.contactDetails?.fullAddress?.subdivision;
+    const taxRate = subdivision ? TAX_RATE_BY_SUBDIVISION[subdivision] ?? 0 : 0;
+
+    return { calculatedPrice: BASE_PRICE_PER_PARTICIPANT * participants * (1 + taxRate) };
+  },
+});
+```
+
+## Key Implementation Notes
+
+1. **Sign-up is mandatory and manual** — see the warning above; there is no self-serve activation flow.
+2. **You own pricing entirely** — the request doesn't carry a merchant-configured base price; compute or look one up yourself.
+3. **Only called after booking creation** — you cannot use this SPI to display prices in advance of a booking existing.
+4. **Pick one response shape** — a numeric `calculatedPrice` (lets the dashboard add further calculations, but breaks Preview Price) or a `priceDescription` (the reverse). Decide once, per your app's use case.
+5. **Confirm with the user before promising this feature** — since activation depends on an out-of-band email approval, tell the user this step is required rather than assuming the integration is live once code is deployed.

package/skills/wix-app/references/service-plugin/BOOKINGS-STAFF-SORTING.md

@@ -36,10 +36,12 @@ import { extendedBookings } from "@wix/bookings";
 staffSorting.provideHandlers({
   sortStaffMembers: async (payload) => {
     const { request } = payload;
-    const { availableResourceIds, slot } = request;
+    // availableResourceIds is optional on the request type — default it, or
+    // spreading/iterating it below fails `tsc` with "possibly undefined."
+    const { availableResourceIds = [], slot } = request;
 
     const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
-    const elevatedQuery = auth.elevate(extendedBookings.query);
+    const elevatedQuery = auth.elevate(extendedBookings.queryExtendedBookings);
     const result = await elevatedQuery({
       filter: {
         "bookedEntity.item.slot.resource.id": { "$in": availableResourceIds },
@@ -73,10 +75,16 @@ staffSorting.provideHandlers({
 });
 ```
 
+## Manual Setup Required
+
+None. Confirmed live with a service that has 2 assigned staff — the dashboard's "Add booking" flow resolved a specific staff member from the plugin's sorted order, and the booking created successfully with no errors. No dashboard configuration is needed beyond having the app installed and released, and the service having 2+ staff assigned to genuinely exercise the sort.
+
 ## Key Implementation Notes
 
 1. **Return all IDs** - You must return every ID from `availableResourceIds`, just reordered
 2. **Performance matters** - Keep logic fast; the booking flow waits for your response
 3. **Elevate permissions** - Use `auth.elevate` when querying Wix APIs from the handler
 4. **Deterministic sorting** - Use a tiebreaker (e.g., resource ID) when priorities are equal
-5. **Graceful degradation** - If your external data source is unavailable, return the original order rather than failing
+5. **Use `queryExtendedBookings`, not `query`** — `extendedBookings.query` is deprecated. `queryExtendedBookings` takes the same `filter`/`cursorPaging` shape, so it's a drop-in replacement; confirmed live after switching.
+6. **`availableResourceIds` is optional on the request type** — default it to `[]` when destructuring, or spreading/iterating it fails `tsc` with "possibly undefined."
+7. **Graceful degradation** - If your external data source is unavailable, return the original order rather than failing

package/skills/wix-app/references/service-plugin/BOOKINGS-VALIDATION.md

@@ -0,0 +1,137 @@
+# Bookings Validation Service Plugin Reference
+
+## Overview
+
+The Bookings Validation SPI lets you implement custom validation logic for booking operations. When a customer creates, cancels, or reschedules a booking (single-service or multi-service), Wix calls the handler matching that operation before it executes. Return `valid: true` to allow the operation or `valid: false` to block it with a customer-facing message.
+
+`bookingsValidation.provideHandlers` requires all six handlers in the object literal — TypeScript rejects a partial object even though you may only care about one or two targets. For the ones you don't have real logic for, provide a no-op that returns an empty `results`/`singleServiceBookingResults` array (an empty array is a no-op: "Omitting an item's result treats it as valid," and an empty results array omits every item's result). Confirmed live: `wix generate` itself scaffolds all six handlers by default — that's not incidental boilerplate you can trim.
+
+## Handlers
+
+| Handler | Validation target | On error/timeout |
+| --- | --- | --- |
+| `validateBeforeCreate` | `CREATE` | Blocked (fail-closed) |
+| `validateBeforeCancel` | `CANCEL` | Blocked (fail-closed) |
+| `validateBeforeReschedule` | `RESCHEDULE` | Continues (fail-open) |
+| `validateBeforeCreateMultiService` | `CREATE_MULTI_SERVICE` | Blocked (fail-closed) |
+| `validateBeforeCancelMultiService` | `CANCEL_MULTI_SERVICE` | Blocked (fail-closed) |
+| `validateBeforeRescheduleMultiService` | `RESCHEDULE_MULTI_SERVICE` | Continues (fail-open) |
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` on each docs URL to get the full request/response types.
+
+| Handler | Docs URL |
+| --- | --- |
+| `validateBeforeCreate` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-create?apiView=SDK |
+| `validateBeforeCancel` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-cancel?apiView=SDK |
+| `validateBeforeReschedule` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-reschedule?apiView=SDK |
+| `validateBeforeCreateMultiService` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-create-multi-service?apiView=SDK |
+| `validateBeforeCancelMultiService` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-cancel-multi-service?apiView=SDK |
+| `validateBeforeRescheduleMultiService` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-reschedule-multi-service?apiView=SDK |
+
+**Correlation differs by handler — this is easy to get wrong, and doing so fails `tsc`, not just at runtime:**
+
+| Handler(s) | Item shape | Max items | Result correlates by |
+| --- | --- | --- | --- |
+| `validateBeforeCreate`, `validateBeforeCreateMultiService` | `{ itemIndex, booking }` | 40 | `itemIndex` |
+| `validateBeforeCancel`, `validateBeforeReschedule`, and their multi-service equivalents | `{ booking }` — **no `itemIndex` field at all** | 8 | `bookingId` (from `booking._id`) |
+
+Only the create family carries `itemIndex`; cancel and reschedule items don't have one, so their results key on the booking's own ID instead. The single-service response field is `results`; the multi-service response field is `singleServiceBookingResults` — same per-item shape either way. Omitting an item's result treats it as valid. `contactDetails` and resource `name`/`email` fields are redacted before reaching your handler.
+
+## Example: Membership Limit and Cancellation Fee
+
+This example enforces a pricing-plan booking limit on create, and blocks late cancellations.
+
+```typescript
+import { bookingsValidation } from "@wix/bookings/service-plugins";
+import { auth } from "@wix/essentials";
+import { orders } from "@wix/pricing-plans";
+
+bookingsValidation.provideHandlers({
+  validateBeforeCreate: async (payload) => {
+    const { request } = payload;
+
+    const results = await Promise.all(
+      (request.items ?? []).map(async (item) => {
+        const memberId = item.booking?.contactDetails?.contactId;
+        if (!memberId) {
+          return { itemIndex: item.itemIndex, result: { valid: true } };
+        }
+
+        // Not orders.listOrders — that method doesn't exist on @wix/pricing-plans.
+        // managementListOrders takes flat buyerIds/orderStatuses, not a nested filter.
+        const elevatedListOrders = auth.elevate(orders.managementListOrders);
+        const { orders: activeOrders } = await elevatedListOrders({
+          buyerIds: [memberId],
+          orderStatuses: ["ACTIVE"],
+        });
+
+        if ((activeOrders ?? []).length === 0) {
+          return {
+            itemIndex: item.itemIndex,
+            result: {
+              valid: false,
+              invalidReason: {
+                message: "An active membership is required to book this service.",
+                fieldViolations: [
+                  { field: "booking.contactDetails", description: "No active membership found.", code: "PLAN_EXPIRED" },
+                ],
+              },
+            },
+          };
+        }
+
+        return { itemIndex: item.itemIndex, result: { valid: true } };
+      })
+    );
+
+    return { results };
+  },
+
+  validateBeforeCancel: async (payload) => {
+    const { request } = payload;
+
+    // Cancel items carry no itemIndex — correlate results by the booking's own _id.
+    const results = (request.items ?? []).map((item) => {
+      const bookingId = item.booking?._id ?? undefined;
+      const startDate = item.booking?.bookedEntity?.slot?.startDate;
+      const hoursUntilStart = startDate
+        ? (new Date(startDate).getTime() - Date.now()) / (1000 * 60 * 60)
+        : Infinity;
+
+      if (hoursUntilStart < 24) {
+        return {
+          bookingId,
+          result: {
+            valid: false,
+            invalidReason: { message: "Cancellations within 24 hours of the appointment aren't allowed." },
+          },
+        };
+      }
+
+      return { bookingId, result: { valid: true } };
+    });
+
+    return { results };
+  },
+
+  // Unimplemented targets still need a handler — see the note above the example.
+  validateBeforeReschedule: async () => ({ results: [] }),
+  validateBeforeCreateMultiService: async () => ({ singleServiceBookingResults: [] }),
+  validateBeforeCancelMultiService: async () => ({ singleServiceBookingResults: [] }),
+  validateBeforeRescheduleMultiService: async () => ({ singleServiceBookingResults: [] }),
+});
+```
+
+## Manual Setup Required
+
+None — confirmed live via the real Cancel Booking API: a cancellation under 24h was correctly blocked with a structured `428 VALIDATION_FAILED`, and one over 24h correctly succeeded. Wix calls this plugin automatically on the relevant booking operations once the app is installed and released.
+
+## Key Implementation Notes
+
+1. **Bulk requests, per-item results** — return a result for every item you received (keyed by `itemIndex` on create, by `bookingId` on cancel/reschedule — see the correlation table above); a missing entry is treated as valid, not rejected.
+2. **Respond fast** — `validateBeforeCreate`, `validateBeforeCancel`, and their multi-service equivalents fail-closed (block the operation) on error or timeout; `validateBeforeReschedule` and its multi-service equivalent fail-open (allow it).
+3. **Multiple providers run concurrently** — if other apps also register validators for the same target, any single rejection blocks the operation.
+4. **Write customer-facing messages** — `invalidReason.message` and `fieldViolations[].description` are shown to the customer; keep them clear and free of internal jargon. `fieldViolations[].code` is for your own programmatic handling, not display.
+5. **Elevate permissions** — use `auth.elevate` when querying Wix APIs (e.g., pricing plan orders) from the handler.

package/skills/wix-app/references/service-plugin/DISCOUNT-TRIGGERS.md

@@ -20,6 +20,10 @@ Before implementing, call `ReadFullDocsMethodSchema` on each docs URL to get the
 | `getEligibleTriggers` | https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/custom-discount-triggers-integration-service-plugin/get-eligible-triggers?apiView=SDK |
 | `listTriggers` | https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/custom-discount-triggers-integration-service-plugin/list-triggers?apiView=SDK |
 
+## ⚠️ `identifier` must be echoed from the request, never invented
+
+`getEligibleTriggers` receives `request.triggers[]`, each with a `customTrigger._id` and an `identifier` Wix generated for that occurrence. Your response's `eligibleTriggers[i].identifier` **must be the exact same value** from the matching `request.triggers[i].identifier` — it's how Wix correlates your answer back to the discount rule that asked. A hardcoded or self-invented `identifier` never matches, so the discount silently never applies — confirmed live: the discount rule stays wired up and no error is raised, it just never fires.
+
 ## Example: Happy Hour and Digital Products Triggers
 
 This example defines two custom triggers: a time-based "Happy Hour" trigger and a product-type-based "Digital Sale" trigger.
@@ -30,22 +34,16 @@ import { customTriggers } from "@wix/ecom/service-plugins";
 customTriggers.provideHandlers({
   getEligibleTriggers: async (payload) => {
     const { request, metadata } = payload;
-    // Use the `request` and `metadata` received from Wix and
-    // apply custom logic.
-    return {
-      // Return your response exactly as documented to integrate with Wix.
-      // Return value example:
-      eligibleTriggers: [
-        {
-          customTriggerId: "my-happy-hour-trigger",
-          identifier: "123",
-        },
-        {
-          customTriggerId: "my-digital-sale-trigger",
-          identifier: "234",
-        },
-      ],
-    };
+    // request.triggers tells you which trigger occurrences Wix is asking about —
+    // filter to the ones you recognize and echo back their `identifier` exactly.
+    const eligibleTriggers = (request.triggers ?? [])
+      .filter((t) => t.customTrigger?._id === "my-happy-hour-trigger" /* + your eligibility check */)
+      .map((t) => ({
+        customTriggerId: "my-happy-hour-trigger",
+        identifier: t.identifier,
+      }));
+
+    return { eligibleTriggers };
   },
   listTriggers: async (payload) => {
     const { request, metadata } = payload;
@@ -79,3 +77,12 @@ customTriggers.provideHandlers({
 2. **Both handlers required** - You must implement both `getEligibleTriggers` and `listTriggers`
 3. **Dynamic eligibility** - `getEligibleTriggers` is called during checkout to determine which triggers are currently active
 4. **Static list** - `listTriggers` provides the master list of all possible triggers for configuration in the Wix dashboard
+5. **Manual step required, every time** — this plugin only supplies *eligibility*. It has no visible effect until the merchant creates an Automatic Discount that uses your trigger. Tell the user this step is required; don't imply the discount is live just because the plugin is installed. Confirmed live, click-by-click in the dashboard:
+   1. Go to **Catalog** (left sidebar) → **Discounts** → **Automatic Discounts**.
+   2. Click **Create Discount**.
+   3. Pick a discount type (e.g. **Standard discount**) and click **Continue**.
+   4. Under **Offer** → **"Are there any requirements?"**, check **Custom requirement**.
+   5. A dropdown appears next to it — click it and select your trigger by the `name` your `listTriggers` handler returned for it (e.g. "Happy Hour 16:00-18:00"). It only shows up here once your app is installed and `listTriggers` includes it — there's no dashboard flow to type in an arbitrary trigger ID.
+   6. Fill in the discount's offer/eligibility/dates as normal, then click **Save**.
+
+   Note: the dialog's own **"Create New"** button under that dropdown only offers Wix's *built-in* requirement templates (email domain, first purchase, order count, etc.) — it does not create a new app-linked custom trigger. Your trigger must already be coming back from `listTriggers` to appear in the dropdown at all.

package/skills/wix-app/references/service-plugin/GIFT-CARDS.md

@@ -67,6 +67,10 @@ giftVouchersProvider.provideHandlers({
 });
 ```
 
+## Manual Setup Required
+
+No dashboard configuration beyond installing the app. But there's nothing to `redeem`/`getBalance` against until a real gift card exists — a customer (or you, via the Wix Gift Cards app's own purchase/issuance flow) must actually buy or be issued a gift card first. You can't shortcut this by calling `redeem` with a made-up code; the code has to correspond to a gift card your provider recognizes as real. Test by issuing a real gift card through the site's own gift-card purchase flow, then redeeming it at checkout.
+
 ## Singular Constraint
 
 `GIFT_CARDS_PROVIDER` is **singular** — only one component of this type is allowed per app. Do not scaffold or include two Gift Cards service plugins in the same app.

package/skills/wix-app/references/service-plugin/PAYMENT-SETTINGS.md

@@ -45,7 +45,6 @@ paymentSettings.provideHandlers({
       };
     }
   },
-  getPaymentSettingsForCheckout: async () => ({ blockedPaymentOptions: [] }),
 });
 ```
 
@@ -84,10 +83,13 @@ paymentSettings.provideHandlers({
       };
     }
   },
-  getPaymentSettingsForCheckout: async () => ({ blockedPaymentOptions: [] }),
 });
 ```
 
+## Manual Setup Required
+
+No dashboard configuration beyond installing the app — Wix calls this SPI automatically once installed. The one real prerequisite: **a payment provider must already be connected** on the site (Wix Payments or another provider), or there's nothing for `requires3dSecure` to apply to. You can't exercise this handler with just a Cart `calculate`/`refresh` call — it only fires during actual payment submission (a customer entering card details), so verifying it end-to-end needs a real or sandbox payment attempt, not just an API-level cart inspection.
+
 ## Key Implementation Notes
 
 1. **Payment provider required** - Site must have a payment provider connected to collect payments

package/skills/wix-app/references/service-plugin/REALTIME-PERMISSIONS.md

@@ -0,0 +1,45 @@
+# Realtime Permissions Provider Service Plugin Reference
+
+## Overview
+
+The Realtime Permissions Provider SPI controls who can receive messages on your app's [Wix Realtime](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/introduction) channels. When a subscriber from another app attempts a cross-app subscription to one of your channels, Wix calls your `checkSubscriberPermissions` handler and waits synchronously for the answer. Without a registered provider, Wix denies all cross-app subscription attempts by default.
+
+This is the only SPI outside eCommerce and Bookings — it belongs to the Realtime module.
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` on the docs URL to get the full request/response types.
+
+| Handler | Docs URL |
+| --- | --- |
+| `checkSubscriberPermissions` | https://dev.wix.com/docs/sdk/core-modules/realtime/extensions/realtime-permissions-provider/check-subscriber-permissions |
+
+The request gives you the `channel` (`name` + optional `resourceId`), the `subscriber` (`type`: `ADMIN` / `MEMBER` / `VISITOR`, and `_id`), and `requestingAppId` (the app attempting the subscription, may be empty). Return `{ read: true }` to allow, `{ read: false }` to deny.
+
+## Example: Allow Members and Admins, Deny Visitors
+
+```typescript
+import { realtimePermissionsProvider } from "@wix/realtime/service-plugins";
+
+realtimePermissionsProvider.provideHandlers({
+  checkSubscriberPermissions: async (payload) => {
+    const { request } = payload;
+    const { subscriber, channel } = request;
+
+    if (channel?.name === "public-updates") {
+      return { read: true };
+    }
+
+    return { read: subscriber?.type !== "VISITOR" };
+  },
+});
+```
+
+## Key Implementation Notes
+
+1. **The generated stub may include a `write` field — remove it.** `wix generate` for this `pluginType` has been observed scaffolding a response of `{ read: true, write: false }`, but `CheckSubscriberPermissionsResponse` only has `read?: boolean`. Confirm against the installed `@wix/auto_sdk_duplexer_realtime-permissions-provider` types if `tsc` doesn't catch it for you.
+2. **`channel` and `subscriber` are both optional on the request** — `channel?: Channel`, `subscriber?: Subscriber`. Accessing `.name`/`.type` without the `?.` above fails `tsc` with "possibly undefined."
+3. **Deny with data, not errors** — return `{ read: false }` for normal policy denials. Only throw `InvalidArgumentError` when the request itself is invalid or missing data; any other thrown error, timeout, or unreachable service makes Wix deny the subscription with a 503.
+4. **Respond quickly** — the call is synchronous and blocks the subscription attempt; a slow handler delays it, and a non-responsive one causes a 503 denial.
+5. **Be consistent** — the same channel, subscriber, and context should always yield the same decision.
+6. **No provider means no cross-app access** — until you implement this SPI, all cross-app subscription attempts to your channels are denied by default.

package/skills/wix-app/references/service-plugin/SHIPPING-RATES.md

@@ -53,6 +53,21 @@ shippingRates.provideHandlers({
 });
 ```
 
+## ⚠️ Manual setup required — installing the app isn't enough
+
+Like Additional Fees and Payment Settings, this plugin only supplies rates when Wix actually asks it to. Unlike those two, **it isn't asked automatically** — the merchant must explicitly turn your app on as a delivery carrier for a shipping region before Wix calls `getShippingRates` for it. Tell the merchant to do this in the dashboard (confirmed live, click-by-click):
+
+1. Go to **Settings** (left sidebar) → under **Business solutions**, click **Shipping, delivery & fulfillment**.
+2. Find the region to enable the carrier for (e.g. **Domestic** or **International**) and click **Manage Your Apps** in that region's header.
+3. In the **"Manage your installed apps"** dialog, check the box next to your app's name.
+4. A **backup rate** section appears (checked by default) with a **Shipping name** and **Rate at checkout** field — this is what Wix falls back to if your plugin errors or times out. Fill these in (or leave the defaults) — Wix requires a backup rate here, same as the API's `backupRate`.
+5. Optionally check **Add a handling fee to every order**.
+6. Click **Save**.
+
+Confirmed live: enabling the carrier this way registers it with no errors. Whichever specific rate a given customer sees selected by default (this carrier's vs. another installed one's) is resolved at checkout-page render time, not by the Cart `calculate`/`refresh` endpoints — verify the actual customer-facing rate on the live checkout page, not from a raw API response alone.
+
+(The same thing can be done via the [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/add-delivery-carrier) API if you're scripting site setup yourself, but for a merchant using your app, send them to the dashboard steps above — not a raw API call.)
+
 ## Singular Constraint
 
 `ECOM_SHIPPING_RATES` is **singular** — only one component of this type is allowed per app. Do not scaffold or include two Shipping Rates service plugins in the same app.

package/skills/wix-app/references/service-plugin/TOOLS_PROVIDER.md

@@ -45,6 +45,10 @@ toolsProvider.provideHandlers({
 });
 ```
 
+## Manual Setup Required
+
+This handler is only invoked by the real Wix AI assistant deciding a tool is relevant — there's no direct API to force-invoke a specific tool for testing. Two things must both be true before it can fire at all: (1) a paired `APP_TOOLS` extension declares the tool with `activated: true` (see [APP_TOOLS.md](../APP_TOOLS.md)), and (2) a user actually asks the AI assistant something the tool's `description` matches. Verify by asking the assistant a matching question on the live site, not by calling this handler directly.
+
 ## Key Implementation Notes
 
 1. **Route on `methodName`** — use a `switch` or map to dispatch to the right handler logic

package/skills/wix-app/references/service-plugin/VALIDATIONS.md

@@ -43,6 +43,10 @@ validations.provideHandlers({
 });
 ```
 
+## Manual Setup Required
+
+None — confirmed live. Once the app is installed and released, Wix calls this plugin automatically on every cart/checkout calculation; no dashboard configuration or extra API call is needed to "turn it on."
+
 ## Key Implementation Notes
 
 1. **Return empty array when valid** - Return `{ violations: [] }` when no validation issues

package/skills/wix-base44-connector/SKILL.md

@@ -23,8 +23,8 @@ they also surface from a search that began at the methods.
 
 In this skill:
 
-- **What are you building?** — route each feature to its identity: visitor token, admin token
-  in a backend function, or admin ad hoc in exec_tool
+- **What are you building?** — for visitors, for the owner, or management done for them —
+  decided per request from the user's intent, each on its own flow
 - **The helpers** — the `wx.*` loader every exec opens with
 - **Gather context** — `wx.context`, the report of what the site actually has
 - **Learn Wix** — find the APIs, learn their contracts
@@ -40,28 +40,41 @@ In this skill:
 
 ## What are you building?
 
-Choose the token by who the code acts for. A headless app can serve visitors, provide admin
-management tools, or do both.
-
-**A site for visitors** — use a visitor token for public reads and actions on behalf of the
-visitor, never the admin connector token. Call Wix directly from the browser through one shared
-visitor client (Write the code, below). Redirect sessions for Wix-hosted flows also require a
-visitor token minted for the headless OAuth app; see Visitor authentication and Wix-hosted flows below.
-**The OAuth app is a one-call prerequisite, not a dead end**: `wx.ensureOAuthApp` returns its
-`clientId`, creating the app when the site has none, so it is a visitor flow's first step — never
-a reason to move the flow onto the admin token or leave it for later.
-Anyone can mint an anonymous visitor token from the
-OAuth app's public `clientId`; no visitor login is required. APIs for the "current visitor"
-use that token to identify whose data and state to access. This applies both to a standalone
-headless frontend and to a frontend extending an existing Wix site.
-
-**An admin tool for the owner** — use the admin connector token in backend functions implementing
-admin logic; keep it secret and server-side. The frontend calls those functions, not Wix with
-visitor tokens. A custom headless management site extending the Wix back office follows this
-flow too. Ad hoc management calls in `exec_tool` also use the admin token. Backend functions
-also handle work requiring the owner's permissions, such as webhooks, scheduled jobs, and
-explicitly authorized elevated operations. For an app with both visitor and admin features,
-keep each feature on its corresponding flow.
+Wix has two identities, visitor and admin, and each has its own flow. Decide which one every
+request is for before acting on it — from what the user wants, not from the technology:
+
+- **Visitor** — the people using the site: browsing, booking, buying, signing in as a member.
+  Visitor token, called from the browser through one shared visitor client.
+- **Admin, built** — a management surface of the owner's own: a custom view, a bulk operation,
+  an internal tool. Admin connector token, server-side in backend functions the frontend calls.
+- **Admin, done for them** — the user wants the business managed now, not an app: create the
+  products, change a setting, import the contacts. Admin token, ad hoc in exec_tool; nothing
+  ships in the app.
+
+The owner already has a full Wix dashboard for running the business — orders, products,
+bookings, settings, and more — so an admin build is a choice the user makes, not a gap to fill by
+default. When a request has both visitor and admin parts, each keeps its own flow.
+
+When the request doesn't say which, ask the user — in their terms (who the thing is for), not in
+technical ones (identities, tokens, flows). When you decide without asking, tell them what you
+chose the same way.
+
+The rules that follow from the split:
+
+- **Checkout runs on a visitor token, never the admin token** — including a checkout this app
+  creates for the visitor. The admin token *will* hand back a checkout URL, and that is the trap:
+  it belongs to the site rather than the buyer (no cart persistence, no abandoned-checkout
+  recovery, no attribution), and a redirect session refuses it outright (`403`). Returns reach
+  this app only from URLs in the OAuth app's redirect list (Visitor authentication and
+  Wix-hosted flows, below).
+- **No OAuth app yet is not a reason to use the admin token.** `wx.ensureOAuthApp` returns the
+  `clientId`, creating the app when the site has none — a visitor flow's first step. Anyone can
+  mint an anonymous visitor token from that public `clientId`; no visitor login is required.
+- **No login still means visitors.** `asServiceRole` governs this app's own data access and says
+  nothing about which identity Wix sees: a public page's Wix calls run on a visitor token. Reach
+  for the admin token because a feature is owner-side, never because nobody signs in.
+- **Owner-side work beyond pages** — webhooks, scheduled jobs, explicitly authorized elevated
+  operations — is admin flow too, in backend functions.
 
 ```
 visitor pages ──(visitor token)────────────────────────► wixapis.com
@@ -69,6 +82,11 @@ admin pages   ──► base44/functions/… ──(admin token)────►
 exec_tool     ──(admin token, ad hoc management)────────► wixapis.com
 ```
 
+**The connected site owns its payments.** Whatever the visitor buys is paid on the Wix-hosted page
+this app hands them off to, with the provider the site already has. Base44's
+`<available_payment_providers>` note is about checkout that Base44 hosts instead — it does not
+apply to these flows, and asks nothing of them, whichever providers it names or rules out.
+
 ## The helpers
 
 Research and probing run in exec_tool, and one loader opens every exec (execs share no state —
@@ -118,6 +136,10 @@ One report: installed apps **with ids** (incl. Stores' catalog version — V1 vs
 endpoints), the OAuth app id (**also the visitor `clientId`**), locale, currency, CMS collections.
 An empty report = bad token, never an empty site.
 
+No OAuth app in the report means the site has none **yet**. For anything a visitor operates,
+create it with `wx.ensureOAuthApp` — one call, returns the `clientId` the frontend mints visitor
+tokens from — and build the feature on the visitor flow.
+
 Reports over 4,000 characters are saved in full to a temporary Markdown file. The result includes
 its path, byte and line counts, and a heading outline. Read that file to inspect the site context.
 

package/skills/wix-headless/SKILL.md

@@ -124,6 +124,7 @@ Compute `<SKILL_ROOT>` from this file (`<SKILL_ROOT>/SKILL.md` — strip `/SKILL
 | Image generation (opt-in; agnostic) | `<SKILL_ROOT>/references/IMAGE_GENERATION.md` |
 | Design — fallback visual quality bar for the built frontend, when the user gave no design direction of their own (managed **create** only) | `<SKILL_ROOT>/references/DESIGN.md` |
 | Content — fallback copy quality bar for the built frontend, when the user gave no copy/voice direction of their own (managed **create** only) | `<SKILL_ROOT>/references/CONTENT.md` |
+| Experience overlays — a vertical's own design + copy bar on top of DESIGN/CONTENT (optional per vertical; read when that vertical is loaded) | `<SKILL_ROOT>/references/inline-recipes/experience-<vertical>.md` (today: `experience-store.md`) |
 | AI features — text/chat + embeddings (opt-in; agnostic) | `<SKILL_ROOT>/references/AI_FEATURES.md` |
 | Feedback — relay the user's headless-experience feedback to Wix (opt-in; user-approved) | `<SKILL_ROOT>/references/FEEDBACK.md` |
 | **Authentication** — obtain `$TOKEN`/`$SITE_ID`/`clientId` (project-type-specific) | `<TYPE_DIR>/AUTHENTICATION.md` |