@wix/agent-skills 1.35.1 → 1.36.1

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

@@ -1,178 +0,0 @@
-# Wix CMS — client utils (you build the UI)
-
-Unlike the other verticals, CMS ships **no UI**. A CMS is schema-driven — every collection is
-different — so there are no meaningful "list/detail" components to hand you. You **build the UI
-yourself** (list, detail, home) in your own framework and design tokens, calling the shipped
-**utils**. **A visitor-fillable form is the `forms` vertical, not `cms`** — come here only when the
-app must read the entries back (a public gallery, a listing, a member's "my submissions"); a visitor
-cannot read Forms submissions. Everything talks to Wix directly over the public `WIX_CLIENT_ID`
-(anonymous visitor token) using the official Wix Data endpoints — never hand-build a Wix Data URL,
-never mock items.
-
-## What ships (utils only)
-
-| file | what it is |
-|---|---|
-| `rest/wix-cms.js` | Wix Data helpers over the official endpoints: `queryDataItems`, `getDataItem`, `getDataItemBy`, `countDataItems`, `insertDataItem`, `updateDataItem`, `removeDataItem`. |
-| `lib/wixImage.js` | `wixImage(uri)` — converts a `wix:image://…` media field into a renderable URL (passes `https://` / `//` through). |
-| `collection.config.js` | Optional one-file mapping: `COLLECTION_ID` (your collection's **name**, not a GUID) + `FIELDS` (map `title`/`image`/`summary`/`body`/`date`/`slug` to your field keys). Keeps field mapping in one place; skip it and pass field keys inline if you prefer. |
-| `wix-config.js` *(shared)* | the two ids, written by the install step. |
-| `WixManageBanner` *(shared)* | Dev-only manage banner — mount it in your Layout (see the platform doc's "Done" step). |
-
-## Prerequisites
-- A Wix **data collection** as the read target, created + seeded separately (see **Seeding**) — it may
-  be empty at build time, so render an honest empty state until items land. This skill does **not**
-  provision collections.
-- **Collection permissions** must grant the action you perform to the visitor: **read** (Show content
-  → *Everyone*) for listing/detail; **insert** only if you add a public form or member submissions;
-  update/delete are author/admin-only and **403 for a visitor**. The owner sets these in the dashboard
-  (CMS → collection → Permissions) — a separate Wix step, out of scope. A 403 before it's set is
-  expected: flag it and continue.
-
-## Build the UI from the utils
-Generate whatever the app needs — a list/grid, a detail page, a home page, a submit form — with your
-framework, your router, and your design tokens. Wire the data with the helpers below (the shapes are
-the bug-prone part). Mount the shared `WixManageBanner` (preview-only) in your Layout. Route conventions
-are yours (e.g. a list path + `/item/:slugOrId` detail).
-
-## Data shapes (load-bearing — keep this wiring)
-
-```jsx
-import { queryDataItems, getDataItem, getDataItemBy, countDataItems, insertDataItem } from "@/rest/wix-cms";
-import { wixImage } from "@/lib/wixImage";
-
-// LIST — queryDataItems resolves to { items, nextCursor } (NOT a bare array). Each item is the flat
-// `data` payload and always carries `_id`. Pass nextCursor back as `cursor` for the next page;
-// set filter/sort on the FIRST request only (cursor follow-ups reuse them — pass only the cursor).
-const { items, nextCursor } = await queryDataItems("Recipes", {
-  sort: [{ fieldName: "publishDate", order: "DESC" }],            // array of { fieldName, order } — NOT { field: -1 }
-  filter: { publishDate: { $lte: { "$date": new Date().toISOString() } } }, // dates wrap as { "$date": ISO }
-  limit: 24,
-});
-
-// DETAIL — by `_id` (getDataItem) or a slug field (getDataItemBy); returns null on miss →
-// show a not-found state, never invent an item.
-const one = await getDataItemBy("Recipes", "slug", slugFromUrl);
-
-// FILTER/SEARCH — operators: $eq $ne $gt $gte $lt $lte $in $nin $startsWith $exists $hasSome $hasAll,
-// combined with $and/$or/$not. Simple text search: { title: { $startsWith: term } }.
-
-// MULTI_REFERENCE fields are NOT inline — pass includeReferences: [{ field: "ingredients", limit: 10 }]
-// to queryDataItems, then read item.<field>.
-
-// IMAGES — a media field comes back as a `wix:image://…` URI the browser can't render. Convert every
-// image with wixImage() before <img src>: <img src={wixImage(item.cover)} />. Never render one raw.
-
-// DATES — date/datetime fields (and _createdDate/_updatedDate) come back WRAPPED: { "$date": ISO }.
-// Read through the wrapper — handing the object to `new Date()` yields an Invalid Date, which reaches
-// the page as the text "Invalid Date":
-const when = new Date(item.publishDate?.$date ?? item.publishDate);
-// Write one back in the same shape, { "$date": iso }. A FILTER accepts either that or a plain ISO string.
-
-// PUBLIC FORM — insertDataItem("Reviews", { name, email, message }); needs Insert = "Anyone" (or members).
-// Resolves to the flat inserted `data` payload (with _id); throws on failure — never fake success.
-
-// OWNED RECORDS ("my items") — insert from the CLIENT while the member is logged in, so Wix stamps
-// `_owner` with THEIR id. (An insert carrying a connector/backend token stamps the app instead, and
-// "my items" then reads back empty.)
-const { member } = useMember();                      // from the members vertical (@/context/MemberContext)
-await insertDataItem("Drawings", { title });         // member token in play → _owner = that member
-const { items: mine } = await queryDataItems("Drawings", { filter: { _owner: member.id } });
-// The member id lives at `member.id`: row fields carry a leading underscore (_id, _owner, _createdDate)
-// while the member object uses plain `id`. Give the filter a real value — `member._id` evaluates to
-// undefined, JSON.stringify drops it, and the query would match every row (or none), so the helpers
-// throw first. For rows that must stay private, seed `read: SITE_MEMBER_AUTHOR` and skip the filter:
-// the server scopes each read to its caller, and that keeps working when `member` is null (see below).
-```
-
-## Owned records (CMS × Wix members)
-Runnable recipe: see **OWNED RECORDS** in the code block above. Requires the **members** vertical (it
-supplies `useMember()`); the collection needs **Insert** for members. Always insert **client-side while
-the member is logged in** — a backend/connector-token insert stamps `_owner` with the *app*, so "my
-items" comes back empty forever.
-
-**Decide which of these you're building — the choice is a collection permission, set at seed time:**
-
-| goal | seed the collection with | how you read "mine" |
-|---|---|---|
-| public list + a personal *view* of it (e.g. a public gallery plus "my submissions") | `read: ANYONE` | `filter: { _owner: member.id }` — a **view** filter: it selects what to show, while every row stays readable by anyone |
-| rows only their owner may ever see | `read: SITE_MEMBER_AUTHOR` (the **member-private** preset in `seed/SEED.md`) | query with **no filter** — the server scopes every read to the caller |
-
-Reach for `SITE_MEMBER_AUTHOR` whenever the data is genuinely per-member: the server enforces it, and it
-holds up when `useMember().member` is `null` — which is the state a logged-in member is in whenever the
-Members Area app is absent (see the members vertical's "Identity vs. profile"), where a client-side id is
-unavailable. For a public list **and** private rows, use **two collections** — permissions are per-collection.
-
-## Images in a collection
-Reading one goes through `wixImage()` (see the code block). Writing one has two shapes, because
-**uploading to Wix Media takes a Manage-scope credential**: `generate-file-upload-url` and
-`import-file` each require `SCOPE.DC-MEDIA.MANAGE-MEDIAMANAGER`, which a member or visitor token
-never carries — a client-side upload answers **403 with an HTML body**. Pick by how the image is used:
-
-| shape | field type | reach for it when |
-|---|---|---|
-| **data URL in the item** — `canvas.toDataURL()`, or any base64 string, written straight into the row | `TEXT` | small images: canvases, signatures, thumbnails, prototypes. An item caps at **500 KB** and base64 adds about a third, so keep the source under ~350 KB. Wix's own visitor-upload tutorial takes this route. |
-| **real Wix Media asset** — a backend route uploads with an elevated credential and returns the CDN URL for the client to store | `IMAGE` | production images: CDN delivery, `wixImage()` transforms, reuse across the site, anything past that size cap |
-
-**On base44 the elevated route is a backend function** — it holds the credential the client lacks:
-```js
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");  // admin-level
-// → POST /site-media/v1/files/generate-upload-url, PUT the bytes to it, return the file URL
-```
-That's the same Wix connector the seed step uses, and it's the supported way to reach a Manage-scope
-API at runtime — a different thing from the Base44 solution kits the build rules exclude. Keep the
-asset on Wix: `base44.integrations.Core.UploadFile` parks the file on Base44 instead, which splits the
-source of truth away from the site.
-
-**Authorize that function against the Wix member**, using the member token the client sends.
-`base44.auth.me()` resolves the *Base44* account — you, the builder — so a function gated on it turns
-real visitors away, while a `test_backend_function` run passes on your own token and reads as working.
-Validate the mime type and the size there as well.
-
-- Tutorial, data URL + elevated route: https://dev.wix.com/docs/go-headless/wix-managed-headless/full-integration-astro/feature-guides/upload-images-to-cms.md
-- Generate File Upload Url: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/generate-file-upload-url.md
-- Import File: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/import-file.md
-
-## Hard rules
-- Read/write **only** through the `wix-cms.js` helpers (official Wix Data endpoints) — never hand-build a URL.
-- `queryDataItems` → `{ items, nextCursor }` (destructure, iterate `.items`); `sort` is `[{ fieldName, order }]`; date comparands wrap as `{ "$date": ISO }`.
-- Read date fields through the wrapper — `new Date(v?.$date ?? v)`. Dates arrive as `{ "$date": ISO }` (including `_createdDate` / `_updatedDate`), and `new Date(object)` puts the text "Invalid Date" on the page. See RETRIEVAL SHAPES in `rest/wix-cms.js` for the field types that need a converter.
-- Convert `wix:image://` URIs via `wixImage()` before `<img src>`.
-- Upload images from a backend route holding an elevated credential, and keep a member-submitted image under the 500 KB item cap when storing it as a data URL — a client-side Wix Media upload answers 403 (see **Images in a collection**).
-- Owner field is `_owner` (Wix Data v2), not `_ownerId`; the member id lives at `member.id`, so "my items" → `{ filter: { _owner: member.id } }` (see above).
-- **Give every filter key a defined value** — add the key only once you hold one: `...(memberId ? { _owner: memberId } : {})`. `JSON.stringify` drops `undefined`, so an undefined comparand would match every row (`{ _owner: undefined }`) or none (`{ _owner: { $eq: undefined } }`) with no error from the server; the helpers throw so it surfaces at the call site.
-- **Let the query do the scoping** (a `filter`, or `read: SITE_MEMBER_AUTHOR` for privacy) so the server returns exactly the rows to show. A wrong result means the filter or the permission needs fixing — a client-side `.filter()` over rows the browser already holds only hides the symptom.
-- `updateDataItem` **replaces** the whole item — fetch + merge first (or use Patch Data Item).
-- Render live Wix data or an honest empty state — never mock items or invent fields not in the collection.
-- Treat a 403 as a permissions setup step (tell the user which permission to grant), not a code bug.
-
-## Fallback — beyond the helpers
-Need something the helpers don't cover? Call it yourself with `wixApiRequest`, but look up the exact
-endpoint/method/body in the official Wix reference first (or use the documentation skill available in your environment) — never guess.
-- Data Items API: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items.md
-- Partial update (Patch): https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/patch-data-item.md
-- Upsert by id (Save): https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/save-data-item.md
-- Free-text search: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/search-data-items.md
-- Aggregations: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/aggregate-data-items.md
-- Distinct values (filter menus): https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-distinct-values.md
-- Referenced items: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-referenced-data-items.md
-- Collection schema / field keys: https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/get-data-collection.md
-- Member-gated / user-generated content → the **members** vertical (`references/members/INSTRUCTIONS.md`).
-
-## Seeding
-Seed the collection per `seed/SEED.md` — the Wix Data v2 REST API with curl examples (create collection
-+ permissions, bulk-insert, verify, references, images). Needs an elevated credential; separate from
-this build, run in parallel.
-
-## Point the user to their dashboard
-Substitute the site's `metaSiteId`:
-- **Collections & items** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-cms` → Create Collection, then add items.
-- **Permissions** — same CMS area → open the collection → More Actions → Permissions & Privacy. Read anonymously → **Show content: Everyone**; public/member form → **Collect content: Everyone/Members**. Update/Delete stay admin-only.
-
-## Verify
-- [ ] `WIX_CLIENT_ID` set (not the placeholder); collection name + field keys correct (from the seed plan).
-- [ ] List renders live items (`{ items, nextCursor }` destructured); pagination works; empty collection → honest empty state (no mock items).
-- [ ] Detail resolves by slug or `_id`, with a not-found state on miss.
-- [ ] Image fields render via `wixImage()` (no raw `wix:image://`).
-- [ ] Any 403 surfaced to the user as a permissions step, with the dashboard deep links.
-- [ ] Built "my items"? Signed in as **two different members** and confirmed each one sees their own rows and only those. Use two accounts: an owner filter can fail silently in either direction — every row, or zero rows — and both look plausible from a single account.

package/skills/wix-vibe-headless/references/cms/app/collection.config.js

@@ -1,31 +0,0 @@
-// collection.config.js — THE data surface. This is where you point the shipped list + detail at
-// YOUR Wix CMS collection and map its field keys to the roles the UI renders. Edit this file; do
-// NOT edit the components. It is the data-side equivalent of the design tokens in `index.css`: one
-// place, and the whole client follows.
-//
-// The item shape is USER-DEFINED — the field keys below are the ones from your own seed / design
-// plan for this collection. Carry that plan forward as the canonical list; don't guess keys or
-// reverse-engineer them from a single fetched row.
-
-// The collection NAME from your Wix dashboard (CMS → Content Manager), e.g. "Recipes", "Posts".
-// NOT a GUID — the name is the id in Wix Data.
-export const COLLECTION_ID = "<YOUR-COLLECTION>";
-
-// Map your collection's field keys → the roles the shipped UI renders. Any role you set to null is
-// skipped (the UI just omits it). `title` is the only required role.
-export const FIELDS = {
-  title:   "title",         // required — card heading + detail heading
-  image:   "image",         // media field (wix:image:// or https URL) — null if the collection has none
-  summary: "description",   // short text shown on the card
-  body:    "content",       // long HTML body shown on the detail page (rendered as HTML)
-  date:    "publishDate",   // ISO date field shown as meta + used for the default sort
-  slug:    "slug",          // human-readable field for detail URLs; null → routes fall back to _id
-};
-
-// Default list sort — an array of { fieldName, order: "ASC"|"DESC" } (Wix syntax, NOT Mongo
-// { field: -1 }). null → collection/insertion order. Uses FIELDS.date when set.
-export const SORT = FIELDS.date ? [{ fieldName: FIELDS.date, order: "DESC" }] : null;
-
-// Route key for an item: the slug value when a slug field is mapped, else the item's `_id`.
-// Both the card link and the detail route read this — one definition, so they can't drift.
-export const itemKey = (item) => (FIELDS.slug && item?.[FIELDS.slug]) || item?._id;

package/skills/wix-vibe-headless/references/cms/app/lib/wixImage.js

@@ -1,18 +0,0 @@
-// wixImage — turn a Wix CMS image field value into a URL a browser can render.
-// CMS media fields come back in two shapes and only ONE renders directly in <img src>:
-//   • a plain `https://static.wixstatic.com/...` (or protocol-relative `//...`) URL → usable as-is
-//   • a Wix media URI `wix:image://v1/<mediaId>/<filename>#originWidth=…&originHeight=…` → NOT
-//     renderable by the browser; the `<mediaId>` segment maps to a static.wixstatic.com/media/ URL.
-// Merchant-uploaded images (via the dashboard) are the `wix:image://` form; images your seed step
-// wrote are usually already `https://`. This converts both so the shipped UI never shows a broken
-// image. Returns null for an empty/unknown value (the UI shows a token surface instead).
-export function wixImage(value) {
-  if (!value || typeof value !== "string") return null;
-  if (value.startsWith("//")) return `https:${value}`;
-  if (value.startsWith("http")) return value;
-  if (value.startsWith("wix:image://")) {
-    const mediaId = value.slice("wix:image://v1/".length).split("/")[0];
-    return mediaId ? `https://static.wixstatic.com/media/${mediaId}` : null;
-  }
-  return null;
-}

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

@@ -1,231 +0,0 @@
-import { wixApiRequest } from "./wix-client.js";
-
-/**
- * Wix CMS (Wix Data) — REST helpers for reading and writing data items in site data collections.
- *
- * COLLECTIONS & PERMISSIONS: A collection (e.g. "Tutorials") is identified by its
- * dataCollectionId — the name set in the dashboard, NOT a GUID. Field keys are also set
- * in the dashboard. This skill runs as an ANONYMOUS VISITOR — a call only succeeds if the
- * collection grants that action to "Anyone" (Read for listing, Insert for forms, etc.).
- * Permission-denied throws HTTP 403 by design. Set permissions in Wix dashboard → CMS → Permissions.
- * https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-permissions/data-permissions-object.md
- *
- * Data Item — every read helper returns the item's `data` payload:
- *   _id {string} — GUID (route key, itemId for get/update/remove),
- *   _createdDate, _updatedDate — dates, wrapped (see RETRIEVAL SHAPES below),
- *   _owner {string} — id of the member who created the row,
- *   ...fields — collection field values keyed by field key
- * Full reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/data-item-object.md
- *
- * RETRIEVAL SHAPES — three field types arrive in a form the UI reads through a converter. Convert on
- * read; the rest (text, number, boolean, url) come back as plain values:
- *   date / datetime  → { "$date": "2026-05-05T00:00:00.000Z" }. Read it as
- *                      `new Date(v?.$date ?? v)` — handing the object itself to `new Date()` produces
- *                      an Invalid Date, which reaches the page as the text "Invalid Date". Applies to
- *                      your own date fields AND to _createdDate / _updatedDate. Send it back the same
- *                      way, `{ "$date": iso }`; a query FILTER accepts either that or a plain ISO string.
- *   image (media)    → `wix:image://v1/...`. Convert with `wixImage()` from `@/lib/wixImage`.
- *   MULTI_REFERENCE  → present once you pass `includeReferences` to queryDataItems; read `item.<field>`.
- *
- * FILTERS & SORT (Wix API Query Language):
- *   filter: { field: value } for equality; { field: { $op: value } } for operators:
- *     $eq $ne $gt $gte $lt $lte $in $nin $startsWith $exists $isEmpty $hasSome $hasAll
- *   Combine with $and / $or / $not. Dates: { "$date": "2026-05-05T00:00:00.000Z" }.
- *   sort: [{ fieldName: "publishDate", order: "DESC" }]
- * Full reference: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md
- */
-
-/**
- * Guard: reject `undefined` values inside a filter.
- *
- * `JSON.stringify` DELETES undefined values, so a missing or mistyped variable doesn't error —
- * it silently changes what the query matches, and the server can't flag it either because the
- * key never arrives:
- *   { _owner: undefined }          → {}               → matches EVERY item
- *   { _owner: { $eq: undefined } } → { "_owner": {} }  → matches NO item
- * The bad value is still visible here, before serialization, so fail loudly instead.
- *
- * The classic slip: every CMS data-item field is underscore-prefixed (`_id`, `_owner`,
- * `_createdDate`), but a Wix MEMBER (a different API) exposes `member.id` — so `member._id`
- * reads naturally, is `undefined`, and turns "my items" into "everyone's items".
- */
-function assertDefinedFilterValues(filter, path = "filter") {
-  if (!filter || typeof filter !== "object") return;
-  for (const [key, value] of Object.entries(filter)) {
-    const at = Array.isArray(filter) ? `${path}[${key}]` : `${path}.${key}`;
-    if (value === undefined) {
-      throw new Error(
-        `wix-cms: ${at} is undefined. JSON.stringify drops undefined, so this query would ` +
-          `silently match every item (or none) instead of filtering. Pass a real value, or omit ` +
-          `the key entirely — e.g. \`...(memberId ? { _owner: memberId } : {})\`. ` +
-          `Note: Wix members expose \`member.id\`, not \`member._id\`.`,
-      );
-    }
-    if (value && typeof value === "object" && !(value instanceof Date)) {
-      assertDefinedFilterValues(value, at);
-    }
-  }
-}
-
-/**
- * Query one page of items from a collection.
- * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-data-items.md
- *
- * Pass `nextCursor` back as `cursor` to load the next page. Define `filter`/`sort`/`fields`
- * on the FIRST request only — on cursor follow-ups Wix reuses the original query and
- * ignores them (so this helper omits them when a cursor is supplied).
- *
- * @param {string} dataCollectionId  Collection name (e.g. "Tutorials").
- * @param {{
- *   filter?: object,
- *   sort?: Array<{ fieldName: string, order?: "ASC"|"DESC" }>,
- *   limit?: number,
- *   cursor?: string,
- *   fields?: string[],
- *   includeReferences?: Array<{ field: string, limit?: number }>
- * }} [options]
- * @returns {Promise<{ items: object[], nextCursor: string|null }>}  items are `data` payloads (each includes `_id`).
- */
-export async function queryDataItems(dataCollectionId, { filter, sort, limit = 100, cursor, fields, includeReferences } = {}) {
-  assertDefinedFilterValues(filter);
-  const query = {
-    ...(cursor
-      ? {}
-      : {
-          ...(filter ? { filter } : {}),
-          ...(sort ? { sort } : {}),
-          ...(fields ? { fields } : {}),
-        }),
-    cursorPaging: cursor ? { limit, cursor } : { limit },
-  };
-  const res = await wixApiRequest("/wix-data/v2/items/query", {
-    method: "POST",
-    body: {
-      dataCollectionId,
-      query,
-      ...(includeReferences ? { includeReferences } : {}),
-    },
-  });
-  return {
-    items: (res?.dataItems ?? []).map((d) => d.data),
-    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
-  };
-}
-
-/**
- * Get a single item by its `_id`. Returns the `data` payload, or null if not found
- * (or not readable by an anonymous visitor — see the permissions note up top).
- * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/get-data-item.md
- *
- * @param {string} dataCollectionId
- * @param {string} itemId            The item's `_id`.
- * @returns {Promise<object|null>}
- */
-export async function getDataItem(dataCollectionId, itemId) {
-  try {
-    const res = await wixApiRequest(`/wix-data/v2/items/${encodeURIComponent(itemId)}`, {
-      method: "GET",
-      query: { dataCollectionId },
-    });
-    return res?.dataItem?.data ?? null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Get the first item whose `fieldKey` equals `value`. Use for slug-style routing —
- * Wix Data has no native get-by-slug, so detail pages keyed off a human-readable field
- * (e.g. a "slug" or "handle" field) resolve through this. Returns the `data` payload or null.
- * Built on Query Data Items: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-data-items.md
- *
- * @param {string} dataCollectionId
- * @param {string} fieldKey   Field to match (e.g. "slug").
- * @param {unknown} value     Value to match.
- * @returns {Promise<object|null>}
- */
-export async function getDataItemBy(dataCollectionId, fieldKey, value) {
-  const { items } = await queryDataItems(dataCollectionId, { filter: { [fieldKey]: value }, limit: 1 });
-  return items[0] ?? null;
-}
-
-/**
- * Count items in a collection matching an optional filter. Use for empty-state logic
- * (0 → prompt the user to add items in their Wix dashboard) and result counts.
- * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/count-data-items.md
- *
- * @param {string} dataCollectionId
- * @param {object} [filter]  Same filter syntax as queryDataItems.
- * @returns {Promise<number>}
- */
-export async function countDataItems(dataCollectionId, filter) {
-  assertDefinedFilterValues(filter);
-  const res = await wixApiRequest("/wix-data/v2/items/count", {
-    method: "POST",
-    body: { dataCollectionId, ...(filter ? { filter } : {}) },
-  });
-  return res?.totalCount ?? 0;
-}
-
-/**
- * Insert a new item (e.g. a public form submission). The collection's Insert permission
- * must be "Anyone" for this to succeed as a visitor. Returns the inserted `data` payload
- * (including the assigned `_id`). Throws on failure (e.g. permission denied, validation).
- * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/insert-data-item.md
- *
- * @param {string} dataCollectionId
- * @param {object} data   Field-keyed values, e.g. { name, email, message }. Omit `_id`
- *                        to let Wix assign one; supply `_id` only for a custom GUID.
- * @returns {Promise<object>}  The inserted item's `data` payload.
- */
-export async function insertDataItem(dataCollectionId, data) {
-  const res = await wixApiRequest("/wix-data/v2/items", {
-    method: "POST",
-    body: { dataCollectionId, dataItem: { data } },
-  });
-  const inserted = res?.dataItem?.data;
-  if (!inserted) throw new Error(`Insert into "${dataCollectionId}" failed (no item returned).`);
-  return inserted;
-}
-
-/**
- * Update (REPLACE) an existing item by `_id`. Returns the updated `data` payload. Throws
- * if the item doesn't exist or the visitor lacks Update permission (usually admin/author only).
- * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/update-data-item.md
- *
- * ⚠ This is a FULL REPLACE: the new `data` overwrites the whole item, and any field NOT
- * included is dropped. To change a few fields, fetch the item first (getDataItem), spread
- * it, then pass the merged object — or use Patch Data Item for a partial change:
- * https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/patch-data-item.md
- *
- * @param {string} dataCollectionId
- * @param {string} itemId   The item's `_id`.
- * @param {object} data     The complete new field set.
- * @returns {Promise<object>}  The updated item's `data` payload.
- */
-export async function updateDataItem(dataCollectionId, itemId, data) {
-  const res = await wixApiRequest(`/wix-data/v2/items/${encodeURIComponent(itemId)}`, {
-    method: "PUT",
-    body: { dataCollectionId, dataItem: { id: itemId, data: { ...data, _id: itemId } } },
-  });
-  const updated = res?.dataItem?.data;
-  if (!updated) throw new Error(`Update of "${itemId}" in "${dataCollectionId}" failed (no item returned).`);
-  return updated;
-}
-
-/**
- * Remove an item by `_id`. Irreversible. Returns the removed `data` payload. Throws if the
- * visitor lacks Delete permission (usually admin/author only).
- * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/remove-data-item.md
- *
- * @param {string} dataCollectionId
- * @param {string} itemId   The item's `_id`.
- * @returns {Promise<object|null>}  The removed item's `data` payload.
- */
-export async function removeDataItem(dataCollectionId, itemId) {
-  const res = await wixApiRequest(`/wix-data/v2/items/${encodeURIComponent(itemId)}`, {
-    method: "DELETE",
-    query: { dataCollectionId },
-  });
-  return res?.dataItem?.data ?? null;
-}

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

@@ -1,145 +0,0 @@
-# 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 documentation skill available in your environment (search + read the live reference); never guess.
-- Anything not covered → use the documentation skill available in your environment (search + read the live reference); never guess.