@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-vibe-headless/references/cms/INSTRUCTIONS.md

@@ -0,0 +1,154 @@
+
+# Wix CMS Skill
+
+> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and this vertical's `references/cms/wix-cms.js`. Copy **both** into your app's `src/rest/` side by side — the helper does `import { wixApiRequest } from "./wix-client.js"`, so they must land in the same folder.
+
+Builds a real, client-only Wix CMS-backed app. The browser talks to Wix Data directly
+over a public `WIX_CLIENT_ID` to read and write items in the site's data collections.
+Never mock data; never hand-build API URLs — always go through the helpers, which call
+the official Wix Data endpoints.
+
+## When to use
+- User wants to display Wix CMS / Content Manager content (a collection of posts,
+  tutorials, recipes, team members, listings, FAQs, etc.) on a site.
+- Replacing placeholder/mock content with live Wix Data items.
+- Adding list pages, detail pages, category/tag filtering, or free-text search over an
+  existing Wix data collection.
+- Wiring a public form (contact, RSVP, review, signup) that writes a row into a collection.
+
+## Prerequisites
+1. A Wix site with **a data collection already created and populated** (this skill does
+   NOT provision collections — it reads/writes existing ones). The merchant creates
+   collections, fields, and items in the Wix dashboard (CMS / Content Manager).
+2. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (the
+   Wix Business Manager surfaces a copyable prompt with the id filled in — see
+   the router `SKILL.md`). Paste it into `src/rest/wix-client.js` in place of the placeholder. It is
+   a buyer-facing credential (it only mints anonymous visitor tokens), **not** a secret,
+   so hardcoding/committing it is fine.
+3. **Collection permissions** must match what you're doing. This skill runs as an
+   anonymous visitor, so a call only works if the collection grants that action to
+   "Anyone": Read for listing content, Insert for a public form. Update/Delete are
+   almost always admin- or author-only and will fail for a visitor. The site owner sets
+   these in the Wix dashboard (CMS → collection → Permissions). This is a **separate Wix
+   setup step the user completes** — out of this skill's scope. If a read/insert fails
+   with a permission error (HTTP 403) before that's set, that's expected; flag it and
+   continue.
+4. You need each collection's **collection ID** (its name, e.g. `Tutorials`) and its
+   **field keys** (e.g. `title`, `publishDate`). Read field keys off a fetched item, or
+   from the collection schema (see "Beyond the snippets").
+
+## The API (copy as-is; do not re-derive it)
+This skill ships only the REST layer — no UI components. Build the UI however the project
+wants; wire it to these two snippets. Copy them into the app (e.g. `src/api/`) and only
+adjust import paths:
+- `src/rest/wix-client.js` — visitor-token mint/refresh + transport. Set `WIX_CLIENT_ID`
+  to the id from the prompt (replace the `<YOUR-CLIENT-ID>` placeholder). The visitor
+  refresh token is persisted to localStorage; do not re-mint anonymously per load.
+- `src/rest/wix-cms.js` — exports:
+  - **Read:** `queryDataItems`, `getDataItem`, `getDataItemBy`, `countDataItems`
+  - **Write:** `insertDataItem`, `updateDataItem`, `removeDataItem`
+
+The Data Item shape, the per-collection **permissions model**, and the **filter/sort
+syntax** are documented as JSDoc comments at the top of `wix-cms.js`. Read them before
+building the UI — read helpers return the item's flat `data` payload (which always
+includes `_id`), and writes are bound by collection permissions.
+
+## How to wire it (UI is the project's choice)
+- **Content list** — `queryDataItems(collectionId, { filter?, sort?, limit?, cursor? })`
+  for the listing; render fields directly off each returned item (`item.title`, etc.).
+  Pass the returned `nextCursor` back as `cursor` to load the next page. Define
+  `filter`/`sort` on the first request only — cursor follow-ups reuse the original query.
+- **Detail page** — route by the item's `_id` and call `getDataItem(collectionId, itemId)`;
+  returns null on miss → show a not-found state, never invent an item. For human-readable
+  URLs, add a slug-like field to the collection and route via
+  `getDataItemBy(collectionId, "slug", slugFromUrl)`.
+- **Filter & search** — pass a `filter` to `queryDataItems` using the operators documented
+  in `wix-cms.js` (`$eq`, `$in`, `$gte`, `$startsWith`, `$hasSome`, `$and`/`$or`, …). For a
+  simple text search, `{ title: { $startsWith: term } }`; for richer free-text/fuzzy search
+  across fields, see "Beyond the snippets" (Search Data Items).
+- **Public form** — on submit, `insertDataItem(collectionId, { name, email, message })`
+  (field keys must match the collection). Requires the collection's Insert permission to be
+  "Anyone". Show success/failure from the resolved/thrown result; never fake a success.
+- **Edit / delete (admin/author flows)** — `updateDataItem(collectionId, itemId, data)`
+  (⚠ full replace — fetch + merge first to preserve other fields) and
+  `removeDataItem(collectionId, itemId)`. These need Update/Delete granted to the caller,
+  which visitors normally don't have — expect them to fail unless the collection is opened up.
+- **Empty state** — if `countDataItems(collectionId)` is 0, show an empty state telling
+  the user to add items in their Wix dashboard. Never invent items.
+
+## Hard rules (do not violate)
+- ✅ Read/write ONLY through the helpers in `wix-cms.js` (which call the official Wix Data
+  `/wix-data/v2/items` endpoints).
+- ❌ Never hand-build Wix Data URLs or invent endpoint paths.
+- ❌ Never mock data — render live Wix Data items or the empty state.
+- ❌ Never invent fields, reviews, ratings, or content not present in the collection.
+- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
+- ✅ Use the item's `_id` as the route key and as `itemId` for get/update/remove.
+- ✅ `updateDataItem` REPLACES the whole item — fetch with `getDataItem`, merge your
+  changes, then pass the full object, or use Patch Data Item (see below) for partial edits.
+- ✅ Treat permission errors (HTTP 403) as a configuration step, not a code bug: tell the
+  user which permission to grant in the dashboard. Writes throw on failure — don't swallow
+  the error and show a fake success.
+
+## Beyond the snippets
+The snippets cover the common CMS paths (list, detail, filter, count, insert, update,
+remove). If you hit a use case they don't cover, make the call yourself with
+`wixApiRequest` — but look up the exact endpoint, HTTP method, and request body in the
+**official Wix API reference** first; never guess:
+- CMS / Data Items API reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items.md
+- Data Items sample flows: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/sample-flows.md
+- **Partial update** (change some fields, keep the rest): Patch Data Item —
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/patch-data-item.md
+- **Upsert** (insert or update by id): Save Data Item —
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/save-data-item.md
+- **Bulk** insert/update/save/remove (many items in one call):
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items.md
+- **Free-text / fuzzy search** across fields: Search Data Items —
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/search-data-items.md
+- **Aggregations** (counts/averages grouped by a field): Aggregate Data Items —
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/aggregate-data-items.md
+- **Distinct values** (e.g. all categories for a filter menu): Query Distinct Values —
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-distinct-values.md
+- **Referenced items** (expand a reference field beyond the inline limit): Query Referenced
+  Data Items — https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-referenced-data-items.md
+- **Collection schema / field keys & types**: Get Data Collection —
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/get-data-collection.md
+- **Member-gated & user-generated content** → the **members** vertical
+  (`references/members/INSTRUCTIONS.md`). A collection whose permissions are `read: Anyone`,
+  `insert: Site Member`, `update/remove: Site Member Author` gives you the classic pattern: anyone
+  reads, only logged-in members write, and each member edits only their own. Sign the member in with
+  custom login (on your own UI), then `insertDataItem` runs as the member and Wix stamps the item's
+  `_owner` automatically — so a **"my items"** view is just
+  `queryDataItems(collectionId, { filter: { _owner: <memberId> } })`, and author-only
+  `updateDataItem`/`removeDataItem` are enforced server-side. (This skill never provisions the
+  collection — the owner creates it with those permissions in the dashboard.)
+  **Prefer Wix for member-generated content, and keep one feature's data and identity together.**
+  Content that belongs to the Wix site (likes, reviews, submissions) is best kept in a Wix collection
+  via these helpers, keyed on the Wix member's server-stamped `_owner`. What breaks is a *split*
+  feature — the row stored in one place while the member is identified from the Wix session elsewhere
+  (or filtered by some other `created_by`/user id): the two ids won't match, so ownership filters
+  miss. Keep them on one side; for Wix-backed rows that's `_owner`.
+
+Keep the snippets as the default for everything they already do; reach for the API
+reference only for the gap.
+
+## Point the user to their dashboard
+In some cases, users need to access the Wix dashboard in order to edit the CMS content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For CMS data those pages are:
+- **Collections & items** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-cms` (`Dashboard → CMS`) → **Create Collection**, then open a collection to add items.
+- **Permissions** — no separate deep link; in the same CMS area, open the collection → **More Actions → Permissions & Privacy**. For the headless app to work anonymously, set **Show content** to *Everyone* (visitor reads) and, for a public form, **Collect content** to *Everyone* (visitor inserts). Update/Delete stay admin-only.
+
+Substitute the site's `metaSiteId` to complete the links (you have it from the handoff / `ListWixSites`). Include the in-dashboard navigation as a fallback.
+
+## Verification checklist (before declaring done)
+- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
+- [ ] Visitor token persists across reload (same anonymous visitor, no re-mint per load)
+- [ ] `queryDataItems` returns live items; pagination via `nextCursor` loads more
+- [ ] Detail page uses the item's `_id` (or a slug field via `getDataItemBy`) and shows a
+      not-found state on miss — no invented item
+- [ ] Filter/sort produce the expected subset (operators match the field types)
+- [ ] Public form `insertDataItem` succeeds only when Insert is "Anyone"; on a 403 the user
+      is told to grant the permission — no fake success
+- [ ] Update is treated as a full replace (fetch + merge), so no fields are silently dropped
+- [ ] Empty state shown when `countDataItems` is 0
+- [ ] No mock data anywhere; no hand-built Wix Data URLs
+- [ ] Told the user at least once that they can continue setting up their content in the dashboard and provided deep links.

package/skills/wix-vibe-headless/references/cms/wix-cms.js

@@ -0,0 +1,186 @@
+import { wixApiRequest } from "./wix-client.js";
+
+/**
+ * Wix CMS (Wix Data) — REST helpers for reading and writing data items in site data collections.
+ *
+ * COLLECTIONS & PERMISSIONS: A collection (e.g. "Tutorials") is identified by its
+ * dataCollectionId — the name set in the dashboard, NOT a GUID. Field keys are also set
+ * in the dashboard. This skill runs as an ANONYMOUS VISITOR — a call only succeeds if the
+ * collection grants that action to "Anyone" (Read for listing, Insert for forms, etc.).
+ * Permission-denied throws HTTP 403 by design. Set permissions in Wix dashboard → CMS → Permissions.
+ * https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-permissions/data-permissions-object.md
+ *
+ * Data Item — every read helper returns the item's `data` payload:
+ *   _id {string} — GUID (route key, itemId for get/update/remove),
+ *   _createdDate, _updatedDate {string} — ISO 8601 (use { "$date": "..." } in filters),
+ *   _ownerId {string}, ...fields — collection field values keyed by field key
+ * Full reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/data-item-object.md
+ *
+ * FILTERS & SORT (Wix API Query Language):
+ *   filter: { field: value } for equality; { field: { $op: value } } for operators:
+ *     $eq $ne $gt $gte $lt $lte $in $nin $startsWith $exists $isEmpty $hasSome $hasAll
+ *   Combine with $and / $or / $not. Dates: { "$date": "2026-05-05T00:00:00.000Z" }.
+ *   sort: [{ fieldName: "publishDate", order: "DESC" }]
+ * Full reference: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md
+ */
+
+/**
+ * Query one page of items from a collection.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-data-items.md
+ *
+ * Pass `nextCursor` back as `cursor` to load the next page. Define `filter`/`sort`/`fields`
+ * on the FIRST request only — on cursor follow-ups Wix reuses the original query and
+ * ignores them (so this helper omits them when a cursor is supplied).
+ *
+ * @param {string} dataCollectionId  Collection name (e.g. "Tutorials").
+ * @param {{
+ *   filter?: object,
+ *   sort?: Array<{ fieldName: string, order?: "ASC"|"DESC" }>,
+ *   limit?: number,
+ *   cursor?: string,
+ *   fields?: string[],
+ *   includeReferences?: Array<{ field: string, limit?: number }>
+ * }} [options]
+ * @returns {Promise<{ items: object[], nextCursor: string|null }>}  items are `data` payloads (each includes `_id`).
+ */
+export async function queryDataItems(dataCollectionId, { filter, sort, limit = 100, cursor, fields, includeReferences } = {}) {
+  const query = {
+    ...(cursor
+      ? {}
+      : {
+          ...(filter ? { filter } : {}),
+          ...(sort ? { sort } : {}),
+          ...(fields ? { fields } : {}),
+        }),
+    cursorPaging: cursor ? { limit, cursor } : { limit },
+  };
+  const res = await wixApiRequest("/wix-data/v2/items/query", {
+    method: "POST",
+    body: {
+      dataCollectionId,
+      query,
+      ...(includeReferences ? { includeReferences } : {}),
+    },
+  });
+  return {
+    items: (res?.dataItems ?? []).map((d) => d.data),
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Get a single item by its `_id`. Returns the `data` payload, or null if not found
+ * (or not readable by an anonymous visitor — see the permissions note up top).
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/get-data-item.md
+ *
+ * @param {string} dataCollectionId
+ * @param {string} itemId            The item's `_id`.
+ * @returns {Promise<object|null>}
+ */
+export async function getDataItem(dataCollectionId, itemId) {
+  try {
+    const res = await wixApiRequest(`/wix-data/v2/items/${encodeURIComponent(itemId)}`, {
+      method: "GET",
+      query: { dataCollectionId },
+    });
+    return res?.dataItem?.data ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the first item whose `fieldKey` equals `value`. Use for slug-style routing —
+ * Wix Data has no native get-by-slug, so detail pages keyed off a human-readable field
+ * (e.g. a "slug" or "handle" field) resolve through this. Returns the `data` payload or null.
+ * Built on Query Data Items: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-data-items.md
+ *
+ * @param {string} dataCollectionId
+ * @param {string} fieldKey   Field to match (e.g. "slug").
+ * @param {unknown} value     Value to match.
+ * @returns {Promise<object|null>}
+ */
+export async function getDataItemBy(dataCollectionId, fieldKey, value) {
+  const { items } = await queryDataItems(dataCollectionId, { filter: { [fieldKey]: value }, limit: 1 });
+  return items[0] ?? null;
+}
+
+/**
+ * Count items in a collection matching an optional filter. Use for empty-state logic
+ * (0 → prompt the user to add items in their Wix dashboard) and result counts.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/count-data-items.md
+ *
+ * @param {string} dataCollectionId
+ * @param {object} [filter]  Same filter syntax as queryDataItems.
+ * @returns {Promise<number>}
+ */
+export async function countDataItems(dataCollectionId, filter) {
+  const res = await wixApiRequest("/wix-data/v2/items/count", {
+    method: "POST",
+    body: { dataCollectionId, ...(filter ? { filter } : {}) },
+  });
+  return res?.totalCount ?? 0;
+}
+
+/**
+ * Insert a new item (e.g. a public form submission). The collection's Insert permission
+ * must be "Anyone" for this to succeed as a visitor. Returns the inserted `data` payload
+ * (including the assigned `_id`). Throws on failure (e.g. permission denied, validation).
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/insert-data-item.md
+ *
+ * @param {string} dataCollectionId
+ * @param {object} data   Field-keyed values, e.g. { name, email, message }. Omit `_id`
+ *                        to let Wix assign one; supply `_id` only for a custom GUID.
+ * @returns {Promise<object>}  The inserted item's `data` payload.
+ */
+export async function insertDataItem(dataCollectionId, data) {
+  const res = await wixApiRequest("/wix-data/v2/items", {
+    method: "POST",
+    body: { dataCollectionId, dataItem: { data } },
+  });
+  const inserted = res?.dataItem?.data;
+  if (!inserted) throw new Error(`Insert into "${dataCollectionId}" failed (no item returned).`);
+  return inserted;
+}
+
+/**
+ * Update (REPLACE) an existing item by `_id`. Returns the updated `data` payload. Throws
+ * if the item doesn't exist or the visitor lacks Update permission (usually admin/author only).
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/update-data-item.md
+ *
+ * ⚠ This is a FULL REPLACE: the new `data` overwrites the whole item, and any field NOT
+ * included is dropped. To change a few fields, fetch the item first (getDataItem), spread
+ * it, then pass the merged object — or use Patch Data Item for a partial change:
+ * https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/patch-data-item.md
+ *
+ * @param {string} dataCollectionId
+ * @param {string} itemId   The item's `_id`.
+ * @param {object} data     The complete new field set.
+ * @returns {Promise<object>}  The updated item's `data` payload.
+ */
+export async function updateDataItem(dataCollectionId, itemId, data) {
+  const res = await wixApiRequest(`/wix-data/v2/items/${encodeURIComponent(itemId)}`, {
+    method: "PUT",
+    body: { dataCollectionId, dataItem: { id: itemId, data: { ...data, _id: itemId } } },
+  });
+  const updated = res?.dataItem?.data;
+  if (!updated) throw new Error(`Update of "${itemId}" in "${dataCollectionId}" failed (no item returned).`);
+  return updated;
+}
+
+/**
+ * Remove an item by `_id`. Irreversible. Returns the removed `data` payload. Throws if the
+ * visitor lacks Delete permission (usually admin/author only).
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/remove-data-item.md
+ *
+ * @param {string} dataCollectionId
+ * @param {string} itemId   The item's `_id`.
+ * @returns {Promise<object|null>}  The removed item's `data` payload.
+ */
+export async function removeDataItem(dataCollectionId, itemId) {
+  const res = await wixApiRequest(`/wix-data/v2/items/${encodeURIComponent(itemId)}`, {
+    method: "DELETE",
+    query: { dataCollectionId },
+  });
+  return res?.dataItem?.data ?? null;
+}

package/skills/wix-vibe-headless/references/events/INSTRUCTIONS.md

@@ -0,0 +1,142 @@
+
+# Wix Events Skill
+
+> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and the helper file(s) you need from `references/events/`. All helpers import from `"./wix-client.js"`, so copy them into the same folder (e.g. `src/rest/`).
+>
+> | Need | Copy |
+> |---|---|
+> | Event listing + detail (always) | `wix-events-browse.js` |
+> | RSVP, ticketing, registration | `wix-events-registration.js` |
+
+Builds a real, client-only Wix Events site. The browser talks to Wix directly over a
+public `WIX_CLIENT_ID`. Never mock events; never hand-build registration or payment URLs —
+register via the RSVP/ticketing APIs, and complete paid tickets on the official Wix-hosted
+ticket form.
+
+## When to use
+- User wants an events site over Wix Events & Tickets, or asks to "connect Wix Events".
+- Replacing placeholder/mock events with live Wix data.
+- Adding event listings, an event detail page, RSVP, or ticket purchase over existing,
+  published Wix events.
+
+## Prerequisites
+1. A Wix site with **Wix Events & Tickets installed and events already published** (this skill
+   does NOT create events — it's read-only over them). Selling **paid** tickets also needs a
+   Wix premium plan + a configured payment method; **free** events and RSVP events work without.
+2. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (the Wix
+   Business Manager surfaces a copyable prompt with the id filled in — see the router `SKILL.md`). Paste
+   it into `src/rest/wix-client.js` in place of the placeholder. It is a visitor-facing
+   credential (it only mints anonymous visitor tokens), **not** a secret, so hardcoding/
+   committing it is fine.
+3. For paid tickets the buyer completes payment on the **Wix-hosted ticket form** (the redirect
+   target of `getTicketCheckoutUrl`). The deployed app domain may need to be allow-listed on the
+   OAuth client for that page to return cleanly — a **separate Wix setup the user completes
+   later**, out of this skill's scope. If the return fails before that's done, that's expected;
+   flag it and continue.
+
+## The API (copy as-is; do not re-derive it)
+This skill ships only the REST layer — no UI components. Build the events UI however the
+project wants; wire it to these two snippets. Copy them into the app (e.g. `src/api/`) and only
+adjust import paths:
+- `src/rest/wix-client.js` — visitor-token mint/refresh + transport. Set `WIX_CLIENT_ID` to the
+  id from the prompt (replace the `<YOUR-CLIENT-ID>` placeholder). The visitor refresh token is
+  persisted to localStorage and IS the identity of the visitor's ticket reservation/cart — do
+  not re-mint anonymously per load.
+- `src/rest/wix-events-browse.js` — **Browse & discovery:**
+  `queryEvents`, `getEventBySlug`, `countUpcomingEvents`, `queryEventCategories`, `listEventsByCategory`
+- `src/rest/wix-events-registration.js` — **RSVP & ticketing:**
+  `createRsvp`, `queryTicketDefinitions`, `reserveTickets`, `getTicketCheckoutUrl`, `checkoutTickets`
+
+The `Event`, `TicketDefinition`, and `RSVP`/`Order` shapes are documented as JSDoc comments at
+the top of each helper file. Read the relevant file(s) before building the UI — they describe
+the key fields and link to the full API reference for anything not shown.
+
+## How to wire it (UI is the project's choice)
+- **Event grid** — `queryEvents()` lists live (UPCOMING/STARTED) events, soonest first. Render
+  `title`, `mainImage.url`, `dateAndTimeSettings.formatted.dateAndTime`, `location.name`, and
+  `shortDescription`. Use `offset`/`nextOffset` from the result to page. Link each card by `slug`.
+- **Event detail** — `getEventBySlug(slug)`; returns null on miss — show a not-found state, never
+  invent an event.
+  - **Description fields:** `event.shortDescription` is a **plain string** (safe teaser). The full
+    `event.description` is **Ricos rich content** — an object shaped `{ nodes: [...] }`, **not a string**.
+    Render it with a Ricos viewer (`@wix/ricos`) or walk `nodes` to extract text; **never** call string
+    methods (`.split`/`.slice`/`.substring`) on it — that crashes the page. When you only need text, use
+    `shortDescription`.
+  - Branch the registration UI on `event.registration.type`:
+  - `"RSVP"` → render the RSVP form (fields from `event.form.controls`).
+  - `"TICKETING"` → render the ticket picker.
+  - `"EXTERNAL"` → link out to `event.registration.external.url`.
+  - `"NONE"` → details only, no registration.
+  Only `registration.status` values starting `OPEN_` accept new registrations; otherwise show the
+  closed state.
+- **Categories (optional)** — `queryEventCategories()` for a filter menu (`counts.assignedEventsCount`
+  per category); `listEventsByCategory(categoryId)` to list a category's events (same card fields
+  and paging as `queryEvents`).
+- **RSVP** — `createRsvp(eventId, { firstName, lastName, email, status, additionalGuestNames?, extraFields? })`.
+  `status` defaults to `"YES"`; only offer `"NO"` when `registration.rsvp.responseType` is
+  `"YES_AND_NO"`. If the event is full with a waitlist enabled, the returned RSVP comes back with
+  status `"WAITLIST"` — tell the guest. Completes fully client-side; no redirect.
+- **Ticketing** — show tickets, reserve, then complete on the hosted form:
+  1. `queryTicketDefinitions(eventId)` → render each ticket's `name`, price (`pricing.fixedPrice.amount`
+     + `currency` for standard tickets; `free` boolean for free tickets; `pricing.minPrice` for
+     donation/"pay what you want"; `pricing.pricingOptions.options` for tiered), and filter on
+     `saleStatus === "SALE_STARTED"`. The endpoint already returns only non-hidden, available tickets.
+  2. `reserveTickets([{ ticketDefinitionId, quantity, guestPrice?, pricingOptionId? }])` → holds the
+     tickets; returns `{ id, expirationDate }`. Show a countdown to `expirationDate` if you like.
+  3. `window.location.href = getTicketCheckoutUrl(event, reservation.id)` → the Wix-hosted ticket
+     form collects guest details + payment and returns the buyer to the event. This is the path for
+     **all paid tickets**.
+  - **Free tickets only:** you may instead call `checkoutTickets(eventId, { reservationId, buyer, guests })`
+    to finish in-app — it returns an order with status `"FREE"`, a `ticketsPdf`, and `tickets[]`. It
+    throws for paid orders (status `INITIATED`), telling you to use the hosted form.
+- **Empty state** — if `countUpcomingEvents()` is 0, show an empty state telling the user to publish
+  events in their Wix dashboard. Never invent events.
+
+## Hard rules (do not violate)
+- ✅ Complete paid ticket purchases ONLY via `reserveTickets()` → `getTicketCheckoutUrl()` redirect
+  (the official Wix-hosted ticket form). 
+- ❌ Never hand-build registration, ticket, payment, or checkout URLs — derive the hosted form URL
+  from `event.eventPageUrl` via `getTicketCheckoutUrl`.
+- ❌ Never mock events, tickets, or guest counts — render live Wix data or the empty/closed state.
+- ❌ Never invent reviews, ratings, attendee names, or "X spots left" numbers not returned by the API.
+- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public visitor-facing client id — safe to hardcode).
+- ✅ Branch registration UI on `event.registration.type`; respect `registration.status` (only `OPEN_*`
+  accepts registrations) and ticket `saleStatus`/`salesDetails.soldOut`.
+- ✅ Pass `guestPrice` for donation/"pay what you want" tickets and `pricingOptionId` for tiered tickets
+  to `reserveTickets`.
+- The helpers fail loudly on purpose: `reserveTickets` throws when tickets aren't actually held,
+  `createRsvp` throws on closed/full registration, `checkoutTickets` throws when payment is still owed.
+  A green path means it really worked — don't swallow these.
+
+## Beyond the snippets
+The snippets cover the common RSVP + ticketing paths. If you hit a use case they don't cover
+(coupons/`discount` at checkout, members/auth, schedule/agenda, seating maps, canceling a
+reservation, a field not in the typedefs), make the call yourself with `wixApiRequest` — but look
+up the exact endpoint, HTTP method, and request body in the **official Wix Events API reference**
+first; never guess:
+- Events API reference: https://dev.wix.com/docs/api-reference/business-solutions/events.md
+- Registration (RSVP + ticketing) overview: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/introduction.md
+- Member login + a "my registrations" account view → the **members** vertical (`references/members/INSTRUCTIONS.md`).
+- Ticketing flow (reservations → orders → tickets): https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/introduction.md
+
+Keep the snippets as the default for everything they already do; reach for the API reference only
+for the gap.
+
+## Point the user to their dashboard
+In some cases, users need to access the Wix dashboard in order to edit the events content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For events data those pages are:
+- **Events** — `https://manage.wix.com/dashboard/{metaSiteId}/events` (`Dashboard → Events` → **+ Add Event**; create the event, then set it up as **Ticketed** or **RSVP**; only published events appear in the app)
+
+Substitute the site's `metaSiteId` to complete the links (you have it from the handoff / `ListWixSites`). Include the in-dashboard navigation as a fallback.
+
+## Verification checklist (before declaring done)
+- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
+- [ ] Visitor token persists across reload (same visitor identity for reservations)
+- [ ] Event grid renders live events; clicking a card opens the detail page by `slug`
+- [ ] Detail page branches correctly on `registration.type` (RSVP form vs. ticket picker vs. external link)
+- [ ] RSVP submit creates a real RSVP (and surfaces a `WAITLIST` result when the event is full)
+- [ ] Ticket purchase reserves tickets, then redirects via `getTicketCheckoutUrl` (no hand-built URL)
+- [ ] Paid checkout lands on the Wix-hosted ticket form; buyer returns to the event afterward
+- [ ] Closed registration / sold-out tickets show a clear state rather than a dead end
+- [ ] Empty state shown when `countUpcomingEvents()` is 0
+- [ ] No mock events, tickets, or attendee data anywhere
+- [ ] Told the user at least once that they can continue setting up their events in the dashboard and provided deep links.

package/skills/wix-vibe-headless/references/events/wix-events-browse.js

@@ -0,0 +1,136 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+
+/**
+ * Wix Events V3 Event — key fields for list cards and the detail page.
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/event-object.md
+ *
+ *   id {string}, title {string}, slug {string},
+ *   status {string} — "UPCOMING"|"STARTED"|"ENDED"|"CANCELED"|"DRAFT" (only UPCOMING/STARTED are live),
+ *   shortDescription {string} — PLAIN-TEXT teaser, safe to render directly (DETAILS fieldset),
+ *   description {object} — RICH CONTENT (Ricos), shape { nodes: [...] } — NOT a string (TEXTS fieldset,
+ *     returned by getEventBySlug). Render it with a Ricos viewer (@wix/ricos) or walk `nodes` to extract
+ *     text; NEVER call string methods (.split/.slice/.substring/.trim) on it — that crashes the page.
+ *     For a plain-string teaser use shortDescription instead.
+ *   detailedDescription {string} — legacy plain/HTML description (TEXTS fieldset); prefer description/shortDescription,
+ *   mainImage {object} — { id, url, width, height, altText } (DETAILS fieldset),
+ *   dateAndTimeSettings {object}:
+ *     startDate, endDate {string} — ISO-8601; absent when dateAndTimeTbd is true,
+ *     timeZoneId {string} — IANA tz,
+ *     formatted.dateAndTime {string} — ready-to-render human string,
+ *   location {object}: type "VENUE"|"ONLINE", name {string}, address {object}, locationTbd {boolean},
+ *   registration {object} (REGISTRATION fieldset):
+ *     type {string} — "RSVP"|"TICKETING"|"EXTERNAL"|"NONE",
+ *     status {string} — only OPEN_* statuses accept new registrations,
+ *     rsvp.responseType — "YES_AND_NO" allows a "NO" reply,
+ *     tickets.lowestPrice {object} — money { value, currency, formattedValue }; render
+ *       formattedValue, not the object (see "Money/price fields" in SKILL.md). tickets.soldOut {boolean},
+ *     external.url — link out when type === "EXTERNAL",
+ *   eventPageUrl {object} — { base, path } (URLS fieldset) — needed for getTicketCheckoutUrl,
+ *   form {object} — registration form controls (FORM fieldset),
+ *   calendarUrls {object} — { google, ics } (DETAILS fieldset)
+ *
+ * Category: { id, label, slug, counts.assignedEventsCount }
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/categories
+ */
+
+const LIST_FIELDS = ["DETAILS", "REGISTRATION", "URLS"];
+const DETAIL_FIELDS = ["DETAILS", "TEXTS", "REGISTRATION", "URLS", "FORM"];
+
+/**
+ * Query live (UPCOMING/STARTED) events for a listing grid, one page. Sorted soonest first.
+ * Uses offset paging — response carries total for empty state and "load more" math.
+ * https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/query-events.md
+ * @param {{ limit?: number, offset?: number, status?: string[] }} [options]
+ * @returns {Promise<{ events: object[], total: number, offset: number, nextOffset: number|null }>}
+ */
+export async function queryEvents({ limit = 50, offset = 0, status = ["UPCOMING", "STARTED"] } = {}) {
+  const res = await wixApiRequest("/events/v3/events/query", {
+    method: "POST",
+    body: {
+      query: {
+        filter: { status: { $in: status } },
+        sort: [{ fieldName: "dateAndTimeSettings.startDate", order: "ASC" }],
+        paging: { limit, offset },
+      },
+      fields: LIST_FIELDS,
+    },
+  });
+  const events = res?.events ?? [];
+  const total = res?.pagingMetadata?.total ?? events.length;
+  const nextOffset = offset + events.length < total ? offset + events.length : null;
+  return { events, total, offset, nextOffset };
+}
+
+/**
+ * Fetch a single event by its URL slug, with full detail-page fields (description, form, page URL).
+ * Returns null if not found — show a not-found state, never invent an event.
+ * https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/get-event-by-slug.md
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ */
+export async function getEventBySlug(slug) {
+  try {
+    const res = await wixApiRequest(`/events/v3/events/slug/${encodeURIComponent(slug)}`, {
+      method: "GET",
+      query: { fields: DETAIL_FIELDS },
+    });
+    return res?.event ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Total number of live events. Used for empty-state logic (0 → prompt user to publish events).
+ * @param {string[]} [status]
+ * @returns {Promise<number>}
+ */
+export async function countUpcomingEvents(status = ["UPCOMING", "STARTED"]) {
+  const res = await wixApiRequest("/events/v3/events/query", {
+    method: "POST",
+    body: { query: { filter: { status: { $in: status } }, paging: { limit: 1, offset: 0 } } },
+  });
+  return res?.pagingMetadata?.total ?? 0;
+}
+
+/**
+ * Query event categories for a category menu/filter. counts.assignedEventsCount tells you
+ * how many events are in each category.
+ * https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/categories/query-categories.md
+ * @param {{ limit?: number, offset?: number }} [options]
+ * @returns {Promise<{ categories: object[], total: number }>}
+ */
+export async function queryEventCategories({ limit = 100, offset = 0 } = {}) {
+  const res = await wixApiRequest("/events/v1/categories/query", {
+    method: "POST",
+    body: { query: { paging: { limit, offset } }, fieldset: ["COUNTS"] },
+  });
+  return {
+    categories: res?.categories ?? [],
+    total: res?.metaData?.total ?? (res?.categories?.length ?? 0),
+  };
+}
+
+/**
+ * List live events assigned to a category, one page. Same card fields as queryEvents.
+ * https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/list-events-by-category.md
+ * @param {string} categoryId  Category GUID from queryEventCategories.
+ * @param {{ limit?: number, offset?: number }} [options]
+ * @returns {Promise<{ events: object[], total: number, offset: number, nextOffset: number|null }>}
+ */
+export async function listEventsByCategory(categoryId, { limit = 50, offset = 0 } = {}) {
+  const res = await wixApiRequest(`/events/v3/events/category/${encodeURIComponent(categoryId)}`, {
+    method: "GET",
+    query: {
+      fields: LIST_FIELDS,
+      "paging.limit": String(limit),
+      "paging.offset": String(offset),
+    },
+  });
+  const events = res?.events ?? [];
+  const total = res?.pagingMetadata?.total ?? events.length;
+  const nextOffset = offset + events.length < total ? offset + events.length : null;
+  return { events, total, offset, nextOffset };
+}