@wix/agent-skills 1.21.0 → 1.22.0

package/skills/wix-headless-fast/references/cms/rest/items.ts

@@ -1,125 +0,0 @@
-// 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
-import { WixApiError, wixRequest } from "./client.js";
-import { imgSrc } from "./media.js";
-import { DEFAULT_LIMIT, patchModifications, queryBody, restHasNext, restWriteData, toItem, toPage, type Raw } from "./items-core.js";
-import type { CmsFilter, CmsItem, CmsPage, CmsQuery } from "./types.js";
-
-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, imgSrc);
-}
-
-/**
- * Fetch one item by `_id`. Null when not found (404 WDE0073).
- * 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, imgSrc) : 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 — empty-state logic and result counts (returnTotalCount). */
-export async function countItems(collectionId: string, filters: CmsFilter[] = []): Promise<number> {
-  const page = await queryItems(collectionId, { filters, limit: 1, withTotal: true });
-  return page.total ?? page.items.length;
-}
-
-/**
- * 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).
- * POST /wix-data/v2/items  { dataCollectionId, dataItem: { data } }  → { dataItem: { data } }
- */
-export async function insertItem(collectionId: string, data: Record<string, unknown>): Promise<CmsItem> {
-  const res = await wixRequest<Raw>("/wix-data/v2/items", { body: { dataCollectionId: collectionId, dataItem: { data: restWriteData(data) } } });
-  return toItem(res?.dataItem?.data ?? {}, imgSrc);
-}
-
-/**
- * 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 ?? {}, imgSrc);
-}
-
-/**
- * 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 ?? {}, imgSrc);
-}
-
-/**
- * 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, imgSrc) : null;
-  } catch (e) {
-    if (notFound(e)) return null;
-    throw e;
-  }
-}

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

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

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

@@ -1,20 +0,0 @@
-// What the CMS holds: collections, their fields, item counts, a few sample items each.
-//   node <SKILL_ROOT>/references/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-fast/references/cms/seed/seed-cms.mjs

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