@wix/agent-skills 1.16.3 → 1.18.0

package/skills/wix-headless/references/inline-recipes/setup-rentals.md

@@ -0,0 +1,254 @@
+---
+name: "Setup Rentals"
+description: Initializes a Wix Rentals backend — creates a resource type, the bookable resources (rooms, vehicles, equipment), and the rental services carrying serviceResources plus a duration range so customers pick their own length in hours or days. Rentals has no APIs of its own; it is Services V2 with rentals-specific field values. Specifies the *how* (calls + format); how many resources and services, their ranges and prices come from the request.
+---
+**RECIPE**: Business Recipe – Initial Setup for Wix Rentals (Services V2 + Resources V2)
+
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
+
+A concise checklist for turning a freshly provisioned Wix site with the **Wix Rentals** app installed into a populated catalog of rentable resources.
+**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial Rentals backend setup. (The frontend read/booking contract is the sibling recipe `how-to-code-rentals.md`.)
+
+> **This recipe is the *how*, not the *what*.** What to seed — how many resource types and resources, how many services, whether they are hourly or daily, their duration ranges and prices — is determined by the request you're fulfilling. This recipe only specifies the calls and the request format; it does not decide quantities.
+
+> **⚠️ Wix Rentals has NO APIs of its own.** It runs on the **Wix Bookings** APIs with rentals-specific field values, so a rental offering is a Bookings *service* and a reservation is a Bookings *booking*. There is no `@wix/rentals` package and no `/rentals/` REST namespace — do not go looking for one, and do not report rentals as "not supported headlessly".
+>
+> **The Wix Rentals doc set is four pages** — this recipe is distilled from them, and they are where to go when a task falls outside the common path:
+> - [About Wix Rentals](https://dev.wix.com/docs/api-reference/business-solutions/rentals/introduction.md) — the model, the app id, and the constraints
+> - [Wix Rentals and the Bookings APIs](https://dev.wix.com/docs/api-reference/business-solutions/rentals/wix-rentals-and-the-bookings-apis.md) — each rentals concept mapped to its Bookings API
+> - [About Wix Rentals Availability](https://dev.wix.com/docs/api-reference/business-solutions/rentals/about-wix-rentals-availability.md) — resource schedules, hourly vs daily, buffer time
+> - [Wix Rentals: Sample Flows](https://dev.wix.com/docs/api-reference/business-solutions/rentals/sample-flows.md) — the call sequences, including [Set up a rental service](https://dev.wix.com/docs/api-reference/business-solutions/rentals/sample-flows.md#set-up-a-rental-service), which is this recipe end to end
+
+> ### The invariants (read these before anything else)
+> A service is a rental because of **five field values**, all set at create time in STEP 4:
+> 1. **`appId` = `ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e`** — and it is **IMMUTABLE after create**. A service created without it is a plain Bookings service *forever*; no update converts it. This is the most expensive mistake in this recipe.
+> 2. **`serviceResources: [{ "resourceType": { "id": "<resourceTypeId>" }, "resourceIds": { "values": ["<resourceId>", …] } }]`** — list the resource type **and** its concrete resource ids. Availability comes from the listed ids: identical services return 48 time-slots with them and 0 without. (Dropping `serviceResources` altogether returns `MISSING_APPOINTMENT_RESOURCES` — see STEP 4.)
+> 3. **`primaryResourceType`** — the resource type GUID, which makes availability come from the rooms/vehicles instead of staff schedules. It must reference **one of the types listed in `serviceResources`**. Omitting it silently falls back to the **staff** resource type.
+> 4. **`form.id` = `3a2ea2ce-91f4-4617-ab24-629933c0c31a`** — the Rentals default booking form, provisioned at install and identical on every site. Omit it and you get the standard Bookings form instead.
+> 5. **`durationRange`** — with a single `unitType` (`HOUR` or `DAY`) and its matching `hourOptions`/`dayOptions`. Mutually exclusive with `sessionDurations`.
+>
+> And one ordering rule: **resources must exist before the service** (STEP 2 before STEP 4), or availability is permanently empty.
+>
+> **Rental services never use a category** — omit the field. The bookings "a category or it's invisible" rule is specific to Wix Bookings and does not apply to rentals. See STEP 3.
+
+> **API surfaces:** everything is on the **public** host `https://www.wixapis.com/bookings/...`. Services are **Services V2** (`…/bookings/v2/services`) — the method page's schema header shows an internal `…/_api/bookings/v2/services` form, **do not use that**. Resource types are `…/bookings/v2/resources/resource-types`, resources are `…/bookings/v2/resources`. The Wix Rentals **app id** is `ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e` (needed here on the service, and by the frontend for filtering + the cart).
+
+---
+
+## Article: Steps for Setting Up Wix Rentals
+
+**YOU MUST** complete the following steps **in the given order** (1-5) without skipping any and **without requiring additional user input**. STEP 5 (attributes) runs only when the request calls for filterable resource properties. The **Attach images** step runs **only when imagery is on** — skip it entirely otherwise.
+
+**⚠️ CRITICAL ORDER REQUIREMENT: resource type (STEP 1) → resources (STEP 2) → services (STEP 4).** (STEP 3 is intentionally empty — rental services use no category.) A rental service declares its resource type in `serviceResources` and points at it via `primaryResourceType`, and its availability is derived from the *resources* in that type — so both must exist before the service. A service created against a resource type that holds **no resources has permanently empty availability**: it is created successfully, appears in the catalog, and can never be booked.
+
+**Check for pre-existing services first** — same demo-data cleanup as bookings, same rules. List with `POST https://www.wixapis.com/bookings/v2/services/query` (body `{"query": {"paging": {"limit": 100}}}`), and `DELETE https://www.wixapis.com/bookings/v2/services/<serviceId>` the install's own samples. **Do not assume every existing service is a sample** — if it isn't obviously install demo data, **ask the user first**. Full rationale: `setup-bookings.md` § "Check for pre-existing services first".
+
+### STEP 1: Create the resource type
+
+A **resource type** is the category of thing being rented — "Meeting rooms", "Vans", "Cameras". A service connects to exactly **one** resource type, and Wix derives that service's availability from the resources inside it. Create one resource type per kind of thing the request rents.
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/resources/resource-types' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "resourceType": { "name": "Meeting rooms" } }'
+```
+
+The response is `{ "resourceType": { "id": "<resourceTypeId>", … } }` — **keep each `id`**, STEP 2 and STEP 4 both need it. Full contract: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resource-types-v2/create-resource-type.md>
+
+- **`name` is required, max 40 characters, and must be unique per site.** A duplicate returns `409 RESOURCE_TYPE_ALREADY_EXISTS_FOR_NAME` — query or rename rather than retrying the same name.
+- Sites have a cap on resource types (`429 MAX_NUMBER_OF_RESOURCE_TYPES_REACHED`). Create one per genuine category, not one per item.
+
+### STEP 2: Create the resources
+
+A **resource** is an individual bookable thing — "Room A", "Room B", "Van 3". Create one per rentable unit. Two resources of the same type mean two customers can rent in parallel.
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/resources' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "resource": {
+      "name": "Room A",
+      "typeId": "<RESOURCE_TYPE_ID_FROM_STEP_1>"
+    }
+  }'
+```
+
+Keep each resource's returned **`id`** — it's needed for attributes (STEP 5) and the handoff, **not** by the service.
+
+**A resource's `typeId` binds it to its type; the service then binds to those resources by listing their ids.** STEP 4's `serviceResources` names the resource *type* **and** its `resourceIds`, which is where the service's availability comes from. Add a resource later by updating the service's `resourceIds`.
+
+- **⚠️ Omit `workingHoursSchedules` — this is the deliberate seed default and it matters downstream.** ([Why, in detail](https://dev.wix.com/docs/api-reference/business-solutions/rentals/about-wix-rentals-availability.md#resource-schedules).) A resource with **no** working-hours schedule is bookable **24/7**. That keeps the seed to a single call per resource, *and* it makes a multi-day daily rental store as **one booking** rather than a linked group of per-day bookings. A resource **with** working hours splits every multi-day rental into one booking per working day, created through Create Multi Service Booking — a materially harder frontend flow (`how-to-code-rentals.md` § "Daily availability"). Seed 24/7 unless the request explicitly needs opening hours; the merchant can add hours from the dashboard later.
+- **Working hours, when the request genuinely needs them,** are a Schedules V3 schedule referenced by `workingHoursSchedules.scheduleId` — created separately, then attached. It is out of scope for a seed; note it in the handoff instead. Reference: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/create-resource.md>
+- **Locations** — `locationOptions.specificLocationOptions` binds a resource to business locations. Omit it for a single-location site (the default). When both `workingHoursSchedules` and `locationOptions` are set, **`workingHoursSchedules` takes precedence**.
+
+### STEP 3: No category — rental services don't use categories
+
+**⚠️ Rental services do not use categories at all. Omit `category` from the service payload entirely** — do not send `"category": {}`, a made-up id, or try to create one. There is no step here; the numbering is kept so STEP 4 keeps its name.
+
+This is the one place where the bookings invariant does **not** carry over. `setup-bookings.md` STEP 2 calls `category.id` critical because a Bookings service without one is hidden on the live site. **That rule is specific to Wix Bookings and does not apply to Wix Rentals** — rentals are surfaced through the `appId`-filtered catalog read, not through Bookings categories. Confirmed on a live Rentals site: services created with no category come back from that read with `hidden: false`, and the Rentals install's own demo service ships without one.
+
+On a Rentals-only site the categories API isn't reachable anyway — it belongs to the **Wix Bookings app**, so `POST …/bookings/v2/categories` returns **`428 APP_NOT_INSTALLED`**. That is expected: rentals don't use categories, so there is nothing to do here. If the site also runs Wix Bookings for plain services, the categories API works there — assign categories only to those Bookings services, never to rentals.
+
+### STEP 4: Create the rental services
+
+Create the services **one at a time** with `POST https://www.wixapis.com/bookings/v2/services` — one call per service, each with a top-level `service` object. A rental service is a normal **Services V2 `APPOINTMENT`** carrying the rentals-specific values.
+
+**⚠️ Do NOT use the bulk endpoint (`…/bookings/v2/bulk/services/create`) for rentals.** It creates the service correctly but attaches a **schedule tagged with the Wix Bookings app id instead of the Wix Rentals one**, and calendar events inherit their app id from the schedule — so every booking and every event on that service becomes invisible in the Rentals dashboard calendar. The service itself looks perfect, which is what makes this hard to spot. Verified on a live site: bulk-created schedules carry `13d21c63-b5ec-5912-8397-c3a5ddb27a97`; single-created ones carry the rentals app id. Use single create until that is fixed upstream. (Bulk is still fine for plain Wix Bookings services — see `setup-bookings.md`.)
+
+**⚠️ CRITICAL: the V2 service payload is FLAT** — name/description/tagLine are top-level, not nested under `info`. Price uses `value` (a **string**), not `amount`. Full field contract: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/create-service.md>
+
+**One hourly rental service, bookable 1–8 hours at $40/hour:**
+
+```json
+{
+  "service": {
+    "type": "APPOINTMENT",
+    "appId": "ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e",
+    "name": "Meeting Room",
+    "description": "A brand-appropriate description of what is being rented.",
+    "tagLine": "Short tagline",
+    "defaultCapacity": 1,
+    "serviceResources": [ {
+      "resourceType": { "id": "<RESOURCE_TYPE_ID_FROM_STEP_1>" },
+      "resourceIds": { "values": ["<RESOURCE_ID_FROM_STEP_2>"] }
+    } ],
+    "primaryResourceType": "<RESOURCE_TYPE_ID_FROM_STEP_1>",
+    "form": { "id": "3a2ea2ce-91f4-4617-ab24-629933c0c31a" },
+    "onlineBooking": { "enabled": true, "requireManualApproval": false, "allowMultipleRequests": false },
+    "schedule": {
+      "availabilityConstraints": {
+        "durationRange": {
+          "unitType": "HOUR",
+          "hourOptions": { "minDurationInMinutes": 60, "maxDurationInMinutes": 480 }
+        }
+      }
+    },
+    "payment": {
+      "rateType": "FIXED",
+      "fixed": { "price": { "value": "40.00", "currency": "USD" } },
+      "options": { "online": true, "inPerson": false }
+    },
+    "locations": [ { "type": "BUSINESS" } ]
+  }
+}
+```
+
+**`serviceResources` carries both levels.** `resourceType.id` is the type from STEP 1; `resourceIds.values` lists the individual resources from STEP 2 that this service can book (max **100** ids, max **8** `serviceResources` entries).
+
+**List the concrete `resourceIds`** — the service's availability comes from them. Verified on a live site: identical services returned **48** time-slots with `resourceIds` and **0** without. Add resources later by updating the service's `resourceIds`.
+
+**⚠️ Price decides how many services you create.** The rate lives on the **service**, not the resource, so resources that rent at **different rates must be separate services**, each pinning its own resource in `resourceIds`. Three meeting rooms at ₪60, ₪120 and ₪250 per hour are **three services** sharing one resource type — not one service with three resources. Resources that rent at the **same** rate can share a single service.
+
+**For a daily rental**, swap the duration range (everything else is identical):
+
+```json
+"durationRange": {
+  "unitType": "DAY",
+  "dayOptions": { "minDurationInDays": 1, "maxDurationInDays": 5 }
+}
+```
+
+**⚠️ CRITICAL FORMAT REQUIREMENTS:**
+
+- **`appId` must be the Wix Rentals app id** `ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e`, and it is **immutable after create** — a service created without it is a plain Bookings service forever, and no update can convert it. Getting this wrong is the single most expensive mistake in this recipe.
+- **`appId` also means the service does NOT appear in the Wix Bookings dashboard** — it appears in the Rentals dashboard. That is correct and expected; don't "fix" it.
+- **⚠️ `serviceResources` is REQUIRED and is the real cause of `MISSING_APPOINTMENT_RESOURCES` — do not trust the error text.** The message reads *"service of type appointment requires at least one staff member or service resource"*, which invites you to go check whether your resource type has resources in it. **That is a dead end** — the create fails even when the type is fully populated. What the service actually needs is the resource type declared **on the service**:
+  ```json
+  "serviceResources": [ {
+    "resourceType": { "id": "<resourceTypeId>" },
+    "resourceIds": { "values": ["<resourceId>"] }
+  } ]
+  ```
+  Verified on a live site: adding this field is what makes the create succeed. `resourceType.id` is the type from STEP 1; `resourceIds.values` lists the resources from STEP 2 this service can book. Max **8** `serviceResources` entries, max **100** ids each. **`resourceIds` supplies the service's availability** — list them (48 slots with, 0 without, otherwise identical). Add resources later by updating `resourceIds`.
+- **`primaryResourceType`** is the resource type **GUID** from STEP 1, and **must be one of the types listed in `serviceResources`**. It is what makes availability come from the rooms/vehicles rather than from staff schedules. Omitting it silently falls back to the **staff** resource type, which produces a normal staff-driven appointment service.
+- **`form.id` selects the booking form. Set it to the Wix Rentals default booking form — `3a2ea2ce-91f4-4617-ab24-629933c0c31a`.** Installing the Rentals app provisions that form, and because it is cloned from the template with the template's own id, **the GUID is the same on every site** — treat it as a constant, like the `appId`. Omit the field and the service uses the standard Wix Bookings form instead, so the rentals form's own fields won't be there. It's the Rentals app's own choice too: `RentalsProvisioner` sets it on every service it creates.
+- **`durationRange` and `sessionDurations` are mutually exclusive** — send one or the other, never both. `durationRange` also **can't be combined with `workingHours`** on the service.
+- **`unitType` selects which config object is read:** `HOUR` → `hourOptions`, `DAY` → `dayOptions`. Sending `dayOptions` with `unitType: "HOUR"` leaves the range unset.
+- **Ranges:** hourly `minDurationInMinutes`/`maxDurationInMinutes` are **30–1440**; daily `minDurationInDays`/`maxDurationInDays` are **1–8** for rentals. Min must be **≤** max. (The underlying Services V2 schema permits days up to 60; Wix Rentals documents 1–8 — stay inside 1–8.)
+- **One unit type per service.** A service is hourly *or* daily, never both. If the request wants a room by the hour **and** by the day, that is **two services**, each with its own price.
+- **Omit `staffMemberIds`.** Rentals are resource-driven, not staff-driven — `serviceResources` above is what satisfies the appointment-resource requirement. Never add a staff resource to get past `MISSING_APPOINTMENT_RESOURCES`; that reintroduces staff-based availability and produces a service that is no longer a rental in behaviour.
+- **Omit `category`.** Rental services don't use categories at all (STEP 3).
+- **`onlineBooking: { "enabled": true }` is required** — V2 rejects the create without it even though it reads as optional.
+- **`defaultCapacity`** is required; use `1` (one customer rents a given resource at a time; parallel capacity comes from having more *resources*, not higher capacity).
+- **`payment.options` — at least one of `online`/`inPerson` must be `true`**, even for free services. `NO_FEE` must pair with `online: false, inPerson: true`.
+- **Price is per unit** — per hour for `HOUR`, per day for `DAY`. Wix multiplies it out at booking time (hourly is prorated per minute: `minutes × price ÷ 60`). Do **not** pre-multiply into a whole-rental price.
+- **`locations[].type`** — use **`"BUSINESS"`**, never `"OWNER_BUSINESS"` (that enum belongs to `createBooking`'s slot location).
+- **Currency** — the site's business currency wins; a EUR-locale site stores `EUR` even if you send `USD`. Not an error.
+- **Imagery is opt-in** (`SEED.md` § "Entity images") — seed text-only, attach images in the pass-2 step below.
+
+**Reading the response.** A single create returns the created service under a top-level `service`:
+
+```json
+{ "service": { "id": "<serviceId>", "name": "…", "type": "APPOINTMENT",
+               "appId": "ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e",
+               "mainSlug": { "name": "<url-slug>", "custom": false },
+               "schedule": { "id": "<scheduleId>", "availabilityConstraints": { "durationRange": { … } } } } }
+```
+
+Keep each service's **`service.id`** and **`service.mainSlug.name`** (the frontend links by slug; if absent, derive it: lowercase, non-alphanumerics → hyphens). A failed create returns a normal error — retry that one service **once** with the same body; don't loop, and don't re-create ones that already succeeded.
+
+**Verify the range actually landed.** `durationRange` is a newer field and a silently-dropped range yields a service that looks fine and books as a fixed slot. Re-read one created service (`GET https://www.wixapis.com/bookings/v2/services/<serviceId>`) and confirm `schedule.availabilityConstraints.durationRange.unitType` is populated before moving on.
+
+### STEP 5: Resource attributes (only when the request wants filterable properties)
+
+Attributes are typed custom properties on a resource — `Capacity` (number), `Has projector` (boolean), `Bed type` (string) — used to describe resources on the site and to filter the catalog. Skip this step entirely unless the request calls for it.
+
+> **⚠️ The attributes API is the one surface here that really does live under `/_api/`.** Unlike Services V2 (where the `_api` form in the schema header is wrong and the public form is correct), the attributes reference's own examples call `https://www.wixapis.com/_api/attributes/v1/...`. Use the paths exactly as written below — don't "correct" them to a public form.
+
+**1 · Define each attribute once per site.** Keep each returned `attributeDefinition.id`.
+
+```bash
+curl -X POST 'https://www.wixapis.com/_api/attributes/v1/attribute-definitions' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "attributeDefinition": {
+      "name": "Capacity",
+      "valueType": "NUMBER",
+      "numberConfig": { "min": 1, "max": 20 },
+      "defaultValue": { "numberDefault": 2 },
+      "visibility": true
+    }
+  }'
+```
+
+**2 · Set values per resource.** The **resource id** is the `{entityId}` path segment. Each entry is matched by `attributeDefinitionId`, so only the listed attributes are created or updated.
+
+```bash
+curl -X POST 'https://www.wixapis.com/_api/attributes/v1/attribute-values/<RESOURCE_ID_FROM_STEP_2>/bulk-upsert' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "values": [ { "attributeDefinitionId": "<ATTRIBUTE_DEFINITION_ID>", "numberData": 4 } ],
+    "returnEntity": true
+  }'
+```
+
+The value key is typed — `numberData` for `NUMBER`, and the string/boolean equivalents for those `valueType`s; check the reference for the exact key rather than guessing.
+
+**3 · Reading them back for display** — filter to attributes whose `attributeDefinition.visibility` is `true`. **⚠️ The API does not enforce visibility server-side**, so an unfiltered render leaks attributes the merchant marked hidden.
+
+References: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/attributes/attribute-definition/create-attribute-definition.md> and <https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/attributes/attribute-value/bulk-upsert-attribute-values.md>
+
+### Attach images (imagery ON only — skip otherwise)
+
+Identical to the bookings flow, because it is the same Services V2 entity. Obtain the image per `references/IMAGE_GENERATION.md`, then `PATCH https://www.wixapis.com/bookings/v2/services/<serviceId>` writing under **`media.mainMedia`** and **`media.coverMedia`**, each `{ "image": { "id", "url", "width", "height" } }`, echoing the current `revision`.
+
+**⚠️ Writing the image under `media.image` returns `HTTP 200` but silently drops it** — confirm by re-querying the service and checking `media.mainMedia` is populated. Never block on image failure; leave the service text-only. Full shape and caveats: `setup-bookings.md` § "Attach images".
+
+---
+
+## Conclusion
+
+Following these steps **in order** sets up a Wix Rentals site:
+
+- A **resource type** exists, and it **contains resources** — without resources the service's availability is permanently empty.
+- Every service carries the **Wix Rentals `appId`** (`ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e`), set at create time because it is **immutable** afterwards.
+- Every service carries **`serviceResources`** with concrete **`resourceIds`** listed — resource type alone gives 0 availability slots — plus **`primaryResourceType`**, so availability comes from the resources rather than from staff.
+- Every service carries **`form.id`** = the Rentals default booking form constant, so it uses the rentals form rather than the standard Bookings one.
+- Every service carries a **`durationRange`** with a single `unitType` and its matching `hourOptions`/`dayOptions` — never alongside `sessionDurations`.
+- **No category** is set — rental services don't use categories, and the bookings visibility rule doesn't apply to them. They are surfaced by the `appId`-filtered catalog read.
+- Resources are seeded **24/7** (no working-hours schedule), which keeps a multi-day daily rental to a single booking.
+- IDs kept for the coding handoff: `resourceTypeIds[]`, `resourceIds[]`, `serviceIds[]`, service `slug`s (`mainSlug.name`), and any `attributeDefinitionIds[]`.

package/skills/wix-headless/references/managed/AUTHENTICATION.md

@@ -4,6 +4,11 @@ For a **managed** project (hosted on Wix infrastructure), every Wix call uses a
 
 ## 1 · Ensure an authenticated CLI session
 
+### Secret boundary — mandatory
+
+Never read authentication material or tokens into agent context.
+Never emit them to stdout, stderr, logs, prompts, or tool results.
+
 ```bash
 npx @wix/cli@latest whoami   # exits 0 when logged in; non-zero when logged out
 ```

package/skills/wix-headless/references/non-astro.md

@@ -25,7 +25,7 @@ This is the framework reference for any **non-Astro** frontend — React/Vue/Sve
 | <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/oauth/create-a-client-for-authentication-with-oauth.md> | **The model.** Install `@wix/sdk` + the domain packages, then `createClient({ modules, auth: OAuthStrategy({ clientId }) })`. clientId only, **no secret in the frontend**. Explicitly scoped to "frameworks other than Astro." Create the client **once** and reuse it. |
 | <https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md> | **`OAuthStrategy` reference** — visitor sessions (automatic) vs member flows (managed/custom/external); token + session methods; confirms `clientId` only. |
 | <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/visitors/handle-visitors-using-the-js-sdk.md> | **Visitors & members via the JS SDK** — visitor token sessions out of the box, and member login when the site needs it. Members are **first-class** on the non-Astro path (not deferred). |
-| <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/members/wix-login-page/wix-managed-login-using-the-js-sdk.md> | **Member login (Wix login page)** — the manual `OAuthStrategy` handshake: `generateOAuthData → getAuthUrl → parseFromUrl → getMemberTokens → setTokens`, `logout`, `loggedIn()`. Login *is* sign-up (the Wix page logs in or registers); member tokens are the **same shape** as visitor tokens (`role: member`), so they reuse the visitor session machinery — login just swaps the token set. **`clientId` only (no secret); the connected site must be PUBLISHED and the `redirectUri` must be an exact-match allow-listed URI, or `getAuthUrl` fails; default to the Wix login page** over custom/external. **Full frontend contract → Read `inline-recipes/how-to-code-members-non-astro.md`** (local — Read it, don't curl). **Only if the brief explicitly asks for a custom/branded login form or custom sign-up fields → Read `inline-recipes/how-to-code-members-custom-login.md`** instead (`client.auth.register`/`login`; works on any project type — pick by intent, not project type). |
+| <https://dev.wix.com/docs/go-headless/authentication/members/wix-login-page/add-a-wix-login-page-js-sdk.md> | **Member login (Wix login page)** — the manual `OAuthStrategy` handshake: `generateOAuthData → getAuthUrl → parseFromUrl → getMemberTokens → setTokens`, `logout`, `loggedIn()`. Login *is* sign-up (the Wix page logs in or registers); member tokens are the **same shape** as visitor tokens (`role: member`), so they reuse the visitor session machinery — login just swaps the token set. **`clientId` only (no secret); the connected site must be PUBLISHED and the `redirectUri` must be an exact-match allow-listed URI, or `getAuthUrl` fails; default to the Wix login page** over custom/external. **Full frontend contract → Read `inline-recipes/how-to-code-members-non-astro.md`** (local — Read it, don't curl). **Only if the brief explicitly asks for a custom/branded login form or custom sign-up fields → Read `inline-recipes/how-to-code-members-custom-login.md`** instead (`client.auth.register`/`login`; works on any project type — pick by intent, not project type). |
 | <https://dev.wix.com/docs/sdk/articles/set-up-a-client/about-the-wix-client.md> | **Confirms non-Astro *does* need a client** — the "when you need a client vs not" list; non-Astro (managed or self-managed) is on the "needs a client" side, the mirror of Astro. |
 
 > **clientId source is deferred.** This file uses the `clientId`; it does **not** say where it comes from. That's `{managed,self-managed}/AUTHENTICATION.md` — managed reads `appId` from `wix.config.json`; self-managed uses the OAuth app you created. Don't re-mint or re-fetch it if the flow already provides it.

package/skills/wix-headless-fast/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: wix-headless-fast
+description: "Build a Wix Headless site fast by wiring SHIPPED, verified @wix/sdk code instead of authoring the integration from recipes. Each Wix business vertical ships a typed, framework-agnostic React core (data layer returning plain DTOs, hooks, headless components) plus an Astro overlay (SSR pages with owner-editable SEO pre-wired) and a build-time REST seed script — the agent scaffolds via the Wix CLI, deploys the shipped code, seeds the backend, designs the presentation layer itself on the shipped hooks (product card/grid, PDP, home, theme), and releases to Wix hosting. Works on Wix-managed Astro (ambient auth, the default) and on any React-based project (Vite, non-Astro) over the public OAuth client id. Verticals: stores/storefront (products, categories, variants, cart, hosted checkout), bookings (services, appointment/class time slots, staff, booking form, checkout-or-place), blog (posts, categories/tags, rich content), cms (structured content collections), forms (schema-driven visitor forms: render, validate, submit), events (listing, RSVP, ticket sales), members (login, gated pages, account), portfolio (project collections, media galleries), pricing-plans (plan grid, hosted purchase), restaurants (menus, online ordering, table reservations). Triggers: build me a store/blog/booking/event/restaurant/portfolio site fast, take appointments fast, sell tickets or membership plans headless, wix headless fast, connect a Wix business app with ready-made SDK code."
+---
+
+# Wix Headless Fast
+
+Build a Wix Headless site by **deploying shipped code, not authoring it**. Where `wix-headless`
+hands the agent recipes to code from, this skill ships the integration itself — a typed data
+layer, hooks, components, pages, and a seed script that are already correct — and the agent's
+job narrows to brand, layout, copy, and wiring. The decisions live in the code; don't
+re-litigate them.
+
+## Relationship to sibling skills
+
+| Skill                        | Use when                                                                                                               |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **wix-headless-fast** (this) | A supported vertical fits the request and the frontend is Astro or React — the fast path.                              |
+| `wix-headless`               | A vertical this skill doesn't ship yet, a non-React frontend, backend-only runs, or stripe/self-managed project types. |
+| `wix-vibe-headless`          | Client-only REST over a `WIX_CLIENT_ID` inside a vibe platform (Base44 etc.) — no SDK, no CLI.                         |
+
+## The model
+
+- **Shipped code is the implementation.** Every vertical ships under `references/<vertical>/`:
+  - `app/` — the framework-agnostic core (TypeScript): a data layer that returns **plain,
+    serializable DTOs** (images resolved to https URLs, prices pre-formatted), React hooks, and
+    routing-free headless components. Works in Astro islands, Vite SPAs, and Next.
+  - `app-astro/` — a thin Astro overlay: SSR pages that fetch via the core and pass DTOs to
+    islands, with owner-editable item-page SEO pre-wired.
+  - `seed/` — a build-time REST seed script (plain-data plan in, created content out) plus its
+    `SEED.md` contract.
+  - `INSTRUCTIONS.md` — the vertical's playbook: file map, what you build, hard rules, verify.
+- **One auth seam.** All shipped code calls Wix through `src/wix/sdk.ts`: on Wix-managed Astro
+  auth is ambient (no client, no id); on any other React setup the same file runs a manual
+  visitor client off the public client id in `src/wix/config.ts`. The deploy step configures
+  this — nothing to wire by hand.
+- **Data as-is; presentation is yours.** The data layer, hooks, and cart chrome are wired
+  as-is — never rewrite their internals, re-route them through API routes, or re-derive a
+  request shape. For a genuine gap, first read the relevant official contract with the
+  `wix-docs` skill; do not search generated SDK types, package files, or `node_modules` to
+  infer it. A normal caller-permitted operation belongs in a new data-layer function. A
+  privileged operation belongs in a validated server endpoint — see
+  `references/shared/CUSTOM_OPERATIONS.md`. The presentation components ship only as
+  **references**: the vertical's INSTRUCTIONS names the surfaces you design and implement
+  yourself on the shipped hooks (for storefront: card, grid, shop + PDP surfaces, home).
+- **Never mock, fail loudly, purchases via Wix.** Live data or an honest empty state; surfaced
+  errors, not swallowed ones; checkout/purchase always through the Wix redirect session.
+- **Optional capabilities are deployed from the plan.** A vertical can opt into a shared
+  capability without copying sensitive code. For a normal file upload, add a named
+  `capabilities.mediaUpload.policies` entry to the plan; Fast ships its client helper, Astro
+  endpoint, dependencies, and generated policy module once. Read
+  `references/shared/CUSTOM_OPERATIONS.md` before choosing it. The agent wires the helper to
+  the product UI; it never authors or widens the endpoint.
+
+## The run
+
+1. **Resolve the stack.** Default is **Wix-managed Astro** — take it unless the user names a
+   different React framework or the directory already holds a non-Astro React project. A
+   non-React frontend is out of scope → `wix-headless`.
+2. **Draft the seed plan** (read only the vertical's `SEED.md` for this — it depends only on
+   the brief; save the vertical's `INSTRUCTIONS.md` for step 4, where it's needed). Requires from here on: Node ≥ 20.11 and a logged-in Wix CLI
+   (`npx @wix/cli@latest whoami`; login via the device-code flow — surface the URL+code, never
+   read tokens into context).
+3. **Create runs (empty directory): run the fast path** — one deterministic call:
+
+   ```bash
+   node <SKILL_ROOT>/install/fast-path.mjs --business-name "<Brand>" --plan plan.json --vertical <vertical>
+   ```
+
+   `--vertical` is required and picks which shipped code deploys AND which seed runs — use
+   the vertical you resolved from the Verticals table.
+
+   It emits one JSON event per line and returns in **~35s**: **scaffolds** the project,
+   **deploys** the shipped code (patching `package.json` with every dependency the code
+   imports, and placing the pre-resolved lockfile), then **starts two detached background
+   jobs** — the dependency install (`npm ci --ignore-scripts || npm install --ignore-scripts`)
+   and the **seed** — whose logs and completion markers are in the events. The final
+   `ready_for_brand_layer` event carries the project dir, siteId, ready-made dashboard links,
+   and both markers. Relay notable events. On an `error` event, recover just that step via the
+   manual path below, then continue.
+
+   **Connect/iterate runs (a project already on disk): never scaffold — use the manual path:**
+   `CI=1 npm create @wix/new@latest init` in place if there is no `wix.config.json` yet; then
+   `node <SKILL_ROOT>/install/deploy.mjs <vertical…> --stack astro|react --plan plan.json` from the project root
+   (react stack: add `--client-id` if there is no `wix.config.json` to read the public id
+   from); then ONE `npm ci --ignore-scripts || npm install --ignore-scripts` (backgroundable —
+   but **never run a second npm install concurrently**: two npms in one `node_modules` race and
+   redo each other's work); then seed per the vertical's `seed/SEED.md`. Seeding is
+   **additive**: never delete or overwrite existing content; if a cleanup seems needed, ask.
+
+4. **Design and build the presentation while the install finishes** — in the project dir from
+   the `ready_for_brand_layer` event, per the vertical's `INSTRUCTIONS.md`: set the `@theme`
+   tokens, brand the chrome, and implement the vertical's creative surfaces yourself on the
+   shipped hooks (for storefront: your product card + grid, shop surface, PDP surface, and the
+   home page) — designed to fit the brief, not copied from the reference components. Read the
+   INSTRUCTIONS and the shared floors — `references/shared/DESIGN.md` +
+   `references/shared/CONTENT.md` — now (not earlier — their contracts matter only from this
+   step on); the hook/DTO
+   contracts are inlined there, so don't open the shipped files themselves. **Author your
+   surfaces in as few messages as possible** — batch multiple Write calls in one message
+   (components are independent files); don't pay a round-trip per file.
+   If the brief needs a core operation that shipped code does not cover, read
+   `references/shared/CUSTOM_OPERATIONS.md` before writing it. Use one documented path and
+   implement it; do not reverse-engineer SDK internals.
+5. **When both background jobs have completed** — the install's marker
+   (`node_modules/.package-lock.json`) and the seed's (`.seed-exit`) both exist — **verify the
+   seed succeeded** (`.seed-exit` contains `0`; `seed-result.json` has the created counts for
+   your summary — if non-zero, read `seed.log` and re-run the seed module manually). Then
+   **build & release once** (managed):
+   `npx @wix/cli@latest build` then `npx @wix/cli@latest release` (if the install failed, run
+   it once more and then build). Don't build+release mid-flow; backend content is fetched at
+   runtime, so a re-release never "refreshes" seeded data. The run is complete only when the
+   site is released — close with the live URL and the dashboard link
+   `https://manage.wix.com/dashboard/<siteId>`. **Copy the live URL verbatim from the
+   `wix release` output — never retype it from memory** (a mistyped subdomain hands the user
+   a 404).
+
+Don't smoke-test with a dev server unless the user explicitly asks to verify — correctness
+comes from the shipped code, and real errors surface at build/release.
+
+## Verticals
+
+| The user wants…                                                                              | Vertical          | Playbook                                   |
+| -------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------ |
+| Online store: products, categories, variants, cart, checkout                                 | **storefront**    | `references/storefront/INSTRUCTIONS.md`    |
+| Appointments/classes: services, time slots, staff, booking, checkout                         | **bookings**      | `references/bookings/INSTRUCTIONS.md`      |
+| Blog: post feed, categories/tags, rich-content post pages                                    | **blog**          | `references/blog/INSTRUCTIONS.md`          |
+| Structured content collections (directory, recipes, listings) with pages designed per schema | **cms**           | `references/cms/INSTRUCTIONS.md`           |
+| Any visitor-fillable form: contact/enquiry, signup, application, survey — rendered from the live schema | **forms**         | `references/forms/INSTRUCTIONS.md`         |
+| Events: listing, event pages, free RSVP, ticket sales via hosted checkout                    | **events**        | `references/events/INSTRUCTIONS.md`        |
+| Member accounts: custom in-app login/sign-up, gated pages, account page                      | **members**       | `references/members/INSTRUCTIONS.md`       |
+| Portfolio/showcase: collections of projects, project pages with media galleries              | **portfolio**     | `references/portfolio/INSTRUCTIONS.md`     |
+| Membership/subscription plans: pricing page, plan detail, hosted purchase                    | **pricing-plans** | `references/pricing-plans/INSTRUCTIONS.md` |
+| Restaurant: menu with photos, online ordering, table reservations                            | **restaurants**   | `references/restaurants/INSTRUCTIONS.md`   |
+
+Verticals compose: a brief that spans several (a restaurant with a blog, a store with member
+accounts) deploys them together — fast-path takes one vertical; deploy the rest with
+`node <SKILL_ROOT>/install/deploy.mjs <vertical…>` from the project root before the install
+starts, and run each vertical's seed. A request that doesn't match any shipped vertical isn't
+this skill's fast path — route it to `wix-headless` rather than improvising an unshipped
+vertical here.
+
+## Adding a vertical (structure contract)
+
+New verticals follow the same layout — the deploy script discovers them automatically (any
+`references/<name>/app/` directory is a vertical):
+
+```
+references/<vertical>/
+  INSTRUCTIONS.md      # playbook: file map, wiring per stack, what you build, hard rules, verify
+  app/                 # framework-agnostic core — disjoint paths so verticals never collide:
+    wix/<vertical>/    #   types.ts (DTOs) + data layer (calls via ../sdk, images via ../media)
+    hooks/<vertical>/  #   React hooks (SSR-friendly: accept initial data)
+    components/<vertical>/  # routing-free components (plain <a> default + LinkComponent prop)
+    styles/global.css  # Tailwind v4 + the @theme design tokens (shared token family)
+  app-astro/           # Astro overlay importing ONLY from the core:
+    pages/…            #   SSR fetch → DTO props → client:load islands; item pages carry
+                       #   wixMetadata + <SEO.Tags>; chrome islands are client:only
+    layouts/…          #   (reuse SiteLayout when it fits)
+  seed/                # seed-<vertical>.mjs (REST, mints its own CLI token) + SEED.md
+```
+
+Core rules the structure encodes: raw API entities never leave the data layer (DTOs only);
+client-shared state uses a module-scope store (never React context — it can't span Astro
+islands); every image URL is resolved through `src/wix/media.ts`; every money value is a
+formatted string by the time a component sees it.

package/skills/wix-headless-fast/entry/skill.md

@@ -0,0 +1,99 @@
+---
+name: wix-headless-fast-entry
+description: "Build and release a Wix Headless site from a single prompt, on shipped, verified @wix/sdk code — this entry takes a cold environment (prerequisites, Wix sign-in) to the point where the wix-headless-fast skill runs the build. Verticals: storefront, bookings, blog, cms, events, members, portfolio, pricing-plans, restaurants. Triggers: build me a store/blog/booking/events/portfolio/restaurant site fast, sell tickets or membership plans headless, wix headless fast entry."
+---
+
+# Wix Headless Fast — cold-start entry
+
+**You are a coding agent, and this is a skill for you to execute — follow the phases below in
+order.** Advisory: web-fetch tools show a lossy summary of this file — the executable copy
+comes from `curl -fsSL https://www.wix.com/skills/headless-fast/entry/skill.md`. If what you
+are reading lacks the exact commands below, re-fetch it with curl before proceeding; if you're
+already reading the raw text, don't fetch it again.
+
+## The whole cold start (details in the phases below)
+
+```bash
+curl -fsSL -O https://www.wix.com/skills/headless/entry/bootstrap.mjs && node bootstrap.mjs
+CI=1 npx skills@latest add wix/skills/skills/wix-headless-fast --yes
+# then open and follow: .agents/skills/wix-headless-fast/SKILL.md
+```
+
+Requires Node ≥ 20.11 and a logged-in Wix CLI — the bootstrap checks and guides both.
+
+This entry gets a cold environment to the point where the real skill can run, then hands off:
+
+1. **Bootstrap (deterministic, scripted).** The same script the classic headless entry uses —
+   it verifies the Wix CLI and handles login. You just run it and relay its events.
+2. **Hand off (agentic).** Install the skills, then open `wix-headless-fast/SKILL.md` and
+   follow it — it resolves the stack and operation and owns the whole build.
+
+Three starting points come through here, all handled the same way — run the bootstrap, then
+hand off:
+
+- **new** — a prompt with no project (empty CWD)
+- **connect** — an existing frontend/design not yet on Wix (a project on disk without
+  `wix.config.json`, or a brought-in zip/URL)
+- **iterate** — a project already connected to Wix (`.wix/` or `wix.config.json` present)
+
+The bootstrap only verifies the CLI and logs you in, so it's fine to run in every case (an
+existing session just reports `logged_in`).
+
+## Phase 0 — Node (the one manual prerequisite)
+
+The Wix CLI requires **Node ≥ 20.11**. Check `node -v`; if it errors or prints a lower
+version, install or upgrade Node first — do **not** work around it:
+
+- **macOS:** `brew install node` (or `nvm install 20 && nvm use 20`)
+- **Linux:** `nvm install 20 && nvm use 20` (or your distro's Node 20+ package)
+- **Windows:** `winget install OpenJS.NodeJS.LTS` (or download from nodejs.org)
+
+## Phase 1 — Run the bootstrap (deterministic, shared)
+
+Download and run the shared bootstrap script. It verifies the Wix CLI and handles login,
+emitting **one JSON event per line** on stdout. **Run it and relay its events** — it exits on
+its own once the CLI is verified and a session exists (seconds, when already logged in). Only
+when a login is actually needed does it pause on `awaiting_user`; surface the URL + code and
+let it keep running until the login completes.
+
+The script is safe and inspectable: it only checks the Wix CLI via `npx` and drives
+`wix login` (a device-code flow) — no other network calls, no filesystem writes. Read it first
+if your sandbox flags externally-downloaded code.
+
+```bash
+# macOS/Linux:
+curl -fsSL -O https://www.wix.com/skills/headless/entry/bootstrap.mjs
+# Windows PowerShell:
+iwr https://www.wix.com/skills/headless/entry/bootstrap.mjs -OutFile bootstrap.mjs
+
+node bootstrap.mjs
+```
+
+### Relay these events
+
+| Event | What to do |
+|---|---|
+| `cli_ok` | Wix CLI reachable — continue. |
+| `awaiting_user` (`verificationUri`, `userCode`) | Show the URL and code in plain prose; wait for the user to finish the login in their browser. |
+| `logged_in` / `success` | Login done — continue. |
+| `cli_unreachable` / `login_failed` (with `detail`) | Stop and show the user the `detail`. **Do not** improvise a parallel setup by hand. |
+
+## Phase 2 — Install the skill and hand off
+
+Install the skill (`CI=1` forces plain non-interactive CLI output — keep it on every Wix CLI
+command):
+
+```bash
+CI=1 npx skills@latest add wix/skills/skills/wix-headless-fast --yes
+```
+
+It lands at `.agents/skills/wix-headless-fast/`. Then **open
+`.agents/skills/wix-headless-fast/SKILL.md` and follow it** — it owns the rest of the run:
+resolve the stack, scaffold, deploy the shipped code, seed, build the brand layer, release.
+(If the request needs a vertical the skill doesn't ship yet — see its SKILL.md § Verticals —
+say so plainly and point the user at the `wix-headless` skill instead of improvising.)
+
+- **Don't** scaffold, install apps, or seed by hand here — the skill does all of that. This
+  entry stops at *logged in*.
+- You're already authenticated from Phase 1, so the skill's CLI auth step will pass without
+  prompting again.