@wix/agent-skills 1.15.0 → 1.16.0

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

@@ -1,154 +1,176 @@
+# Wix CMS — client utils (you build the UI)
 
-# Wix CMS Skill
+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, forms) in your own framework and design tokens, calling the shipped
+**utils**. 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.
 
-> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and this vertical's `references/cms/wix-cms.js`. Copy **both** into your app's `src/rest/` side by side — the helper does `import { wixApiRequest } from "./wix-client.js"`, so they must land in the same folder.
+## What ships (utils only)
 
-Builds a real, client-only Wix CMS-backed app. The browser talks to Wix Data directly
-over a public `WIX_CLIENT_ID` to read and write items in the site's data collections.
-Never mock data; never hand-build API URLs — always go through the helpers, which call
-the official Wix Data endpoints.
-
-## When to use
-- User wants to display Wix CMS / Content Manager content (a collection of posts,
-  tutorials, recipes, team members, listings, FAQs, etc.) on a site.
-- Replacing placeholder/mock content with live Wix Data items.
-- Adding list pages, detail pages, category/tag filtering, or free-text search over an
-  existing Wix data collection.
-- Wiring a public form (contact, RSVP, review, signup) that writes a row into a collection.
+| 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)* | Set `WIX_CLIENT_ID` + `WIX_METASITE_ID` here (the one place both ids live). |
+| `WixManageBanner` *(shared)* | Dev-only manage banner — mount it in your Layout (see the platform doc's "Done" step). |
 
 ## Prerequisites
-1. A Wix site with **a data collection already created and populated** (this skill does
-   NOT provision collections — it reads/writes existing ones). The merchant creates
-   collections, fields, and items in the Wix dashboard (CMS / Content Manager).
-2. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (the
-   Wix Business Manager surfaces a copyable prompt with the id filled in — see
-   the router `SKILL.md`). Paste it into `src/rest/wix-client.js` in place of the placeholder. It is
-   a buyer-facing credential (it only mints anonymous visitor tokens), **not** a secret,
-   so hardcoding/committing it is fine.
-3. **Collection permissions** must match what you're doing. This skill runs as an
-   anonymous visitor, so a call only works if the collection grants that action to
-   "Anyone": Read for listing content, Insert for a public form. Update/Delete are
-   almost always admin- or author-only and will fail for a visitor. The site owner sets
-   these in the Wix dashboard (CMS → collection → Permissions). This is a **separate Wix
-   setup step the user completes** — out of this skill's scope. If a read/insert fails
-   with a permission error (HTTP 403) before that's set, that's expected; flag it and
-   continue.
-4. You need each collection's **collection ID** (its name, e.g. `Tutorials`) and its
-   **field keys** (e.g. `title`, `publishDate`). Read field keys off a fetched item, or
-   from the collection schema (see "Beyond the snippets").
-
-## The API (copy as-is; do not re-derive it)
-This skill ships only the REST layer — no UI components. Build the UI however the project
-wants; wire it to these two snippets. Copy them into the app (e.g. `src/api/`) and only
-adjust import paths:
-- `src/rest/wix-client.js` — visitor-token mint/refresh + transport. Set `WIX_CLIENT_ID`
-  to the id from the prompt (replace the `<YOUR-CLIENT-ID>` placeholder). The visitor
-  refresh token is persisted to localStorage; do not re-mint anonymously per load.
-- `src/rest/wix-cms.js` — exports:
-  - **Read:** `queryDataItems`, `getDataItem`, `getDataItemBy`, `countDataItems`
-  - **Write:** `insertDataItem`, `updateDataItem`, `removeDataItem`
-
-The Data Item shape, the per-collection **permissions model**, and the **filter/sort
-syntax** are documented as JSDoc comments at the top of `wix-cms.js`. Read them before
-building the UI — read helpers return the item's flat `data` payload (which always
-includes `_id`), and writes are bound by collection permissions.
-
-## How to wire it (UI is the project's choice)
-- **Content list** — `queryDataItems(collectionId, { filter?, sort?, limit?, cursor? })`
-  for the listing; render fields directly off each returned item (`item.title`, etc.).
-  Pass the returned `nextCursor` back as `cursor` to load the next page. Define
-  `filter`/`sort` on the first request only — cursor follow-ups reuse the original query.
-- **Detail page** — route by the item's `_id` and call `getDataItem(collectionId, itemId)`;
-  returns null on miss → show a not-found state, never invent an item. For human-readable
-  URLs, add a slug-like field to the collection and route via
-  `getDataItemBy(collectionId, "slug", slugFromUrl)`.
-- **Filter & search** — pass a `filter` to `queryDataItems` using the operators documented
-  in `wix-cms.js` (`$eq`, `$in`, `$gte`, `$startsWith`, `$hasSome`, `$and`/`$or`, …). For a
-  simple text search, `{ title: { $startsWith: term } }`; for richer free-text/fuzzy search
-  across fields, see "Beyond the snippets" (Search Data Items).
-- **Public form** — on submit, `insertDataItem(collectionId, { name, email, message })`
-  (field keys must match the collection). Requires the collection's Insert permission to be
-  "Anyone". Show success/failure from the resolved/thrown result; never fake a success.
-- **Edit / delete (admin/author flows)** — `updateDataItem(collectionId, itemId, data)`
-  (⚠ full replace — fetch + merge first to preserve other fields) and
-  `removeDataItem(collectionId, itemId)`. These need Update/Delete granted to the caller,
-  which visitors normally don't have — expect them to fail unless the collection is opened up.
-- **Empty state** — if `countDataItems(collectionId)` is 0, show an empty state telling
-  the user to add items in their Wix dashboard. Never invent items.
-
-## Hard rules (do not violate)
-- ✅ Read/write ONLY through the helpers in `wix-cms.js` (which call the official Wix Data
-  `/wix-data/v2/items` endpoints).
-- ❌ Never hand-build Wix Data URLs or invent endpoint paths.
-- ❌ Never mock data — render live Wix Data items or the empty state.
-- ❌ Never invent fields, reviews, ratings, or content not present in the collection.
-- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
-- ✅ Use the item's `_id` as the route key and as `itemId` for get/update/remove.
-- ✅ `updateDataItem` REPLACES the whole item — fetch with `getDataItem`, merge your
-  changes, then pass the full object, or use Patch Data Item (see below) for partial edits.
-- ✅ Treat permission errors (HTTP 403) as a configuration step, not a code bug: tell the
-  user which permission to grant in the dashboard. Writes throw on failure — don't swallow
-  the error and show a fake success.
-
-## Beyond the snippets
-The snippets cover the common CMS paths (list, detail, filter, count, insert, update,
-remove). If you hit a use case they don't cover, make the call yourself with
-`wixApiRequest` — but look up the exact endpoint, HTTP method, and request body in the
-**official Wix API reference** first; never guess:
-- CMS / Data Items API reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items.md
-- Data Items sample flows: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/sample-flows.md
-- **Partial update** (change some fields, keep the rest): Patch Data Item —
-  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/patch-data-item.md
-- **Upsert** (insert or update by id): Save Data Item —
-  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/save-data-item.md
-- **Bulk** insert/update/save/remove (many items in one call):
-  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items.md
-- **Free-text / fuzzy search** across fields: Search Data Items —
-  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/search-data-items.md
-- **Aggregations** (counts/averages grouped by a field): Aggregate Data Items —
-  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/aggregate-data-items.md
-- **Distinct values** (e.g. all categories for a filter menu): Query Distinct Values —
-  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-distinct-values.md
-- **Referenced items** (expand a reference field beyond the inline limit): Query Referenced
-  Data Items — https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-referenced-data-items.md
-- **Collection schema / field keys & types**: Get Data Collection —
-  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`). A collection whose permissions are `read: Anyone`,
-  `insert: Site Member`, `update/remove: Site Member Author` gives you the classic pattern: anyone
-  reads, only logged-in members write, and each member edits only their own. Sign the member in with
-  custom login (on your own UI), then `insertDataItem` runs as the member and Wix stamps the item's
-  `_owner` automatically — so a **"my items"** view is just
-  `queryDataItems(collectionId, { filter: { _owner: <memberId> } })`, and author-only
-  `updateDataItem`/`removeDataItem` are enforced server-side. (This skill never provisions the
-  collection — the owner creates it with those permissions in the dashboard.)
-  **Prefer Wix for member-generated content, and keep one feature's data and identity together.**
-  Content that belongs to the Wix site (likes, reviews, submissions) is best kept in a Wix collection
-  via these helpers, keyed on the Wix member's server-stamped `_owner`. What breaks is a *split*
-  feature — the row stored in one place while the member is identified from the Wix session elsewhere
-  (or filtered by some other `created_by`/user id): the two ids won't match, so ownership filters
-  miss. Keep them on one side; for Wix-backed rows that's `_owner`.
-
-Keep the snippets as the default for everything they already do; reach for the API
-reference only for the gap.
+- 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
+- Set `WIX_CLIENT_ID` (in `wix-config`) — not the placeholder.
+- 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 `wix-docs` skill) — 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
-In some cases, users need to access the Wix dashboard in order to edit the CMS content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For CMS data those pages are:
-- **Collections & items** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-cms` (`Dashboard → CMS`) → **Create Collection**, then open a collection to add items.
-- **Permissions** — no separate deep link; in the same CMS area, open the collection → **More Actions → Permissions & Privacy**. For the headless app to work anonymously, set **Show content** to *Everyone* (visitor reads) and, for a public form, **Collect content** to *Everyone* (visitor inserts). Update/Delete stay admin-only.
-
-Substitute the site's `metaSiteId` to complete the links (you have it from the handoff / `ListWixSites`). Include the in-dashboard navigation as a fallback.
-
-## Verification checklist (before declaring done)
-- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
-- [ ] Visitor token persists across reload (same anonymous visitor, no re-mint per load)
-- [ ] `queryDataItems` returns live items; pagination via `nextCursor` loads more
-- [ ] Detail page uses the item's `_id` (or a slug field via `getDataItemBy`) and shows a
-      not-found state on miss — no invented item
-- [ ] Filter/sort produce the expected subset (operators match the field types)
-- [ ] Public form `insertDataItem` succeeds only when Insert is "Anyone"; on a 403 the user
-      is told to grant the permission — no fake success
-- [ ] Update is treated as a full replace (fetch + merge), so no fields are silently dropped
-- [ ] Empty state shown when `countDataItems` is 0
-- [ ] No mock data anywhere; no hand-built Wix Data URLs
-- [ ] Told the user at least once that they can continue setting up their content in the dashboard and provided deep links.
+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

@@ -0,0 +1,31 @@
+// 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

@@ -0,0 +1,18 @@
+// 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/{wix-cms.js → app/rest/wix-cms.js}

@@ -12,10 +12,21 @@ import { wixApiRequest } from "./wix-client.js";
  *
  * Data Item — every read helper returns the item's `data` payload:
  *   _id {string} — GUID (route key, itemId for get/update/remove),
- *   _createdDate, _updatedDate {string} — ISO 8601 (use { "$date": "..." } in filters),
- *   _ownerId {string}, ...fields — collection field values keyed by field key
+ *   _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
@@ -24,6 +35,38 @@ import { wixApiRequest } from "./wix-client.js";
  * 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
@@ -44,6 +87,7 @@ import { wixApiRequest } from "./wix-client.js";
  * @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
       ? {}
@@ -115,6 +159,7 @@ export async function getDataItemBy(dataCollectionId, fieldKey, value) {
  * @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 } : {}) },