@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -0,0 +1,61 @@
+# Bookings — seeding
+
+Seed by **running `seed-bookings.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 Bookings app if needed, resolves a staff resource (polling — a fresh
+install provisions the owner asynchronously), and creates everything in the right order.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/references/bookings/seed/seed-bookings.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to 3 services** (the seed
+shows the shape; the owner adds the rest in the dashboard) and make them exercise the UI:
+mix APPOINTMENT and CLASS when it fits the business, include ≥1 free/pay-in-person service,
+and give every service an image — the default is an `imagePrompt` (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 `imagePath` (a file on this
+machine — uploaded to Wix Media) or `imageUrl` (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 service text-only.
+
+```json
+{
+  "services": [
+    { "type": "APPOINTMENT", "name": "Deep Tissue Massage", "tagLine": "60 minutes of relief",
+      "description": "…", "price": 85, "duration": 60, "category": "Massage",
+      "imageUrl": "https://…" },
+    { "type": "APPOINTMENT", "name": "Intro Consultation", "description": "…", "free": true,
+      "duration": 30, "category": "Massage", "imageUrl": "https://…" },
+    { "type": "CLASS", "name": "Morning Yoga", "description": "…", "price": 20, "capacity": 12,
+      "category": "Classes", "imageUrl": "https://…",
+      "sessions": [
+        { "start": "2026-09-01T09:00:00", "end": "2026-09-01T10:00:00" },
+        { "start": "2026-09-03T09:00:00", "end": "2026-09-03T10:00:00" }
+      ] }
+  ]
+}
+```
+
+- `type` — `APPOINTMENT` (visitor picks a free slot; needs `duration` in minutes) or `CLASS`
+  (fixed `sessions` you schedule here — **future local wall-clock** `YYYY-MM-DDThh:mm:ss`, no Z;
+  a CLASS without sessions shows no bookable times).
+- `price` — a number; omit or `free: true` → a no-fee, pay-in-person service (books without
+  checkout). The site currency wins over `currency`.
+- `category` — a name; created idempotently. Every service gets one (required for live-site
+  visibility) — uncategorized services fall into a default "Services" category.
+- Staff: appointments are auto-assigned to the site's default staff resource; the flow books
+  with ANY_RESOURCE when the visitor doesn't choose.
+
+**Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
+seems needed.
+
+## Escape hatch — individual functions
+`setupBookings` composes exported steps — `installBookingsApp`, `queryStaffWithRetry`,
+`createCategories`, `createServices`, `scheduleClassSessions`, `importImage`,
+`attachServiceImage`, 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-bookings.md`.

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

@@ -0,0 +1,302 @@
+// Bookings 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/bookings/seed/seed-bookings.mjs plan.json
+//
+// It mints its own site token via the Wix CLI, installs the Wix Bookings app if needed,
+// resolves a staff resource (polling — a fresh install provisions the owner async), creates
+// categories (idempotent by name) and services (bulk; APPOINTMENT + CLASS mixed), schedules
+// CLASS sessions, and imports+attaches images. Prints a JSON result to stdout.
+//
+// Plan shape (see SEED.md):
+//   { "services": [{ "type": "APPOINTMENT"|"CLASS", "name", "description", "tagLine"?,
+//                    "price"?, "free"?, "duration"? (APPOINTMENT, minutes), "capacity"?,
+//                    "category"? (name), "imageUrl"? | "imagePrompt"?,
+//                    "sessions"?: [{ "start", "end", "capacity"? }] }] }   // CLASS only; local "YYYY-MM-DDThh:mm:ss"
+//
+// 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-bookings.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 BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+
+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));
+
+function slugify(name) {
+  return String(name || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+// plain service -> flat Services V2 create object. price omitted / free:true -> NO_FEE.
+function buildService(s) {
+  const isAppointment = s.type === "APPOINTMENT";
+  const free = s.free === true || s.price == null;
+  const out = {
+    type: s.type,
+    name: s.name,
+    description: s.description,
+    tagLine: s.tagLine,
+    defaultCapacity: s.capacity ?? (isAppointment ? 1 : undefined),
+    onlineBooking: { enabled: true, requireManualApproval: false, allowMultipleRequests: false },
+    payment: free
+      ? { rateType: "NO_FEE", options: { online: false, inPerson: true } }
+      : {
+          rateType: "FIXED",
+          fixed: { price: { value: String(s.price), currency: s.currency ?? "USD" } },
+          options: { online: true, inPerson: false },
+        },
+    category: { id: s.categoryId }, // mandatory for live-site visibility
+    locations: [{ type: "BUSINESS" }], // never OWNER_BUSINESS on the services endpoint
+  };
+  if (isAppointment) {
+    out.schedule = { availabilityConstraints: { sessionDurations: [s.duration ?? 60] } };
+    out.staffMemberIds = s.staffMemberIds; // resourceId(s) — non-empty or MISSING_APPOINTMENT_RESOURCES
+  }
+  return out;
+}
+
+// ---- operations ----------------------------------------------------------------------------------
+
+// docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
+export async function installBookingsApp(ctx) {
+  try {
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+      tenant: { tenantType: "SITE", id: ctx.siteId },
+      appInstance: { appDefId: BOOKINGS_APP_ID, enabled: true },
+    } });
+  } catch {
+    /* already installed is fine */
+  }
+}
+
+// ⚠️ staffMemberIds takes resourceId, NOT the staff id.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/query-staff-members.md
+export async function queryStaff(ctx) {
+  const r = await req(ctx, "/bookings/v1/staff-members/query", {
+    body: { query: {}, fields: ["RESOURCE_DETAILS"] },
+  });
+  return (r.staffMembers ?? []).map((m) => ({ resourceId: m.resourceId, id: m.id, name: m.name }));
+}
+
+// A fresh install provisions the default "Business Owner" resource ASYNC — poll until it lands.
+export async function queryStaffWithRetry(ctx, { tries = 15, delayMs = 2000 } = {}) {
+  let lastErr;
+  for (let i = 0; i < tries; i++) {
+    try {
+      const s = await queryStaff(ctx);
+      if (s.length) return s;
+    } catch (e) {
+      lastErr = e;
+    }
+    if (i < tries - 1) await sleep(delayMs);
+  }
+  if (lastErr) throw lastErr;
+  return [];
+}
+
+// Every service needs a category.id or it's invisible on the live site. Idempotent by name.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/query-categories.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/create-category.md
+export async function createCategories(ctx, names) {
+  const existing = await req(ctx, "/bookings/v2/categories/query", { body: { query: {} } });
+  const byName = new Map((existing.categories ?? []).map((c) => [c.name, { id: c.id, name: c.name }]));
+  const out = [];
+  for (const name of names) {
+    let cat = byName.get(name);
+    if (!cat) {
+      const r = await req(ctx, "/bookings/v2/categories", { body: { category: { name } } });
+      cat = { id: r.category?.id, name };
+      byName.set(name, cat);
+    }
+    out.push(cat);
+  }
+  return out;
+}
+
+// Bulk-create services (APPOINTMENT + CLASS mixed). Run AFTER staff + categories.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services.md
+export async function createServices(ctx, services) {
+  const body = { services: services.map(buildService), returnEntity: true };
+  const r = await req(ctx, "/bookings/v2/bulk/services/create", { body });
+  return (r.results ?? []).map((res, i) => {
+    const item = res.item ?? {};
+    return {
+      id: item.id ?? res.itemMetadata?.id,
+      slug: item.mainSlug?.name ?? slugify(item.name ?? services[i]?.name),
+      revision: item.revision,
+      type: item.type ?? services[i]?.type,
+      scheduleId: item.schedule?.id,
+      success: res.itemMetadata?.success ?? false,
+      error: res.itemMetadata?.error,
+    };
+  });
+}
+
+// CLASS only: schedule sessions (bulk Calendar Events V3). start/end are LOCAL wall-clock
+// "YYYY-MM-DDThh:mm:ss" (no Z), today-or-future.
+// docs: https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event.md
+export async function scheduleClassSessions(ctx, sessions) {
+  const body = {
+    events: sessions.map((s) => ({
+      event: {
+        scheduleId: s.scheduleId,
+        type: "CLASS",
+        start: { localDate: s.start },
+        end: { localDate: s.end },
+        resources: [{ id: s.resourceId, permissionRole: "WRITER" }], // non-empty + WRITER, else UNKNOWN_ROLE
+        ...(s.capacity != null ? { totalCapacity: s.capacity } : {}),
+      },
+    })),
+  };
+  const r = await req(ctx, "/calendar/v3/bulk/events/create", { body });
+  return (r.results ?? []).map((res) => ({
+    id: res.itemMetadata?.id,
+    success: res.itemMetadata?.success ?? false,
+    error: res.itemMetadata?.error,
+  }));
+}
+
+// Bookings binds a service image by Wix Media file ID — an external url must be imported
+// first; a plan `imagePrompt` 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";
+
+// Writes under media.mainMedia + media.coverMedia (writing media.image 200s but silently drops).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/update-service.md
+export async function attachServiceImage(ctx, it) {
+  return req(ctx, `/bookings/v2/services/${it.serviceId}`, {
+    method: "PATCH",
+    body: {
+      service: {
+        id: it.serviceId,
+        revision: it.revision,
+        media: { mainMedia: { image: it.image }, coverMedia: { image: it.image } },
+      },
+    },
+  });
+}
+
+/**
+ * ONE-CALL seed: install → resolve staff (poll) → categories → services → CLASS sessions →
+ * images, ids threaded in memory. The default path.
+ */
+export async function setupBookings(ctx, { services = [], staffResourceId } = {}) {
+  await installBookingsApp(ctx);
+
+  let resourceId = staffResourceId;
+  if (!resourceId) {
+    const staff = await queryStaffWithRetry(ctx);
+    resourceId = staff[0]?.resourceId;
+  }
+  if (!resourceId) throw new Error("No staff resource resolved — Bookings provisioning may still be in progress; re-run the seed.");
+
+  const catNames = [...new Set(services.map((s) => s.category).filter(Boolean))];
+  const cats = catNames.length ? await createCategories(ctx, catNames) : await createCategories(ctx, ["Services"]);
+  const catIdByName = new Map(cats.map((c) => [c.name, c.id]));
+  const defaultCatId = cats[0]?.id;
+
+  const created = await createServices(ctx, services.map((s) => ({
+    type: s.type,
+    name: s.name,
+    description: s.description,
+    tagLine: s.tagLine,
+    price: s.price,
+    currency: s.currency,
+    free: s.free,
+    duration: s.duration,
+    capacity: s.capacity,
+    categoryId: (s.category ? catIdByName.get(s.category) : undefined) ?? defaultCatId,
+    staffMemberIds: s.staffMemberIds ?? (s.type === "APPOINTMENT" ? [resourceId] : undefined),
+  })));
+
+  const sessions = [];
+  created.forEach((c, i) => {
+    const plan = services[i];
+    if (c.type === "CLASS" && c.scheduleId && Array.isArray(plan?.sessions)) {
+      for (const ses of plan.sessions) {
+        sessions.push({ scheduleId: c.scheduleId, resourceId, start: ses.start, end: ses.end, capacity: ses.capacity ?? plan.capacity });
+      }
+    }
+  });
+  const scheduled = sessions.length ? await scheduleClassSessions(ctx, sessions) : [];
+
+  // Pass 2 — images: resolve (import by url / generate by prompt) in one parallel wave, then
+  // attach. Failures leave the service text-only; the seed's exit never depends on images.
+  const files = await resolveItemImages(ctx, created.map((c, i) => ({
+    url: services[i]?.imageUrl,
+    path: services[i]?.imagePath,
+    prompt: services[i]?.imagePrompt,
+    displayName: `${c?.slug || "service"}.png`,
+  })));
+  let imagesAttached = 0;
+  for (let i = 0; i < created.length; i++) {
+    if (!files[i] || !created[i]?.id) continue;
+    try {
+      await attachServiceImage(ctx, {
+        serviceId: created[i].id,
+        revision: created[i].revision,
+        image: { id: files[i].id, url: files[i].url, width: 1024, height: 1024 },
+      });
+      imagesAttached++;
+    } catch {
+      /* never block on image failure — the service stays text-only */
+    }
+  }
+
+  return {
+    services: created,
+    categories: cats,
+    resourceId,
+    sessionsScheduled: scheduled.filter((s) => s.success).length,
+    imagesAttached,
+  };
+}
+
+// ---- 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-bookings.mjs <plan.json>   (run from the project root)");
+    process.exit(1);
+  }
+  const plan = JSON.parse(readFileSync(planPath, "utf8"));
+  const ctx = makeCtx();
+  setupBookings(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/cms/INSTRUCTIONS.md

@@ -0,0 +1,179 @@
+# CMS — playbook
+
+The data machinery ships as files — typed reads/writes over ANY collection, hooks, and the
+normalization layer (dates → ISO strings, `wix:image://` → https URLs), correct end-to-end.
+CMS is schema-generic, so unlike other verticals there are **no fixed pages**: the seed plan
+(`plan.json`) is the site's content model, and **you design the pages from it** — a listing
+surface and an item page per content collection, plus the home page and the brand. You never
+write data-access 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).
+
+| 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/cms/types.ts` | the DTOs (`CmsItem`, `CmsFilter`, `CmsSort`, `CmsQuery`, `CmsPage`) — contracts below |
+| `wix/cms/items.ts` | `queryItems`, `getItemById`, `getItemBy`, `countItems`, `insertItem`, `updateItem`, `patchItemFields`, `removeItem` |
+| `hooks/cms/useCollection.ts` | list state + skip paging — contract below |
+| `hooks/cms/useItem.ts` | one item by `_id` or slug field — contract below |
+| `styles/global.css` | the design system: Tailwind v4 + the `@theme` token block (shared across verticals) |
+
+There are **no shipped components** — the data layer and hooks are the machinery; every
+component is yours.
+
+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 your content nav links there |
+
+There are **no shipped pages** — you author them (below).
+
+## What you build — the design job
+
+Read the seed plan first: its collections, field keys, and permissions are the contract your
+pages bind to (collection ids and field keys verbatim).
+
+1. **A listing surface per content collection** — your card (image, title, secondary fields)
+   and rhythm, with skeletons while loading and an honest empty state — on `useCollection`
+   (or SSR via `queryItems` alone when the page needs no interactivity).
+2. **An item page per collection with a `slug` field** — your detail layout on the DTO
+   (SSR fetch via `getItemBy`), with a real 404 on miss.
+3. **The home page** — hero, featured items (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
+// CmsItem — display-ready, fields FLAT on the item (never item.data.*):
+// { _id, _createdDate?, _updatedDate?, _owner?, ...fields }
+//   TEXT/URL/EMAIL → string · NUMBER → number · BOOLEAN → boolean
+//   DATE/DATETIME → ISO string (render: new Date(iso).toLocaleDateString())
+//   IMAGE → resolved https URL (straight into <img src>; guard the absent case)
+//   RICH_TEXT → the stored HTML string (render via set:html on a wrapper you control)
+//   REFERENCE/MULTI_REFERENCE → id(s); full CmsItem(s) when queried with include
+
+// queryItems(collectionId, { filters?, sort?, limit?, skip?, include?, withTotal? })
+//   → { items: CmsItem[], hasNext, total }        // filters: [{ field, op, value }]
+//     ops: eq ne gt ge lt le contains startsWith hasSome hasAll isEmpty isNotEmpty
+//     DATE comparands must be Date objects (an ISO string matches nothing)
+// getItemBy(collectionId, field, value) → CmsItem | null      // slug routing
+// getItemById(collectionId, id) → CmsItem | null
+// countItems(collectionId, filters?) → number
+
+// useCollection(collectionId, { filters?, sort?, limit?, include?, initialItems?, initialHasNext? })
+// → { items: CmsItem[]|null /* null = loading → skeletons */,
+//     hasNext, loadMore(), loadingMore, error }   // changing filters/sort refetches
+
+// useItem(collectionId, { id } | { by: { field, value } }, { initialItem? })
+// → { item: CmsItem|null, notFound, error }       // notFound → your 404/miss state
+
+// Writes (only when the collection's permissions allow the caller):
+// insertItem(collectionId, data)                  // dates as Date objects; never set _owner
+// patchItemFields(collectionId, id, fields)       // the safe partial change
+// updateItem(collectionId, item)                  // REPLACES the whole item — see hard rules
+// removeItem(collectionId, id)
+```
+
+### Wiring — Astro (default)
+
+1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass) and add one nav
+   link per content surface.
+2. Author your pages under `src/pages/` — SSR fetch in the frontmatter, DTO props to your
+   islands (`client:load`; a page with no interactivity needs no island at all). Listing:
+
+   ```astro
+   ---
+   import SiteLayout from "../layouts/SiteLayout.astro";
+   import { queryItems } from "../wix/cms/items";
+   import type { CmsPage } from "../wix/cms/types";
+   let page: CmsPage = { items: [], hasNext: false, total: null };
+   try {
+     page = await queryItems("recipes", { sort: [{ field: "publishDate", direction: "desc" }] });
+   } catch {
+     // an unguarded SSR throw truncates the response mid-stream
+   }
+   ---
+   ```
+
+   Item page (`src/pages/recipes/[slug].astro`): `getItemBy("recipes", "slug", Astro.params.slug!)`
+   in the frontmatter; `return new Response(null, { status: 404 })` on null. SEO is plain
+   `<title>`/`<meta name="description">` from the DTO via the layout props — CMS collections
+   have **no owner-editable SEO item type**, so don't copy another vertical's
+   `wixMetadata`/`<SEO.Tags>` wiring.
+3. **Author your surfaces in as few messages as possible** — batch multiple Writes per
+   message (components and pages are independent files).
+
+### 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 are yours: a list route per collection on
+`useCollection`, a detail route on `useItem` with `by: { field: "slug", value }`.
+
+## Hard rules
+
+- **Data only through the shipped exports** — never re-derive a Wix Data request, never
+  import `@wix/data` directly in your components, never hand-build a `static.wixstatic.com`
+  URL.
+- **The id is `_id`, fields are flat** — `item.id` is undefined; `item.data.title` is the
+  REST shape and reads undefined.
+- **Bind by the seed plan's ids and keys verbatim** — collection ids have no namespace; a
+  mistyped field key reads as a blank, not an error.
+- **An empty read on a PUBLIC collection is a seed permissions bug** (`read` must be
+  `ANYONE`) — fix the seed, never reach for `auth.elevate` (it doesn't exist on this path).
+  On a member-scoped collection an empty anonymous read is the gate working, not a bug.
+- **`updateItem` REPLACES the whole item** — omitted fields are wiped. Spread the full item,
+  or use `patchItemFields`. Date fields on any write are Date objects — a round-tripped ISO
+  string is silently stored as text and breaks date queries.
+- **Writes 403 unless the collection was seeded with that verb open** — surface a 403 as a
+  permissions setup step (which permission, where in the dashboard), not a code bug.
+- **User-created content is a CMS contribution flow.** For a member or visitor submission that
+  the app must later list, use the seeded CMS collection and its intended permission preset.
+  If the operation needs elevated access — especially a browser-created file that must enter
+  Media Manager — follow `references/shared/CUSTOM_OPERATIONS.md`: validate the caller and
+  input in a narrow server endpoint before elevating one documented operation. Never call a
+  privileged Media API directly from a client island.
+- **Use the shipped upload capability when it fits.** Declare its named policy in
+  `plan.capabilities.mediaUpload`; Fast deploys the endpoint, client helper, dependencies, and
+  generated policy module. Your CMS surface calls `uploadMedia(policyId, file)` and stores the
+  returned Wix Media reference. Do not author another upload endpoint for that flow.
+- **RICH_TEXT is HTML, not plain text** — render it with `set:html` (Astro) /
+  `dangerouslySetInnerHTML` (React) on a wrapper; never interpolate it as text.
+- Reference fields hold ids unless the query passed `include` — don't render an id as
+  content.
+- Guard absent IMAGE fields — render a fallback, never an empty/broken `<img>`.
+- Theme via the `@theme` tokens; no parallel theme files, no hardcoded palettes.
+- Live data or an honest empty state — never mock items or invent fields not in the plan.
+
+## Point the user to their dashboard
+
+Give the owner the dashboard link — the deploy step's JSON printed `dashboardUrl`; append
+`/wix-cms` for the collections area (items, fields, and More Actions → Permissions &
+Privacy live there).
+
+## Seeding
+
+Per `seed/SEED.md` — plain-data `plan.json` into `seed-cms.mjs` from the project root. The
+plan is the content model your pages bind to: design collections that exercise the UI
+(a `slug` field per detail page, an IMAGE field with a verified `imageUrl` per item, a DATE
+field when the content is chronological).
+
+## Verify (before declaring done)
+
+- [ ] Each listing page renders live items SSR (view-source shows titles) through YOUR
+      components; an empty collection shows your honest empty state (no mock items).
+- [ ] Item pages resolve by slug with a real 404 on a bad slug.
+- [ ] Images render (resolved https URLs, no raw `wix:image://`); absent images fall back
+      gracefully.
+- [ ] Dates render formatted (no "Invalid Date", no raw ISO strings in copy).
+- [ ] RICH_TEXT renders formatted (no visible HTML tags, no `[object Object]`).
+- [ ] Any 403 surfaced as a permissions step with the dashboard link.
+- [ ] Listing/item/home surfaces are YOUR designs on the tokens; data-layer/hook files
+      unedited.
+- [ ] Dashboard link handed to the owner.

package/skills/wix-headless-fast/references/cms/app/hooks/cms/useCollection.ts

@@ -0,0 +1,83 @@
+// One collection as list state. SSR-friendly: pass server-fetched items as `initialItems`
+// (Astro frontmatter / server component) and no client fetch happens for the first page; a
+// SPA passes nothing. Changing filters/sort (by value) refetches; loadMore() appends the
+// next page (skip paging).
+import { useCallback, useEffect, useRef, useState } from "react";
+import { queryItems } from "../../wix/cms/items";
+import type { CmsFilter, CmsItem, CmsSort } from "../../wix/cms/types";
+
+export interface UseCollectionOptions {
+  filters?: CmsFilter[];
+  sort?: CmsSort[];
+  /** Page size (default 20). */
+  limit?: number;
+  /** Reference field keys to inline as full items. */
+  include?: string[];
+  /** Server-fetched first page — must come from the SAME query (filters/sort/limit/include). */
+  initialItems?: CmsItem[];
+  /** The server fetch's hasNext. Omitted → inferred (a full first page ⇒ assume more). */
+  initialHasNext?: boolean;
+}
+
+export interface UseCollection {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  items: CmsItem[] | null;
+  hasNext: boolean;
+  loadMore: () => void;
+  loadingMore: boolean;
+  error: string | null;
+}
+
+export function useCollection(collectionId: string, options: UseCollectionOptions = {}): UseCollection {
+  const { filters, sort, limit = 20, include, initialItems, initialHasNext } = options;
+  // Query identity by value — Dates in filters serialize to ISO, so this is stable.
+  const key = JSON.stringify([collectionId, filters ?? null, sort ?? null, limit, include ?? null]);
+  const initialKey = useRef<string | null>(initialItems ? key : null);
+  const [items, setItems] = useState<CmsItem[] | null>(initialItems ?? null);
+  const [hasNext, setHasNext] = useState<boolean>(
+    initialHasNext ?? (initialItems ? initialItems.length >= limit : false),
+  );
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const itemsRef = useRef<CmsItem[] | null>(items);
+  itemsRef.current = items;
+
+  useEffect(() => {
+    if (initialKey.current === key) return; // the SSR pass already answered this exact query
+    initialKey.current = null;
+    let alive = true;
+    setItems(null);
+    setError(null);
+    queryItems(collectionId, { filters, sort, limit, include })
+      .then((page) => {
+        if (!alive) return;
+        setItems(page.items);
+        setHasNext(page.hasNext);
+      })
+      .catch((e) => {
+        if (!alive) return;
+        setItems([]);
+        setError(e instanceof Error ? e.message : String(e));
+      });
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  const loadMore = useCallback(() => {
+    const current = itemsRef.current;
+    if (!current || loadingMore) return;
+    setLoadingMore(true);
+    queryItems(collectionId, { filters, sort, limit, include, skip: current.length })
+      .then((page) => {
+        setItems([...(itemsRef.current ?? []), ...page.items]);
+        setHasNext(page.hasNext);
+      })
+      .catch((e) => setError(e instanceof Error ? e.message : String(e)))
+      .finally(() => setLoadingMore(false));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, loadingMore]);
+
+  return { items, hasNext, loadMore, loadingMore, error };
+}