@wix/agent-skills 1.17.0 → 1.18.1

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

@@ -0,0 +1,103 @@
+# CMS — seeding
+
+Seed by **running `seed-cms.mjs` with a plan file** — don't hand-write the REST calls.
+The script mints its own site token via the Wix CLI (logged-in session + `wix.config.json`
+required), installs the Wix Data (CMS) app if needed, resolves every IMAGE value into Wix
+Media in one parallel wave, and creates everything in order: per collection — create
+(schema + permissions) → bulk-insert items → wire multi-references → verify persistence.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/references/cms/seed/seed-cms.mjs plan.json
+```
+
+`plan.json` is plain data — **it IS the site's content model**: the collections, their field
+schemas, and the items the pages will render. Write it from the brief. Default to **one or
+two content collections with ~3–6 items each** (the seed shows the shape; the owner adds the
+rest in the dashboard). Give any collection that gets a detail page a `slug` TEXT field, and
+every content item an image on an IMAGE field (a content site without images looks broken).
+
+```json
+{
+  "collections": [
+    {
+      "id": "categories", "displayName": "Categories",
+      "fields": [{ "key": "name", "type": "TEXT" }],
+      "items": [{ "name": "Cakes" }, { "name": "Breads" }]
+    },
+    {
+      "id": "recipes", "displayName": "Recipes",
+      "fields": [
+        { "key": "title", "type": "TEXT" },
+        { "key": "slug", "type": "TEXT" },
+        { "key": "summary", "type": "TEXT" },
+        { "key": "body", "type": "RICH_TEXT" },
+        { "key": "photo", "type": "IMAGE" },
+        { "key": "publishDate", "type": "DATE" },
+        { "key": "categories", "type": "MULTI_REFERENCE", "referencedCollectionId": "categories" }
+      ],
+      "items": [
+        { "title": "Chocolate Layer Cake", "slug": "chocolate-layer-cake",
+          "summary": "Three layers, one ganache.", "body": "<p>Cream the butter…</p>",
+          "photo": "https://…", "publishDate": "2026-08-01", "categories": [0] },
+        { "title": "Country Sourdough", "slug": "country-sourdough",
+          "summary": "A 24-hour loaf.", "body": "<p>Feed the starter…</p>",
+          "photo": "https://…", "publishDate": "2026-08-10", "categories": [1] },
+        { "title": "Pavlova", "slug": "pavlova",
+          "summary": "Crisp shell, soft heart.", "body": "<p>Whip the whites…</p>",
+          "photo": "https://…", "publishDate": "2026-08-20", "categories": [0] }
+      ]
+    }
+  ]
+}
+```
+
+- `id` — the collection id the frontend binds to, verbatim (no namespace; Wix doesn't rename
+  it). Item keys must match the field `key`s exactly — the script fails loud on a key the
+  schema doesn't have (the API would silently drop it).
+- Field `type` — `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `DATETIME`, `URL`, `EMAIL`, `IMAGE`,
+  `RICH_TEXT` (an HTML string, stored verbatim), `REFERENCE`, `MULTI_REFERENCE`.
+- `IMAGE` values — the default is `{ "prompt": "..." }` (AI-generated, ~1 Wix AI credit per
+  image, account-billed): brand-contextual — subject, aesthetic/mood, palette, lighting —
+  always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually supplied use
+  `{ "path": "..." }` (a file on this machine — uploaded to Wix Media) or an https URL string
+  (their own hosted URL; verify it with `curl -sI` → 200) — never a stock-photo or guessed URL. Images
+  resolve in parallel and never block the seed; a failed image leaves that field unset (the
+  item stays text-only).
+- `DATE`/`DATETIME` values are ISO strings — the script wraps them as `{ "$date": iso }`.
+- References: **order collections so targets come first.** A `REFERENCE` value is the target
+  item's index in its collection's `items` array; `MULTI_REFERENCE` is an array of indices
+  (set at insert it would be silently dropped — the script wires these via
+  `POST /wix-data/v2/bulk/items/insert-references`).
+- `permissions` — omit for the **public-read** default
+  (`read: ANYONE`, writes `ADMIN`). Other shapes (per action: `ANYONE` › `SITE_MEMBER` ›
+  `SITE_MEMBER_AUTHOR` › `ADMIN`):
+
+  | 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 — **seed it EMPTY** (rows seeded here would be owned by the admin, invisible to members) |
+  | 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 |
+
+  `read` is the privacy decision — a public collection's `read` MUST be `ANYONE` or the
+  visitor frontend reads **zero items with no error**.
+
+**Seeding is additive — never delete or overwrite existing content** (an existing collection
+is left as-is; its items are appended); ask first if a cleanup seems needed.
+
+## Escape hatch — individual functions
+`setupCms` composes exported steps — `installDataApp`, `createCollection`, `importImage`,
+`bulkInsertItems`, `insertReferences`, `verifyItems`, plus `makeCtx()` — import them only
+for a partial re-seed.
+
+## Reference
+Unexpected shape or an uncovered operation → read the live Wix API reference; the
+authoritative source recipe is `wix-headless/references/inline-recipes/setup-cms.md`.
+Endpoints used: `POST /wix-data/v2/collections` (Create Data Collection),
+`POST /wix-data/v2/bulk/items/insert` (Bulk Insert Data Items),
+`POST /wix-data/v2/bulk/items/insert-references` (Bulk Insert Data Item References),
+`POST /wix-data/v2/items/query` (Query Data Items — the verify step),
+`POST /site-media/v1/files/import` (Import File),
+`POST /apps-installer-service/v1/app-instance/install` (Install App).

package/skills/wix-headless-fast/references/cms/seed/seed-cms.mjs

@@ -0,0 +1,324 @@
+// CMS seed — a BUILD-TIME script, never shipped in the app. Run from the project root
+// (where wix.config.json lives) with a plan file:
+//
+//   node <SKILL_ROOT>/references/cms/seed/seed-cms.mjs plan.json
+//
+// It mints its own site token via the Wix CLI, installs the Wix Data (CMS) app if needed,
+// resolves every IMAGE value into Wix Media (url import / AI generation, one parallel wave),
+// creates each collection (field schema + permissions; an existing collection is left
+// as-is), bulk-inserts items, wires multi-references, and verifies persistence. Prints a
+// JSON result to stdout.
+//
+// Plan shape (see SEED.md):
+//   { "collections": [{ "id", "displayName"?, "permissions"?,
+//       "fields": [{ "key", "displayName"?, "type", "referencedCollectionId"? }],
+//       "items": [{ "<fieldKey>": value, ... }] }] }
+// Reference fields: order collections so targets come FIRST. A REFERENCE value is the
+// target item's index in ITS collection's items array; MULTI_REFERENCE is an array of
+// indices. An IMAGE value is a verified https url STRING, { "prompt": "..." }
+// (AI-generated), or { "path": "..." } (a local file the user supplied, uploaded).
+//
+// Seeding is ADDITIVE — never deletes or overwrites existing content. Unexpected shapes →
+// read the live API reference; authoritative source recipe:
+// wix-headless/references/inline-recipes/setup-cms.md.
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolveItemImages } from "../../shared/seed/images.mjs";
+
+const API = "https://www.wixapis.com";
+const WIX_DATA_APP_ID = "e593b0bd-b783-45b8-97c2-873d42aacaf4";
+
+// Public collection default: read MUST be "ANYONE" or a visitor query silently returns 0
+// items (the single most common "empty page" cause). Other presets: SEED.md.
+const DEFAULT_PERMISSIONS = { insert: "ADMIN", update: "ADMIN", remove: "ADMIN", read: "ANYONE" };
+
+export function makeCtx({ cwd = process.cwd() } = {}) {
+  const config = JSON.parse(readFileSync(`${cwd}/wix.config.json`, "utf8"));
+  const siteId = config.siteId ?? config.projectId;
+  if (!siteId) throw new Error("wix.config.json has no siteId — is this a Wix CLI project?");
+  const token = execFileSync("npx", ["@wix/cli@latest", "token", "--site", siteId], {
+    encoding: "utf8",
+    cwd,
+  }).trim();
+  if (!token) throw new Error("The Wix CLI returned no token — run `npx @wix/cli@latest login` first.");
+  return { token, siteId };
+}
+
+async function req(ctx, path, { method = "POST", body } = {}) {
+  const res = await fetch(API + path, {
+    method,
+    headers: {
+      Authorization: `Bearer ${ctx.token}`,
+      "wix-site-id": ctx.siteId,
+      "Content-Type": "application/json",
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 400)}`);
+  return json;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// A fresh site's Wix Data backend can transiently fail its FIRST calls while provisioning —
+// 403, 400 WDE0117 ("MetaSite not found"), or 5xx. Retry the same body ONCE after ~3s, then
+// fail loud (never loop).
+async function reqRetryOnce(ctx, path, opts) {
+  try {
+    return await req(ctx, path, opts);
+  } catch (e) {
+    const m = String(e.message);
+    if (/-> (403|5\d\d):/.test(m) || m.includes("WDE0117")) {
+      await sleep(3000);
+      return req(ctx, path, opts);
+    }
+    throw e;
+  }
+}
+
+// ---- operations ----------------------------------------------------------------------------------
+
+// Idempotent; strictly only needed when a data call errors WDE0110 (app not installed).
+// docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
+export async function installDataApp(ctx) {
+  try {
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+      tenant: { tenantType: "SITE", id: ctx.siteId },
+      appInstance: { appDefId: WIX_DATA_APP_ID, enabled: true },
+    } });
+  } catch {
+    /* already installed is fine */
+  }
+}
+
+// The binding key is referencedCollectionId — the docs' stale `referencedCollection` is
+// accepted with a 200 but stores an EMPTY target, leaving every later link silently dead.
+// MULTI_REFERENCE additionally REQUIRES referencingFieldKey — the auto-created back-reference
+// field on the referenced collection (400 without it); synthesized from the owning
+// collection + field when the plan doesn't name one.
+function buildField(f, collectionId) {
+  const out = { key: f.key, displayName: f.displayName ?? f.key, type: f.type };
+  if (f.type === "MULTI_REFERENCE" || f.type === "REFERENCE") {
+    if (!f.referencedCollectionId) {
+      throw new Error(`field "${f.key}": ${f.type} requires referencedCollectionId`);
+    }
+    out.typeMetadata =
+      f.type === "MULTI_REFERENCE"
+        ? { multiReference: {
+            referencedCollectionId: f.referencedCollectionId,
+            referencingFieldKey: f.referencingFieldKey ?? `${collectionId}_${f.key}`.replace(/[^a-zA-Z0-9_]/g, "_"),
+            referencingDisplayName: f.referencingDisplayName ?? `${displayNameOf(collectionId)} (${f.key})`,
+          } }
+        : { reference: { referencedCollectionId: f.referencedCollectionId } };
+  }
+  return out;
+}
+
+const displayNameOf = (id) => String(id).replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+
+// The permissions block is MANDATORY. 409 WDE0104 (already exists) is fine — additive.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-collections/create-data-collection.md
+export async function createCollection(ctx, { id, displayName, fields = [], permissions }) {
+  try {
+    await reqRetryOnce(ctx, "/wix-data/v2/collections", { body: { collection: {
+      id,
+      displayName: displayName ?? id,
+      fields: fields.map((f) => buildField(f, id)),
+      permissions: permissions ?? DEFAULT_PERMISSIONS,
+    } } });
+    return { id, created: true };
+  } catch (e) {
+    const m = String(e.message);
+    if (m.includes("WDE0104") || m.includes("-> 409:")) return { id, created: false };
+    throw e;
+  }
+}
+
+// An IMAGE field stores a permanent Wix Media URL — an external url must be imported first;
+// a { "prompt": ... } value is generated (Wix AI, 1 credit) then imported. Both live in the
+// shared util (parallel, resilient, never blocks the seed).
+export { importImage } from "../../shared/seed/images.mjs";
+
+// Ids come from results[].dataItem.id (there is no results[].item key).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-insert-data-items.md
+export async function bulkInsertItems(ctx, dataCollectionId, dataItems) {
+  const r = await reqRetryOnce(ctx, "/wix-data/v2/bulk/items/insert", { body: {
+    dataCollectionId,
+    dataItems: dataItems.map((data) => ({ data })),
+    returnEntity: true,
+  } });
+  const results = [...(r.results ?? [])].sort(
+    (a, b) => (a.itemMetadata?.originalIndex ?? 0) - (b.itemMetadata?.originalIndex ?? 0),
+  );
+  return {
+    ids: results.map((res) => res.dataItem?.id ?? res.itemMetadata?.id),
+    failures: r.bulkActionMetadata?.totalFailures ?? 0,
+  };
+}
+
+// Body key is dataItemReferences with referringItemFieldName/referringItemId/referencedItemId
+// — the natural-looking `references` shape is rejected with 400 WDE0080.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-insert-data-item-references.md
+export async function insertReferences(ctx, dataCollectionId, dataItemReferences) {
+  if (!dataItemReferences.length) return 0;
+  const r = await req(ctx, "/wix-data/v2/bulk/items/insert-references", {
+    body: { dataCollectionId, dataItemReferences },
+  });
+  return r.bulkActionMetadata?.totalSuccesses ?? dataItemReferences.length;
+}
+
+// A 200 on insert does NOT prove persistence — query back and count.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-data-items.md
+export async function verifyItems(ctx, dataCollectionId) {
+  const r = await reqRetryOnce(ctx, "/wix-data/v2/items/query", { body: { dataCollectionId } });
+  return (r.dataItems ?? []).length;
+}
+
+// plan item -> insert `data`, per field type. MULTI_REFERENCE values are silently dropped by
+// the insert endpoint (200, no error) — stripped here and wired after; a single REFERENCE is
+// set at insert as the target item's _id. DATE/DATETIME wrap as { "$date": iso }; RICH_TEXT
+// is an HTML string stored verbatim; IMAGE values were resolved to Wix Media files up front
+// (imageFiles, keyed by imageKey) — a failed image leaves the field unset.
+function buildItemData(col, item, idsByCollection, multiRefs, itemIndex, counters, imageFiles) {
+  const fieldsByKey = new Map((col.fields ?? []).map((f) => [f.key, f]));
+  const data = {};
+  for (const [key, value] of Object.entries(item)) {
+    const f = fieldsByKey.get(key);
+    // A key the schema doesn't have is silently dropped by the API — fail loud instead.
+    if (!f) throw new Error(`"${col.id}" item ${itemIndex}: key "${key}" is not in the collection's fields`);
+    if (value == null) continue;
+    if (f.type === "MULTI_REFERENCE") {
+      for (const targetIndex of [].concat(value)) {
+        multiRefs.push({ itemIndex, fieldKey: key, targetCollectionId: f.referencedCollectionId, targetIndex });
+      }
+      continue;
+    }
+    if (f.type === "REFERENCE") {
+      const targetId = (idsByCollection.get(f.referencedCollectionId) ?? [])[value];
+      if (!targetId) {
+        throw new Error(
+          `"${col.id}" item ${itemIndex}: REFERENCE "${key}" -> "${f.referencedCollectionId}"[${value}] — ` +
+            `target not created yet (order collections so targets come first)`,
+        );
+      }
+      data[key] = targetId;
+      continue;
+    }
+    if (f.type === "IMAGE") {
+      const file = imageFiles.get(imageKey(col.id, itemIndex, key));
+      if (file) {
+        data[key] = file.url;
+        counters.imagesImported++;
+      }
+      continue;
+    }
+    if (f.type === "DATE" || f.type === "DATETIME") {
+      data[key] = { $date: new Date(value).toISOString() };
+      continue;
+    }
+    data[key] = value;
+  }
+  return data;
+}
+
+const imageKey = (colId, itemIndex, fieldKey) => `${colId}${itemIndex}${fieldKey}`;
+
+// Every IMAGE value across the plan (a url string or { prompt }), resolved to Wix Media files
+// in ONE parallel wave before any insert. Returns Map<imageKey, { id, url } | absent>.
+async function resolveAllImages(ctx, collections) {
+  const keys = [];
+  const specs = [];
+  for (const col of collections) {
+    const imageFields = new Set((col.fields ?? []).filter((f) => f.type === "IMAGE").map((f) => f.key));
+    (col.items ?? []).forEach((item, i) => {
+      for (const [key, value] of Object.entries(item)) {
+        if (!imageFields.has(key) || value == null) continue;
+        keys.push(imageKey(col.id, i, key));
+        specs.push({
+          url: typeof value === "string" ? value : undefined,
+          path: typeof value === "object" ? value.path : undefined,
+          prompt: typeof value === "object" ? value.prompt : undefined,
+          displayName: `${col.id}-${i}-${key}.png`,
+        });
+      }
+    });
+  }
+  const files = specs.length ? await resolveItemImages(ctx, specs) : [];
+  const out = new Map();
+  keys.forEach((k, i) => { if (files[i]) out.set(k, files[i]); });
+  return out;
+}
+
+/**
+ * ONE-CALL seed: install → resolve every IMAGE value in one parallel wave → per collection
+ * (in plan order): create → bulk-insert → wire multi-references → verify; ids threaded in
+ * memory. The default path.
+ */
+export async function setupCms(ctx, { collections = [] } = {}) {
+  await installDataApp(ctx);
+
+  const imageFiles = await resolveAllImages(ctx, collections);
+
+  const idsByCollection = new Map();
+  const out = { collections: [] };
+  for (const col of collections) {
+    const created = await createCollection(ctx, col);
+
+    const counters = { imagesImported: 0 };
+    const multiRefs = [];
+    const dataItems = [];
+    const planItems = col.items ?? [];
+    for (let i = 0; i < planItems.length; i++) {
+      dataItems.push(buildItemData(col, planItems[i], idsByCollection, multiRefs, i, counters, imageFiles));
+    }
+
+    let ids = [];
+    let failures = 0;
+    if (dataItems.length) ({ ids, failures } = await bulkInsertItems(ctx, col.id, dataItems));
+    idsByCollection.set(col.id, ids);
+
+    const refs = multiRefs.map(({ itemIndex, fieldKey, targetCollectionId, targetIndex }) => {
+      const referringItemId = ids[itemIndex];
+      const referencedItemId = (idsByCollection.get(targetCollectionId) ?? [])[targetIndex];
+      if (!referringItemId || !referencedItemId) {
+        throw new Error(
+          `"${col.id}" item ${itemIndex}: multi-reference "${fieldKey}" -> "${targetCollectionId}"[${targetIndex}] ` +
+            `has no created id (order collections so targets come first)`,
+        );
+      }
+      return { referringItemFieldName: fieldKey, referringItemId, referencedItemId };
+    });
+    const referencesLinked = await insertReferences(ctx, col.id, refs);
+
+    out.collections.push({
+      id: col.id,
+      created: created.created,
+      inserted: ids.length,
+      failures,
+      imagesImported: counters.imagesImported,
+      referencesLinked,
+      itemsInCollection: await verifyItems(ctx, col.id),
+    });
+  }
+  return out;
+}
+
+// ---- CLI entry ----------------------------------------------------------------------------------
+
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
+if (invokedDirectly) {
+  const planPath = process.argv[2];
+  if (!planPath) {
+    console.error("usage: node seed-cms.mjs <plan.json>   (run from the project root)");
+    process.exit(1);
+  }
+  const plan = JSON.parse(readFileSync(planPath, "utf8"));
+  const ctx = makeCtx();
+  setupCms(ctx, plan)
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+}

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

@@ -0,0 +1,149 @@
+# Events — playbook
+
+The events machinery ships as files — event reads (list, by slug, by id), the visitor-public
+ticket-tier read, the exact `reserve → hosted-checkout redirect` sequence, and RSVP, typed
+end-to-end. **The presentation is yours**: you design and implement the event card, the
+events index, and the event page's registration surface on the shipped hooks/DTOs, plus the
+home page and the brand. You never write registration logic; you never skip designing.
+
+## The file map (deployed into `src/`)
+
+**Don't read the shipped files** — this table and the contracts below are everything you
+need. Open a shipped file's source only on a real fallback (runtime error / uncovered field),
+or to read a reference component's pattern.
+
+| file | what it is |
+|---|---|
+| `wix/config.ts` · `wix/sdk.ts` · `wix/media.ts` · `wix/money.ts` | shared auth seam + helpers (deploy configures; nothing to set) |
+| `wix/events/types.ts` | the DTOs (`EventSummary`, `EventDetail`, `TicketTier`, `RegistrationResult`) — contracts below |
+| `wix/events/events.ts` | `fetchEvents`, `fetchEventBySlug`, `fetchEventById` (post-checkout confirmation read) |
+| `wix/events/registration.ts` | `fetchTicketTiers`, `startTicketCheckout`, `submitRsvp` — the exact reserve→redirect sequence lives here |
+| `hooks/events/useEvents.ts` | listing + category filter — contract below |
+| `hooks/events/useEventRegistration.ts` | the whole registration state machine — contract below |
+| `components/events/EventsView.tsx` (+ `EventCard`) · `EventRegistrationView.tsx` · `EventConfirmationView.tsx` | **REFERENCE implementations** — correct, plain; build your own instead of shipping them |
+| `styles/global.css` | the design system: Tailwind v4 + the `@theme` token block (shared across verticals) |
+
+Astro stack additionally gets:
+
+| file | what it is |
+|---|---|
+| `layouts/SiteLayout.astro` | site chrome — **yours to brand** (keep the `seo-tags` slot + global.css import). If another vertical is also deployed, its layout won — add an Events nav link there |
+| `pages/events.astro` | SSR listing — **keep the frontmatter**, swap the island import to YOUR component |
+| `pages/events/[slug].astro` | SSR detail + registration with owner-editable SEO — **keep the frontmatter and the SEO pieces** (`wixMetadata`, `loadSEOTagsServiceConfig`, `<SEO.Tags>`) exactly; swap the island import. The registration island stays `client:only="react"` |
+| `pages/event-confirmation.astro` | the hosted checkout's thank-you landing (`?orderNumber=&eventId=`) — **keep the route**; the shipped checkout callbacks point at it |
+
+## What you build — the design job
+
+1. **The event card + events index** — your tile (image, date eyebrow, title,
+   venue/online, price-from, sold-out badge) and rhythm, with the category filter (only when
+   >1 category), skeletons while loading, and an honest empty state — on `useEvents`.
+2. **The event page's registration surface** — branch on `event.registrationType`:
+   `TICKETING` → your tier picker (name, description, price, quantity stepper capped by
+   `limitPerCheckout`, non-`SALE_STARTED` tiers unbuyable) and the checkout CTA; `RSVP` →
+   the built-in first/last/email form (a "can't make it" option only when
+   `rsvpResponseType === "YES_AND_NO"`) and the confirmed/waitlist states; `EXTERNAL` →
+   link out; closed → an honest closed state — on `useEventRegistration`, which owns ALL
+   registration logic; you own how it looks.
+3. **The home page** — hero, featured/next events (fetch in frontmatter → your components),
+   brand story.
+
+Plus the **theme** (`@theme` block, one edit) and the **chrome** (`SiteLayout`, one pass).
+Style everything with Tailwind utilities on the tokens.
+
+### The contracts your components consume
+
+```ts
+// EventSummary (tiles) — display-ready:
+// { id, slug, title, shortDescription /* plain text */, dateLabel /* "Sep 26, 2026, 7:00 PM" */,
+//   startDateIso, locationName, locationType: "VENUE"|"ONLINE"|"TBD", imageUrl,
+//   registrationType: "RSVP"|"TICKETING"|"EXTERNAL"|"NONE",
+//   priceLabel /* "From €25.00" | "Free" | "" */, soldOut, categories: [{id,name}] }
+// EventDetail adds: aboutParagraphs: string[], registrationOpen, rsvpResponseType,
+//   externalUrl, addToCalendar: { google, ics }.
+// TicketTier: { id, name, description, price /* "€45.00" | "Free" */, free,
+//   limitPerCheckout, saleStatus /* only "SALE_STARTED" is buyable */ }
+
+// useEvents({ initialEvents? }) →
+// { events: EventSummary[]|null /* null = loading → skeletons */,
+//   categories: [{id,name}] /* derived from the loaded events */,
+//   activeCategoryId, setActiveCategoryId(id|null), error }
+
+// useEventRegistration(event: EventDetail) →
+// { tiers: TicketTier[]|null,                    // TICKETING only; null = loading
+//   quantities, setQuantity(tierId, qty),        // clamped; sale-status gated
+//   ticketCount, canCheckout,                    // gate the tickets CTA on canCheckout
+//   checkout(): Promise<RegistrationResult>,     // reserve → the browser redirects to Wix checkout
+//   rsvpValues, setRsvpValue(field, value),      // built-in fields: firstName/lastName/email
+//   canRsvp,                                     // gate the RSVP CTA on this
+//   rsvp(attending?): Promise<RegistrationResult>, // attending=false only for YES_AND_NO
+//   submitting, confirmed, error }               // confirmed: rsvpConfirmed with status
+//                                                //   "YES" | "NO" | "WAITLIST" (tell the guest!)
+```
+
+### Wiring — Astro (default)
+
+1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass — merge into the
+   existing layout instead if another vertical is deployed).
+2. Write your components under `src/components/events/` (new names — don't overwrite the
+   references), swap the island imports in `pages/events.astro` and
+   `pages/events/[slug].astro`. Listing island: `client:load` with the SSR props;
+   registration island: `client:only="react"`. Keep `pages/event-confirmation.astro`'s route.
+   **Author your surfaces in as few messages as possible** — batch multiple Writes per
+   message.
+3. Write `pages/index.astro` (home) — it exists from the scaffold; Read it before overwriting.
+
+### Wiring — React SPA (Vite etc.)
+
+Import `./styles/global.css` once at the app entry (needs `@tailwindcss/vite` in the vite
+plugins — deploy added the dep). Routes: `/events` → your listing; `/events/:slug` → fetch
+with `fetchEventBySlug(slug)` client-side, then your registration surface;
+`/event-confirmation` → the confirmation view (the checkout callbacks point at that path).
+
+## Hard rules
+
+- **Registration logic only through the shipped exports** — `useEventRegistration` /
+  `startTicketCheckout` / `submitRsvp` own the sequence (visitor-public tier read, reserve,
+  `createRedirectSession({ eventsCheckout })`, rsvpV2). Never re-derive any of it, never
+  hand-build a checkout/ticket-form URL, never route it through an API route or elevate —
+  the whole flow runs client-side as the visitor.
+- **Branch on `registrationType`** — never render an RSVP event with a ticket picker or a
+  ticketed event with an RSVP form; respect `registrationOpen`.
+- **The RSVP form is built-in** — exactly first name, last name, email; never fetch a form
+  schema or add fields.
+- **Gate CTAs on `canCheckout` / `canRsvp`** and surface `error` — `checkout()`/`rsvp()` can
+  reject (sold out, sale ended, duplicate email, payment method not configured); the message
+  is for the visitor.
+- **Confirmed states reflect REAL success**: RSVP → render only from `confirmed` (and say
+  "waitlisted", not "confirmed", for status `WAITLIST`). Tickets → the only success surface
+  is `/event-confirmation` with Wix's `?orderNumber=` params; a visitor merely returning to
+  the event page is NOT a success signal.
+- Theme via the `@theme` tokens; no parallel theme files, no hardcoded palettes.
+- Live data or an honest empty state — never mock events, tiers, or "X spots left".
+- Keep the detail page's SEO pieces exactly as shipped.
+
+## Point the user to their dashboard
+
+Give the owner the dashboard link plus the Events page — the deploy step's JSON printed
+`dashboardUrl`; append `/events` for event management. **Selling paid tickets needs a premium
+plan + a connected payment method** (free/RSVP events work without) — mention it.
+
+## Seeding
+
+Per `seed/SEED.md` — plain-data `plan.json` into `seed-events.mjs` from the project root.
+Seed events that exercise the UI (a ticketed event with 2 tiers, another ticketed one, a free
+RSVP event; future dates; an image per event).
+
+## Verify (before declaring done)
+
+- [ ] `/events` renders live events SSR (view-source shows titles) through YOUR components;
+      empty catalog shows your honest empty state.
+- [ ] An event page branches correctly: ticketed shows your tier picker (prices, steppers,
+      CTA disabled at zero tickets); RSVP shows the three-field form.
+- [ ] An RSVP submits end-to-end: `rsvp()` resolves, your confirmed state renders.
+- [ ] A ticketed checkout reserves and redirects to the Wix-hosted checkout (or surfaces the
+      "connect a payment method" message when the site has none — that's correct behavior).
+- [ ] `/event-confirmation` renders (the honest no-order state on a direct visit).
+- [ ] Event page view-source carries the SEO tags (Astro).
+- [ ] Card/index/registration surfaces/home are YOUR designs on the tokens; data-layer/hook
+      files unedited.
+- [ ] Dashboard links handed to the owner (+ the paid-tickets premium note when relevant).

package/skills/wix-headless-fast/references/events/app/components/events/EventConfirmationView.tsx

@@ -0,0 +1,66 @@
+// REFERENCE post-checkout confirmation: the Wix-hosted checkout redirects to
+// /event-confirmation?orderNumber=&eventId= on success — this island reads those params and
+// fetches the event for context. Mount client:only (it reads the browser URL). Landing here
+// IS the success signal for a ticket order (Wix redirects only after checkout completes);
+// the ticket PDF/QR arrives by email — echo the order number, don't invent order details.
+import { useEffect, useState } from "react";
+import { fetchEventById } from "../../wix/events/events";
+import type { EventDetail } from "../../wix/events/types";
+
+export default function EventConfirmationView({ eventsHref = "/events" }: { eventsHref?: string }) {
+  const [params] = useState(() => {
+    if (typeof window === "undefined") return { orderNumber: "", eventId: "" };
+    const q = new URLSearchParams(window.location.search);
+    return { orderNumber: q.get("orderNumber") ?? "", eventId: q.get("eventId") ?? "" };
+  });
+  const [event, setEvent] = useState<EventDetail | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    if (params.eventId) {
+      fetchEventById(params.eventId).then((e) => alive && setEvent(e));
+    }
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [params.eventId]);
+
+  if (!params.orderNumber) {
+    // Direct visit with no order in the URL — an honest state, not a fake confirmation.
+    return (
+      <div className="mx-auto max-w-lg py-16 text-center">
+        <p className="text-lg font-semibold">No order to show</p>
+        <a href={eventsHref} className="mt-4 inline-block text-sm text-foreground underline">
+          Browse events
+        </a>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto max-w-lg py-16 text-center">
+      <p className="eyebrow">Order {params.orderNumber}</p>
+      <h1 className="mt-2 text-2xl font-semibold tracking-tight">You're going! 🎟️</h1>
+      <p className="mt-3 text-sm text-muted-foreground">
+        {event ? `${event.title}${event.dateLabel ? ` — ${event.dateLabel}` : ""}. ` : ""}
+        Your tickets are on their way to your email.
+      </p>
+      {event?.addToCalendar.google && (
+        <a
+          href={event.addToCalendar.google}
+          target="_blank"
+          rel="noreferrer"
+          className="mt-6 inline-block rounded-full border border-border px-6 py-2.5 text-sm font-medium text-foreground no-underline transition-colors hover:bg-secondary"
+        >
+          Add to Google Calendar
+        </a>
+      )}
+      <div className="mt-4">
+        <a href={eventsHref} className="text-sm text-muted-foreground underline">
+          Back to events
+        </a>
+      </div>
+    </div>
+  );
+}