@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-vibe-headless/references/cms/seed/SEED.md

@@ -0,0 +1,145 @@
+# CMS — seeding (Wix Data v2 REST)
+
+Seeding a collection is an **admin/build-time** job: create the collection(s), insert items, wire
+references, attach images — all via the **Wix Data v2 REST API**. There is **no helper module** — make
+the calls yourself with the shapes below. Needs an **elevated credential** (a connector token or a Wix
+API key; the public `WIX_CLIENT_ID` cannot write — see the platform doc's seed-auth step).
+
+**⛔ Additive only — never delete, reset, or overwrite existing content.**
+
+## Auth (on every call)
+The curls below are **request shapes** — endpoint, method, body. **Never inline the raw token/API key**
+into a command: it would end up in the transcript, exec logs, and shell history. Keep the credential in
+a variable and reference it.
+- **On Base44 (and any exec-tool platform): don't shell out to curl — make these calls with `fetch()`**,
+  taking the token from the connector so it's never printed:
+  ```js
+  const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // token stays in memory
+  await fetch(`https://www.wixapis.com/wix-data/v2/collections`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${accessToken}`, "wix-site-id": METASITE_ID, "Content-Type": "application/json" },
+    body: JSON.stringify({ collection: { /* … */ } }),
+  });
+  ```
+- **On a shell/curl platform:** load the credential into an env var from your secret manager (don't
+  echo it), then reference `$TOKEN` — the literal never appears in the command you write:
+  ```bash
+  API=https://www.wixapis.com
+  # TOKEN comes from your connector / secret manager (e.g. TOKEN="$WIX_TOKEN") — do NOT paste it here.
+  AUTH=(-H "Authorization: Bearer $TOKEN" -H "wix-site-id: $METASITE_ID" -H "Content-Type: application/json")
+  #  Wix API key instead of a token → -H "Authorization: $TOKEN"   (raw, NO "Bearer")
+  ```
+
+## 0 · Install the Wix Data app — only if a data call returns `WDE0110` (app not installed)
+```bash
+curl -sS -X POST "$API/apps-installer-service/v1/app-instance/install" "${AUTH[@]}" \
+  -d '{"tenant":{"tenantType":"SITE","id":"<METASITE_ID>"},
+       "appInstance":{"appDefId":"e593b0bd-b783-45b8-97c2-873d42aacaf4","enabled":true}}'
+```
+
+## 1 · Create a collection — the `permissions` block is MANDATORY
+```bash
+curl -sS -X POST "$API/wix-data/v2/collections" "${AUTH[@]}" -d '{
+  "collection": {
+    "id": "Recipes", "displayName": "Recipes",
+    "fields": [
+      { "key": "title", "displayName": "Title", "type": "TEXT" },
+      { "key": "photo", "displayName": "Photo", "type": "IMAGE" },
+      { "key": "categories", "displayName": "Categories", "type": "MULTI_REFERENCE",
+        "typeMetadata": { "multiReference": { "referencedCollectionId": "Categories" } } }
+    ],
+    "permissions": { "insert": "ADMIN", "update": "ADMIN", "remove": "ADMIN", "read": "ANYONE" }
+  }
+}'
+```
+- The `id` you send **is** the collection id (Wix doesn't rename it) — keep it + the field keys.
+- **Permissions is required and load-bearing.** A public collection's `read` **must** be `"ANYONE"` or a visitor query silently returns 0 items. Presets:
+
+  | preset | `read` / `insert` / `update` / `remove` | use |
+  |---|---|---|
+  | **public-read** (default) | `ANYONE` / `ADMIN` / `ADMIN` / `ADMIN` | admin content, anyone reads |
+  | **collaborative** | `ANYONE` / `ANYONE` / `ANYONE` / `ANYONE` | visitor-written shared board (anonymous, unscoped) |
+  | **member-private** | `SITE_MEMBER_AUTHOR` / `SITE_MEMBER` / `SITE_MEMBER_AUTHOR` / `SITE_MEMBER_AUTHOR` | per-user "my…" rows (`_owner`-matched); **create it EMPTY** — members populate it from the client with their **member token** so Wix stamps `_owner` |
+  | **member-shared-read-only** | `SITE_MEMBER` / `ADMIN` / `ADMIN` / `ADMIN` | gated: any member reads, seed/admin writes |
+  | **public-wall** | `ANYONE` / `SITE_MEMBER` / `SITE_MEMBER_AUTHOR` / `SITE_MEMBER_AUTHOR` | members post, **everyone** reads (public gallery/feed); authors edit only their own |
+
+- **The values are Wix user *roles*, and they're a hierarchy** — a role can do anything the roles below it can. Pick per action (`read` / `insert` / `update` / `remove`):
+
+  | role | who, for that action |
+  |---|---|
+  | `ANYONE` | any visitor, logged in or not |
+  | `SITE_MEMBER` | any logged-in member — **all** rows |
+  | `SITE_MEMBER_AUTHOR` | logged-in members, but **only rows they created** (Wix matches `_owner`) — this is how "only mine" is enforced, server-side |
+  | `CMS_EDITOR` | Wix users holding a CMS role |
+  | `PRIVILEGED` / `ADMIN` | site admins + special permissions only |
+
+  So **`read` is the privacy decision**: `SITE_MEMBER_AUTHOR` scopes each read to its caller on the
+  server, so a member receives only their own rows and the client needs no filter; `ANYONE` publishes
+  every row, and a `_owner` filter then selects a view of public data. Set it here, at create time —
+  the client inherits whichever you choose.
+  Reference: [Data Permissions](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-permissions/introduction.md)
+
+- **MULTI_REFERENCE fields:** `typeMetadata.multiReference.referencedCollectionId` is mandatory (NOT `referencedCollection` — the docs' stale key stores an empty target and every later link is dead), and the **target collection must be created first**.
+- `409 WDE0104` = "collection already exists" — fine (additive); skip and move on.
+
+## 2 · Insert items — bulk
+```bash
+curl -sS -X POST "$API/wix-data/v2/bulk/items/insert" "${AUTH[@]}" -d '{
+  "dataCollectionId": "Recipes",
+  "dataItems": [ { "data": { "title": "Chocolate Cake" } }, { "data": { "title": "Pavlova" } } ],
+  "returnEntity": true
+}'
+#  ← read each id from  results[].dataItem.id  (NOT results[].item)
+```
+Single item: `POST $API/wix-data/v2/items` with `{"dataCollectionId":"Recipes","dataItem":{"data":{…}}}`.
+- Set plain fields + single `REFERENCE` (pass the target item's `_id` string) only. A **`MULTI_REFERENCE` value here is silently dropped** (no error) — wire it in step 4.
+
+## 3 · Verify — a `200` does NOT prove the rows persisted
+```bash
+curl -sS -X POST "$API/wix-data/v2/items/query" "${AUTH[@]}" -d '{"dataCollectionId":"Recipes"}'
+#  ← { "dataItems": [ { "id": "...", "data": { … } }, … ] }
+```
+
+## 4 · Wire multi-references — only if collections relate
+```bash
+curl -sS -X POST "$API/wix-data/v2/bulk/items/insert-references" "${AUTH[@]}" -d '{
+  "dataCollectionId": "Recipes",
+  "dataItemReferences": [
+    { "referringItemFieldName": "categories", "referringItemId": "<recipeId>", "referencedItemId": "<categoryId>" }
+  ]
+}'
+```
+Resolves only if the field was created with a non-empty `referencedCollectionId` (step 1). Ids come from step 2's `results[].dataItem.id`.
+
+## 5 · Images (optional)
+An `IMAGE` field stores a **URL string**. Use a permanent Wix Media URL — if your image is external
+(e.g. a generated one), **upload it to Wix Media first** (`POST /site-media/v1/files/import` with
+`{url, mimeType, displayName}` → use the returned `file.url`; the blog/storefront seeds show this), then
+set it. Attaching is a **read-merge-PUT** — a PUT replaces the whole item, so a partial body wipes the
+other fields:
+```bash
+# query the item (step 3), merge the url into its IMAGE field, then PUT the WHOLE record back:
+curl -sS -X PUT "$API/wix-data/v2/items/<itemId>" "${AUTH[@]}" -d '{
+  "dataCollectionId": "Recipes",
+  "dataItem": { "data": { <…all existing fields…>, "_id": "<itemId>", "photo": "https://…/file.jpg" } }
+}'
+```
+
+## Gotchas
+- Elevated credential required (the public client id can't write).
+- **Provisioning race:** a fresh site's FIRST create/insert can transiently fail — `403`, or `400 WDE0117` ("MetaSite not found"), or `5xx`. Retry the same call **once** after ~3s, then fail loud (don't loop).
+- Any PUT/update **replaces** the whole item — always fetch + merge (or use Patch Data Item).
+- Verify with a query; a non-error POST is not proof of persistence.
+
+## Reference
+Read a method's page before writing its call: it carries the exact body shape, the required
+permission scope, and the response envelope.
+- Install a Wix app onto the site: https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/install-app.md
+- Import an image into Wix Media: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/import-file.md
+- Create Data Collection: https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/create-data-collection.md
+- Bulk Insert Data Items: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-insert-data-items.md
+- Bulk Insert Data Item References: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-insert-data-item-references.md
+- Data Items API: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items.md
+- Collections: https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections.md
+- Anything not covered → use the `wix-docs` skill (search + read the live reference); never guess.
+- Anything not covered → use the `wix-docs` skill (search + read the live reference); never guess.

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

@@ -1,142 +1,239 @@
+# Wix Events — ready-made client
 
-# Wix Events Skill
+The events client is **shipped as real files**, not snippets to regenerate. It's a complete events
+listing + detail page + RSVP + ticketing (reserve → hosted checkout, plus in-app free-ticket
+checkout), styled with your app's design tokens (base44's `src/index.css` — the shadcn palette the
+design phase already set). Copy it into the app and wire the routes — you generate almost none of the
+events code (offset paging, category filtering, the RSVP `WAITLIST` case, the ticket
+reservation/checkout shapes all ship and are correct).
 
-> **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` |
+Talks to Wix directly over the public `WIX_CLIENT_ID` (anonymous visitor tokens). Never mock events;
+never hand-build a registration/ticket/checkout URL — RSVP completes client-side and paid tickets go
+through the Wix-hosted ticket form via the shipped reserve → redirect path.
 
-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.
+## Prerequisites
+- The site's **Wix Events & Tickets** app is the read/registration target. It's installed and seeded separately (see **Seeding** below), in parallel with this build — so it may have no events at build time; the client renders the shipped empty state until events are published. This client is read-only over events (it does not create them).
+- The public headless **`WIX_CLIENT_ID`** from your prompt (visitor-facing, safe to hardcode/commit).
+- Selling **paid** tickets also needs a Wix premium plan + a configured payment method on the site; **free** events and RSVP events work without. For paid tickets the buyer completes payment on the Wix-hosted ticket form; the deployed app domain may need to be allow-listed on the OAuth client for the return to land cleanly — a separate Wix setup the user completes later, out of scope here.
 
-## 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.
+## STEP 1 — The client is already in `src/`
+The install step (base44.md STEP 1) deployed the whole events UI client + REST scaffolds into `src/`
+(imports use the `@/` alias → `src/`). Here's every file and what it is — **this is your map, so you
+don't need to open them:**
 
-## 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:
+| file | what it is |
+|---|---|
+| `hooks/useEventsList.js` | listing logic — categories, active filter, offset "load more", empty count |
+| `hooks/useEventDetail.js` | detail data for a slug — event + derived `type`/`open` registration state |
+| `hooks/useRsvpForm.js` | RSVP submit logic (`YES`/`NO`, additional guests, `WAITLIST` result) |
+| `hooks/useTicketing.js` | ticket selection + reserve → paid redirect / free in-app checkout |
+| `components/EventCard.jsx`, `EventGrid.jsx` | event listing UI (grid + card, with empty state) |
+| `components/CategoryFilter.jsx` | category menu (renders `label` + `assignedEventsCount`) |
+| `components/EventRegistration.jsx` | branches on `registration.type` (RSVP / TICKETING / EXTERNAL / NONE) |
+| `components/RsvpForm.jsx` | RSVP form UI over `useRsvpForm` |
+| `components/TicketPicker.jsx` | ticket list + quantity + checkout UI over `useTicketing` |
+| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 4) |
+| `pages/Events.jsx`, `pages/EventDetail.jsx` | the two shipped routes (`/events`, `/events/:slug`) |
+| `rest/wix-config.js` | **you set the ids here** (STEP 2) |
+| `rest/wix-client.js` | visitor-token mint/refresh + REST transport (reads `wix-config.js`) |
+| `rest/wix-events-browse.js` | browse/discovery helpers (`queryEvents`, `getEventBySlug`, categories, count) |
+| `rest/wix-events-registration.js` | RSVP + ticketing helpers (`createRsvp`, `reserveTickets`, `getTicketCheckoutUrl`, `checkoutTickets`) |
+
+They're already in place — go **straight to theming + wiring**, nothing to verify first. **Don't
+`read_file` the shipped page/component/hook source to inspect it** — the table above says what each is
+and every field shape you need is in the snippets below. Read a shipped file's source **only** on a
+real fallback — a runtime error, or a field the snippets don't cover (see "Fallback only" at the
+end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
+`references/events/app/` → `src/`.)
+
+## STEP 2 — Credentials
+Write `src/rest/wix-config.js` with your `WIX_CLIENT_ID` and `WIX_METASITE_ID` from the prompt — the
+one place both ids live. The visitor refresh token minted from this id is persisted to localStorage
+and **is** the identity of the visitor's ticket reservation — don't re-mint anonymously per load.
+
+## STEP 3 — Theme (nothing to style on the shipped components)
+The shipped components carry **no palette of their own** — they render from base44's design tokens in
+`src/index.css` (`:root`/`.dark`: `--background`, `--foreground`, `--card`, `--primary`, `--muted`,
+`--border`, `--radius`, `--font-*`) via shadcn Tailwind classes (`bg-card`, `text-foreground`,
+`bg-primary`, `text-muted-foreground`, `border-border`, `rounded-lg`, `font-display`). Those tokens
+are **already set to the brand by the design phase**, so the shipped pages are themed with zero work
+here. To adjust the palette, edit `index.css` (`:root` **and** `.dark`) — the base44 way; **never add
+a parallel theme file (e.g. a `theme.css`) or restyle the shipped JSX.** Build the Home/Header you add
+(STEP 4) from the **same** base44 tokens/classes so it matches automatically. A dark brand is just
+base44's dark palette in `index.css` — no per-component work.
+
+## STEP 4 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+**No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
+`App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
+replace it. (Events needs no cross-page provider — there's no cart; the RSVP/ticketing state is local
+to the detail page.)
+- Put your **header + footer in a `Layout`** that renders `<Outlet/>` between them, and nest every
+  route under one pathless `<Route element={<Layout/>}>`. Your brand chrome then wraps **every** page
+  — including the shipped `Events` / `EventDetail` — so you **never edit the shipped pages to add a
+  header/footer** (they render inside `<Outlet/>` as-is).
+- **Pin the top chrome as one fixed block.** Put `<WixManageBanner/>` (shipped, preview-only) **above**
+  your `<Header/>` inside a single `position:fixed` top region — the header itself is plain in-flow
+  markup, the region owns the fixing — so banner + header ride together (no scroll drift/gap). Pad
+  the content by the region's **ResizeObserver-measured** height so it clears the chrome and
+  self-corrects when the banner is dismissed.
+- Routes under the Layout: `/events` → `Events`, `/events/:slug` → `EventDetail` (both shipped, as-is).
+  **You add `/` → your own Home** page.
+
+```jsx
+import { useRef, useState, useEffect } from "react";
+import { Routes, Route, Outlet } from "react-router-dom";
+import WixManageBanner from "@/components/WixManageBanner";   // shipped, preview-only · default export, no props
+import Events from "@/pages/Events";                   // shipped · default export, no props
+import EventDetail from "@/pages/EventDetail";         // shipped · default export, no props
+import Home from "@/pages/Home";       // YOU build
+import Header from "@/components/Header";   // YOU build — plain in-flow markup, NOT position:fixed
+import Footer from "@/components/Footer";   // YOU build
+
+function Layout() {
+  const topRef = useRef(null);
+  const [offset, setOffset] = useState(0);
+  useEffect(() => {                                  // measure the fixed region → pad content below it
+    const ro = new ResizeObserver(() => setOffset(topRef.current?.offsetHeight ?? 0));
+    if (topRef.current) ro.observe(topRef.current);
+    return () => ro.disconnect();
+  }, []);
+  return (<>
+    <div ref={topRef} style={{ position: "fixed", top: 0, left: 0, right: 0, zIndex: 50 }}>
+      <WixManageBanner />                    {/* null on the published site / when dismissed */}
+      <Header />                             {/* your brand header, in-flow inside this fixed block */}
+    </div>
+    <div style={{ paddingTop: offset }}>     {/* clears the chrome; shrinks when the banner is dismissed */}
+      <Outlet />                             {/* shipped Events/EventDetail render here, untouched */}
+      <Footer />
+    </div>
+  </>);
+}
+
+<Routes>
+  <Route element={<Layout />}>                                {/* chrome wraps all */}
+    <Route path="/" element={<Home />} />                     {/* yours */}
+    <Route path="/events" element={<Events />} />             {/* shipped, as-is */}
+    <Route path="/events/:slug" element={<EventDetail />} />  {/* shipped, as-is */}
+  </Route>
+</Routes>
+```
+
+## What you build (not shipped)
+The **home / landing page**, the **`Header`** and a **`Footer`** — the two you drop into the `Layout`
+(STEP 4) so they wrap every route — plus the overall brand story, styled with the same base44
+tokens/classes. **Compose the shipped pieces** — a "featured events" strip is just `queryEvents` + the
+shipped `EventGrid`; the nav is a link to `/events`:
+
+```jsx
+import { useState, useEffect } from "react";
+import { Link } from "react-router-dom";
+import { queryEvents } from "@/rest/wix-events-browse";
+import EventGrid from "@/components/EventGrid";
+
+// Responsive header: choose ONE branch with a state flag (copy this pattern). Do NOT render a
+// desktop nav AND a mobile nav toggled by Tailwind `hidden md:*` — these navs are inline-styled and
+// an inline `display` beats a Tailwind class, so `hidden` never applies and BOTH branches render.
+export function Header() {
+  const [mobile, setMobile] = useState(() => window.innerWidth < 768);
+  useEffect(() => {
+    const onResize = () => setMobile(window.innerWidth < 768);
+    window.addEventListener("resize", onResize);             // keep it reactive to viewport changes
+    return () => window.removeEventListener("resize", onResize);
+  }, []);
+  return (
+    <nav style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+      {/* brand/logo */}
+      {mobile ? <YourMenu /> : <Link to="/events">Events</Link>}
+    </nav>
+  );
+}
+
+export function Featured() {                                 // on your home page
+  const [events, setEvents] = useState([]);
+  // NB: queryEvents returns { events, total, offset, nextOffset } — destructure the array.
+  useEffect(() => { queryEvents({ limit: 6 }).then(({ events }) => setEvents(events)); }, []);
+  return <EventGrid events={events} empty="Events coming soon." />;
+}
+```
+Everything reads base44's design tokens (`index.css`), so your home/nav match the shipped pages automatically.
+
+**Editing a component and the change doesn't show? It's the preview, not your code.** The dev preview
+can serve a stale module after a write. Before diagnosing a visual bug you just "fixed", do a fresh
+full navigate/reload of the preview and re-check — don't keep rewriting correct code against a stale
+render.
+
+## Using the client from your own UI
+
+```jsx
+// Every browse list helper returns an OBJECT { events, total, offset, nextOffset } — not a bare
+// array. Destructure `events`; nextOffset is null when there are no more pages.
+import { queryEvents, getEventBySlug, queryEventCategories, listEventsByCategory, countUpcomingEvents } from "@/rest/wix-events-browse";
+
+const { events, nextOffset } = await queryEvents({ limit: 24 });          // live UPCOMING/STARTED, soonest first
+const { categories } = await queryEventCategories();                       // render category.label (NOT name)
+const { events: inCat } = await listEventsByCategory(categories[0].id);    // same shape + paging as queryEvents
+const total = await countUpcomingEvents();                                 // 0 → shipped empty state
+
+// Detail by slug — returns null on miss (the shipped EventDetail shows a not-found state):
+const event = await getEventBySlug(slug);
+
+// Image urls live at event.mainImage.url. shortDescription is a PLAIN string (safe to render).
+// event.description is Ricos rich content { nodes: [...] } — NOT a string; render with @wix/ricos or
+// walk nodes; NEVER call string methods (.slice/.split) on it — that crashes the page.
+```
+
+The registration flows are already wired in the shipped `EventRegistration` (branches on
+`registration.type`, respects `registration.status` — only `OPEN_*` accepts registrations), so your
+pages just render `<EventRegistration .../>` as the shipped `EventDetail` does. Doing a flow yourself:
+
+```jsx
+import { createRsvp, reserveTickets, getTicketCheckoutUrl, checkoutTickets } from "@/rest/wix-events-registration";
+
+// RSVP (client-side): status "NO" only when registration.rsvp.responseType === "YES_AND_NO".
+const rsvp = await createRsvp(event.id, { firstName, lastName, email });   // rsvp.status may be "WAITLIST"
+
+// PAID tickets: reserve, then redirect to the Wix-hosted ticket form — NEVER a hand-built URL.
+const reservation = await reserveTickets([{ ticketDefinitionId, quantity: 1 }]);
+window.location.href = getTicketCheckoutUrl(event, reservation.id);
+
+// FREE tickets only: finish in-app instead of redirecting (throws if payment is owed).
+const order = await checkoutTickets(event.id, { reservationId: reservation.id, buyer, guests: [buyer] });
+```
+
+## Extending the client
+Building something beyond the shipped pages (a "my registrations" account view, coupons, seating
+maps, a schedule/agenda, canceling a reservation)? The helpers cover the common RSVP + ticketing
+paths; for a gap, make the call with `wixApiRequest` — but look up the exact endpoint/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
+- Registration (RSVP + ticketing): https://dev.wix.com/docs/api-reference/business-solutions/events/registration/introduction.md
+- Member login + "my registrations" → the **members** vertical (`references/members/INSTRUCTIONS.md`).
+
+Fallback only — when you hit an error or need something not shown here: read the relevant shipped file
+under `src/`, or look it up via the **`wix-docs`** skill.
 
-Keep the snippets as the default for everything they already do; reach for the API reference only
-for the gap.
+## Hard rules
+- Set `WIX_CLIENT_ID` (STEP 2) — not the placeholder.
+- Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped components or adding a parallel theme file.
+- Header/footer live in a `Layout` around `<Outlet/>` (STEP 4) — never edit the shipped `Events`/`EventDetail` to add chrome.
+- The Layout's fixed top region owns positioning: `<WixManageBanner/>` above `<Header/>`; your `Header` is plain in-flow markup (not `position:fixed`).
+- Paid ticket checkout goes through the shipped reserve → `getTicketCheckoutUrl` redirect (the Wix-hosted ticket form) — never a hand-built registration/ticket/payment URL.
+- Render live Wix data or the shipped empty/closed/not-found state — never mock events, tickets, guest counts, or "X spots left".
 
 ## 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:
+Provide deep links so the owner can edit content (substitute the site's `metaSiteId`):
 - **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.
+## Seeding
+Seed events per `seed/SEED.md` (the build-time setup module) — separate from this client build; run in
+parallel.
+
+## Verify (before declaring done)
+- [ ] Client files copied into `src/`; `WIX_CLIENT_ID` set (not the placeholder).
+- [ ] Brand palette lives in `index.css` (`:root`/`.dark`); no parallel theme file; shipped components/pages not restyled or rewritten.
+- [ ] Opened the vertical's data route(s) (not just the home page) and confirmed the shipped components render themed (surface, text, brand) with images.
+- [ ] `Layout` (fixed `<WixManageBanner/>` + `<Header/>` region, then `<Outlet/>` + Footer) wraps all routes; shipped `Events`/`EventDetail` untouched; content clears the fixed chrome.
+- [ ] Event grid renders live events; clicking a card opens the detail page by `slug`; visitor token persists across reload.
+- [ ] Detail page branches correctly on `registration.type` (RSVP form vs. ticket picker vs. external link vs. none); closed registration / sold-out tickets show a clear state.
+- [ ] RSVP submit creates a real RSVP (and surfaces a `WAITLIST` result when full); paid ticket purchase reserves then redirects via `getTicketCheckoutUrl`.
+- [ ] Empty catalog shows the shipped empty state (`countUpcomingEvents()` is 0); no mock events anywhere.

package/skills/wix-vibe-headless/references/events/app/components/CategoryFilter.jsx

@@ -0,0 +1,23 @@
+// Category filter menu for the events listing. Pure UI — the active id + setter come from
+// useEventsList. Display field is `name`; key/filter by `category.id`; the per-category
+// count is `counts.assignedEventsCount`. Styled with base44 design tokens (shadcn Tailwind classes).
+
+const chipBase = "py-1.5 px-3.5 cursor-pointer text-sm font-body border rounded-full";
+const chipIdle = "border-border bg-card text-foreground";
+const chipActive = "bg-primary text-primary-foreground border-primary";
+
+export default function CategoryFilter({ categories, active, onSelect }) {
+  if (!categories?.length) return null;
+  return (
+    <nav className="flex flex-wrap gap-2 mb-4">
+      <button onClick={() => onSelect(null)} aria-pressed={active === null}
+        className={`${chipBase} ${active === null ? chipActive : chipIdle}`}>All</button>
+      {categories.map((c) => (
+        <button key={c.id} onClick={() => onSelect(c.id)} aria-pressed={active === c.id}
+          className={`${chipBase} ${active === c.id ? chipActive : chipIdle}`}>
+          {c.name} ({c.counts?.assignedEventsCount ?? 0})
+        </button>
+      ))}
+    </nav>
+  );
+}