@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/cms/rest/items.ts

@@ -0,0 +1,189 @@
+// Wix Data reads/writes over REST — the twin of app/wix/cms/items.ts. Same exports, same DTOs; the
+// rules and mappers come from items-core (the SAME file the SDK transport uses, deployed flat next
+// to this one by deploy.mjs --stack static), so this file is only the transport: one fetch with a
+// literal body per function. The reads are safe from a browser with a visitor token on any
+// collection whose read permission is ANYONE; the writes succeed only where the collection's
+// insert/update/remove permission covers the caller (403 WDE0027 otherwise — a permissions step,
+// not a code bug). Porting: keep the paths, keep the bodies, port the core once.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-data-items.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/get-data-item.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/patch-data-item.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-insert-data-item-references.md
+import { WixApiError, wixRequest } from "./client.js";
+import { imgRatio, imgSrc } from "./media.js";
+import {
+  DEFAULT_LIMIT,
+  DISTINCT_LIMIT,
+  countBody,
+  distinctBody,
+  patchModifications,
+  queryBody,
+  referencesBody,
+  restHasNext,
+  restWriteData,
+  toItem,
+  toPage,
+  toValues,
+  type Media,
+  type Raw,
+} from "./items-core.js";
+import type { CmsFilter, CmsItem, CmsPage, CmsQuery } from "./types.js";
+
+const media: Media = { imgSrc, imgRatio };
+const notFound = (e: unknown): boolean => e instanceof WixApiError && e.status === 404;
+
+/**
+ * Query one page of a collection. An empty result on a PUBLIC collection is a seed permissions bug
+ * (read must be "ANYONE"), not a query bug.
+ * POST /wix-data/v2/items/query  { dataCollectionId, query: { filter, sort, paging: { limit, offset } }, includeReferences: [{ field }], returnTotalCount }
+ * → { dataItems: [{ id, dataCollectionId, data: { _id, …fields } }], pagingMetadata: { count, offset, total?, hasNext } }
+ */
+export async function queryItems(collectionId: string, query: CmsQuery = {}): Promise<CmsPage> {
+  const { limit = DEFAULT_LIMIT, skip = 0 } = query;
+  const res = await wixRequest<Raw>("/wix-data/v2/items/query", { body: queryBody(collectionId, query) });
+  const items = ((res?.dataItems ?? []) as Raw[]).map((d) => d.data ?? {});
+  return toPage(items, restHasNext(res?.pagingMetadata, skip, limit), res?.pagingMetadata?.total, media);
+}
+
+/**
+ * Fetch one item by `_id`. Null when not found (404 WDE0073). `includeReferences.field` is the
+ * request's key per the installed typings — confirm once on a live site that get honours it; if the
+ * referenced fields come back as ids, route through getItemBy("_id", …).
+ * GET /wix-data/v2/items/{id}?dataCollectionId=…&includeReferences.field=…  → { dataItem: { data } }
+ */
+export async function getItemById(
+  collectionId: string,
+  itemId: string,
+  { include = [] }: { include?: string[] } = {},
+): Promise<CmsItem | null> {
+  try {
+    const res = await wixRequest<Raw>(`/wix-data/v2/items/${encodeURIComponent(itemId)}`, {
+      method: "GET",
+      query: { dataCollectionId: collectionId, ...(include.length ? { "includeReferences.field": include } : {}) },
+    });
+    return res?.dataItem?.data ? toItem(res.dataItem.data, media) : null;
+  } catch (e) {
+    if (notFound(e)) return null;
+    throw e;
+  }
+}
+
+/**
+ * Fetch the first item whose `field` equals `value` — slug-style routing (Wix Data has no native
+ * get-by-slug). Null when not found → render a not-found state, never invent an item.
+ */
+export async function getItemBy(
+  collectionId: string,
+  field: string,
+  value: string | number,
+  { include = [] }: { include?: string[] } = {},
+): Promise<CmsItem | null> {
+  const page = await queryItems(collectionId, { filters: [{ field, op: "eq", value }], limit: 1, include });
+  return page.items[0] ?? null;
+}
+
+/**
+ * Count items matching the filters — no items transferred.
+ * POST /wix-data/v2/items/count  { dataCollectionId, filter }  → { totalCount }
+ */
+export async function countItems(collectionId: string, filters: CmsFilter[] = []): Promise<number> {
+  const res = await wixRequest<Raw>("/wix-data/v2/items/count", { body: countBody(collectionId, filters) });
+  return typeof res?.totalCount === "number" ? res.totalCount : 0;
+}
+
+/**
+ * The distinct values a field holds across the collection (optionally within `filters`) — filter
+ * chips and selects from live data. Values normalized like item values; a reference field yields ids.
+ * POST /wix-data/v2/items/query-distinct-values  { dataCollectionId, fieldName, filter, paging: { limit, offset } }  → { distinctValues: [...] }
+ */
+export async function distinctValues(
+  collectionId: string,
+  field: string,
+  { filters = [], limit = DISTINCT_LIMIT }: { filters?: CmsFilter[]; limit?: number } = {},
+): Promise<unknown[]> {
+  const res = await wixRequest<Raw>("/wix-data/v2/items/query-distinct-values", { body: distinctBody(collectionId, field, filters, limit) });
+  return toValues((res?.distinctValues ?? []) as unknown[], media);
+}
+
+/**
+ * Insert an item (visitor form / member submission). Never set `_owner` — Wix stamps it from the
+ * caller's identity. Date fields must be Date objects (the core spells them `{ $date }` on the wire;
+ * an ISO string is stored as text and breaks date queries). A MULTI_REFERENCE value inside `data` is
+ * DROPPED by the endpoint (200, no error) — pass those as `link: { field: [referencedIds] }` and they
+ * are linked right after the insert. The returned item predates the links.
+ * POST /wix-data/v2/items  { dataCollectionId, dataItem: { data } }  → { dataItem: { data } }
+ */
+export async function insertItem(
+  collectionId: string,
+  data: Record<string, unknown>,
+  { link = {} }: { link?: Record<string, string[]> } = {},
+): Promise<CmsItem> {
+  const res = await wixRequest<Raw>("/wix-data/v2/items", { body: { dataCollectionId: collectionId, dataItem: { data: restWriteData(data) } } });
+  const item = toItem(res?.dataItem?.data ?? {}, media);
+  for (const [field, refIds] of Object.entries(link)) await linkItems(collectionId, field, item._id, refIds);
+  return item;
+}
+
+/**
+ * REPLACE an item — fields omitted from `item` are WIPED (update does not patch). Spread the full
+ * item you hold and override; for an id + a few changed fields use patchItemFields. Wrap each date
+ * field back into a Date (`new Date(iso)`) before updating.
+ * PUT /wix-data/v2/items/{id}  { dataCollectionId, dataItem: { id, data } }  → { dataItem: { data } }
+ */
+export async function updateItem(collectionId: string, item: CmsItem): Promise<CmsItem> {
+  const res = await wixRequest<Raw>(`/wix-data/v2/items/${encodeURIComponent(item._id)}`, {
+    method: "PUT",
+    body: { dataCollectionId: collectionId, dataItem: { id: item._id, data: restWriteData(item) } },
+  });
+  return toItem(res?.dataItem?.data ?? {}, media);
+}
+
+/**
+ * Patch only the named fields — the safe partial change.
+ * PATCH /wix-data/v2/items/{id}  { dataCollectionId, patch: { dataItemId, fieldModifications: [{ fieldPath, action: "SET_FIELD", setFieldOptions: { value } }] } }
+ */
+export async function patchItemFields(
+  collectionId: string,
+  itemId: string,
+  fields: Record<string, unknown>,
+): Promise<CmsItem> {
+  const res = await wixRequest<Raw>(`/wix-data/v2/items/${encodeURIComponent(itemId)}`, {
+    method: "PATCH",
+    body: { dataCollectionId: collectionId, patch: { dataItemId: itemId, fieldModifications: patchModifications(fields) } },
+  });
+  return toItem(res?.dataItem?.data ?? {}, media);
+}
+
+/**
+ * Remove an item by `_id`. Irreversible. Returns the removed item (null if it didn't exist).
+ * DELETE /wix-data/v2/items/{id}?dataCollectionId=…  → { dataItem: { data } }
+ */
+export async function removeItem(collectionId: string, itemId: string): Promise<CmsItem | null> {
+  try {
+    const res = await wixRequest<Raw>(`/wix-data/v2/items/${encodeURIComponent(itemId)}`, { method: "DELETE", query: { dataCollectionId: collectionId } });
+    return res?.dataItem?.data ? toItem(res.dataItem.data, media) : null;
+  } catch (e) {
+    if (notFound(e)) return null;
+    throw e;
+  }
+}
+
+/**
+ * Add references to a MULTI_REFERENCE field of `itemId` — the only way a multi-reference is set
+ * (insert/update drop the value silently). Existing references stay; needs the collection's update
+ * permission. A no-op for an empty list.
+ * POST /wix-data/v2/bulk/items/insert-references  { dataCollectionId, dataItemReferences: [{ referringItemFieldName, referringItemId, referencedItemId }] }
+ */
+export async function linkItems(collectionId: string, field: string, itemId: string, refIds: string[]): Promise<void> {
+  if (!refIds.length) return;
+  await wixRequest<Raw>("/wix-data/v2/bulk/items/insert-references", { body: referencesBody(collectionId, field, itemId, refIds) });
+}
+
+/**
+ * Remove references from a MULTI_REFERENCE field of `itemId`. Other references stay. A no-op for an empty list.
+ * POST /wix-data/v2/bulk/items/remove-references  { dataCollectionId, dataItemReferences: [...] }  (same body as the insert)
+ */
+export async function unlinkItems(collectionId: string, field: string, itemId: string, refIds: string[]): Promise<void> {
+  if (!refIds.length) return;
+  await wixRequest<Raw>("/wix-data/v2/bulk/items/remove-references", { body: referencesBody(collectionId, field, itemId, refIds) });
+}

package/skills/wix-headless-templates/cms/seed/SEED.md

@@ -0,0 +1,116 @@
+# 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>/templates/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`, `TIME` (a `"hh:mm:ss.SSS"`
+  string, stored as text), `URL`, `EMAIL`, `IMAGE`, `RICH_TEXT` (an HTML string, stored verbatim),
+  `ARRAY_STRING` (tags: an array of strings), `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 both as `{ "$date": iso }` (the
+  form the app's reads and date filters are proven against; a `"YYYY-MM-DD"` string would be
+  stored as text). A `TIME` value stays a string.
+- 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`; at runtime the app does the same through
+  `linkItems` / `unlinkItems` in `wix/cms/items.ts`).
+- `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.
+
+## Supplied content
+
+The general rules are in `templates/shared/SUPPLIED-CONTENT.md`. For the CMS the user's data
+defines the schema: each distinct table, sheet or file becomes a collection, its columns become
+`fields` with a type read from the values (`TEXT`, `NUMBER`, `DATE`, `IMAGE` for image URLs,
+`RICH_TEXT` for HTML), and its rows become `items`. Keep the user's column names as field keys. A
+column whose values point at rows of another table becomes a `MULTI_REFERENCE`. When a column's
+type is ambiguous, ask.
+
+## 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; every call the script
+makes carries a `docs:` line with its reference page.
+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-templates/cms/seed/read-site.mjs

@@ -0,0 +1,20 @@
+// What the CMS holds: collections, their fields, item counts, a few sample items each.
+//   node <SKILL_ROOT>/templates/cms/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/cms";
+
+await runReader({
+  vertical: "cms",
+  async read(api, { limit }) {
+    const r = await api.call({ method: "GET", path: "/wix-data/v2/collections", docs: `${D}/collection-management/data-collections/list-data-collections` });
+    const all = r.collections ?? r.dataCollections ?? [];
+    const own = all.filter((c) => c.collectionType !== "WIX_APP");
+    const collections = [];
+    for (const c of own.slice(0, limit)) {
+      const items = await api.tryCall({ path: "/wix-data/v2/items/query", body: { dataCollectionId: c.id, query: { paging: { limit: 3 } }, returnTotalCount: true }, docs: `${D}/data-items/query-data-items` });
+      collections.push({ id: c.id, displayName: c.displayName, fields: (c.fields ?? []).map((f) => `${f.key}:${f.type}`), itemCount: items?.pagingMetadata?.total ?? null, sample: (items?.dataItems ?? []).map((i) => i.data?.title ?? i.data?.name ?? i.id) });
+    }
+    return { collectionCount: own.length, collections, appCollections: all.filter((c) => c.collectionType === "WIX_APP").map((c) => c.id) };
+  },
+});

package/skills/wix-headless-templates/cms/seed/seed-cms.mjs

@@ -0,0 +1,321 @@
+// 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; every call below
+// carries a docs: line with its reference page.
+import { readFileSync } from "node:fs";
+import { resolveItemImages } from "../../shared/seed/images.mjs";
+import { seedSiteId } from "../../shared/seed/site-context.mjs";
+import { wixToken } from "../../shared/seed/wix-cli.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() } = {}) {
+  // The content site: the config's site, or the parent on a migration preview (site-context.mjs stops
+  // a seed there unless --allow-parent is passed after the user confirmed).
+  const siteId = seedSiteId({ cwd, argv: process.argv });
+  const token = wixToken(siteId, cwd);
+  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);
+    });
+}