@wix/agent-skills 1.24.0 → 1.26.0

package/skills/wix-manage/references/cms/cms-data-items-crud.md

@@ -1,12 +1,12 @@
 ---
 name: "CMS Data Items CRUD"
-description: "Add, query, update, and delete items in CMS collections. Use this to insert content, bulk insert/update/patch/delete items, query with filters, and manage collection data. Key endpoints: /wix-data/v2/items, /wix-data/v2/bulk/items/*."
+description: "Add, query, update, and delete items in CMS collections, one at a time or in bulk. Also covers counting items, upserting with bulk save, truncating a collection, aggregating data with a pipeline, linking items through single- and multi-reference fields, and reading items with their referenced items expanded."
 ---
 # CMS Data Items CRUD
 
 > **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
 
-This recipe covers basic Create, Read, Update, Delete (CRUD) operations for Wix CMS data items.
+This recipe covers Create, Read, Update, Delete (CRUD) operations for Wix CMS data items, plus count, upsert, truncate, aggregate, and reference-field links.
 
 ## Prerequisites
 
@@ -231,6 +231,8 @@ Unlike Update, this only modifies the specified fields — all other fields rema
 
 **Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/update`
 
+> There is no update-by-filter endpoint. To update the items matching a filter, query them first (see [Query Data Items](#query-data-items)), then send their ids to bulk update or bulk patch.
+
 > **Important**: Use `id` (not `_id`) at the element level. The `data` object should NOT contain `_id`.
 
 ```json
@@ -297,7 +299,7 @@ Unlike bulk update, this only modifies the specified fields - other fields remai
 }
 ```
 
-**Setting a reference field** (single REFERENCE only):
+**Setting a single `REFERENCE` field** (the value is one item ID; for `MULTI_REFERENCE` the value shape differs, see the next example):
 ```json
 {
   "dataCollectionId": "events",
@@ -318,26 +320,39 @@ Unlike bulk update, this only modifies the specified fields - other fields remai
 }
 ```
 
+**Setting a `MULTI_REFERENCE` field** (verified live): the value is an **array of item IDs**, and `SET_FIELD` **replaces the whole link set**. To add links without dropping the existing ones, use [Insert Multi-Reference Links](#insert-multi-reference-links) instead. A plain string, or `APPEND_TO_ARRAY`, fails per item with `WDE0303` inside a 200 bulk response — check `results[].itemMetadata`.
+```json
+{
+  "dataCollectionId": "Projects",
+  "patches": [
+    {
+      "dataItemId": "project-item-id",
+      "fieldModifications": [
+        {
+          "fieldPath": "team",
+          "action": "SET_FIELD",
+          "setFieldOptions": {
+            "value": ["alice-item-id", "bob-item-id"]
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
 **Available actions**: `SET_FIELD`, `REMOVE_FIELD`, `INCREMENT_FIELD`, `APPEND_TO_ARRAY`, `REMOVE_FROM_ARRAY`
 
 > **Common error**: If you get `WDE0080: patches must not be empty`, you sent `dataItems` instead of `patches`. Use the format above.
 
 > **Recommended**: Use bulk patch instead of bulk update when you only need to change specific fields.
 
-> **Reference Fields**:
-> - **Single REFERENCE**: CAN be set during insert/update by providing the referenced item's ID as the field value (e.g., `"venue": "venue-item-id"`)
-> - **MULTI_REFERENCE**: **STOP** - You cannot use this recipe for multi-reference fields. They cannot be set via insert/update/patch.
->
-> **For MULTI_REFERENCE operations (add speakers, assign tags, link categories, etc.):**
-> **READ [CMS References & Relationships](cms-references-and-relationships.md)** for the exact endpoints and request bodies:
-> - `POST https://www.wixapis.com/wix-data/v2/bulk/items/insert-references` - add references
-> - `POST https://www.wixapis.com/wix-data/v2/items/replace-references` - replace all references
-> - `POST https://www.wixapis.com/wix-data/v2/bulk/items/remove-references` - remove references
->
-> Error `WDE0303` occurs when attempting to set multi-reference fields via data operations.
+> **Reference fields**: a single `REFERENCE` field is set like any other value (`"venue": "venue-item-id"`, as above). `MULTI_REFERENCE` links are written only by a `SET_FIELD` patch (single or bulk) or by the reference endpoints in [Reference Fields](#reference-fields) below; insert, bulk insert, bulk save, PUT and bulk update all return 200 but silently drop multi-reference values (verified live) — read the item back after any of them.
 
 ## Delete Data Item
 
+> Deletes are irreversible. Confirm with the user before calling either delete endpoint unless the request already names the items to remove.
+
 **Endpoint**: `DELETE https://www.wixapis.com/wix-data/v2/items/{itemId}?dataCollectionId={collectionId}`
 
 ```bash
@@ -357,6 +372,225 @@ curl -X DELETE \
 }
 ```
 
+## Count Data Items
+
+Count items in a collection, optionally with filters.
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/count`
+
+**Count All Items**:
+```json
+{
+  "dataCollectionId": "Products"
+}
+```
+
+**Response**:
+```json
+{
+  "totalCount": 42
+}
+```
+
+**Count with Filter**:
+```json
+{
+  "dataCollectionId": "Products",
+  "filter": {
+    "$and": [
+      { "inStock": true },
+      { "price": { "$gte": 50 } }
+    ]
+  }
+}
+```
+
+Count returns only `totalCount`. When the user needs to know *which* items match, run Query Data Items with the same filter instead of, or after, counting.
+
+## Bulk Save (Upsert)
+
+Insert new items or update existing items in a single operation. This is useful for syncing data.
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/save`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "dataItems": [
+    {
+      "id": "existing-item-id",
+      "data": {
+        "title": "Updated Product",
+        "price": 199.99,
+        "inStock": true
+      }
+    },
+    {
+      "data": {
+        "title": "New Product",
+        "price": 79.99,
+        "inStock": true
+      }
+    }
+  ],
+  "returnEntity": true
+}
+```
+
+| Scenario | Action |
+|----------|--------|
+| No `id` provided | INSERT - Creates new item with generated ID |
+| `id` provided, doesn't exist | INSERT - Creates new item with provided ID |
+| `id` provided, exists | UPDATE - Replaces existing item |
+
+> **Warning**: When updating, the entire item is replaced. Include all fields you want to keep. Confirm with the user before saving over existing items.
+
+## Truncate Collection
+
+Remove all items from a collection.
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/truncate`
+
+```json
+{
+  "dataCollectionId": "TestCollection"
+}
+```
+
+> **Warning**: This permanently deletes ALL items in the collection and cannot be undone. Ask the user to confirm before calling it.
+
+## Aggregate Data
+
+Perform calculations on collection data using a pipeline of sequential stages. The example shows one `group` stage; the full set of stages (`filter`, `group`, `sort`, `projection`, `unwindArray`, `skip`, `limit`) and accumulators is in the [Aggregate Pipeline Data Items reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/aggregate-pipeline-data-items).
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/aggregate-pipeline`
+
+**Count by Category**:
+```json
+{
+  "dataCollectionId": "Products",
+  "pipeline": {
+    "stages": [
+      {
+        "group": {
+          "groupIds": [
+            {"key": "category", "expression": {"fieldPath": "category"}}
+          ],
+          "accumulators": [
+            {
+              "resultFieldName": "count",
+              "sum": {"expression": {"numeric": 1}}
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+## Operation Comparison
+
+| Operation | Use Case | Behavior |
+|-----------|----------|----------|
+| **Bulk Insert** | Add new items only | Fails if ID exists |
+| **Bulk Update** | Update existing items | Fails if ID doesn't exist, replaces entire item |
+| **Bulk Save** | Upsert (insert or update) | Creates or updates based on ID |
+| **Bulk Patch** | Partial update | Only modifies specified fields |
+
+## Reference Fields
+
+Reference fields link items across collections. A single `REFERENCE` field holds one item ID and is set like any other value in insert, update, or patch. A `MULTI_REFERENCE` field holds many links, and only two kinds of write create them: a `SET_FIELD` patch on the field (single or bulk), or the reference endpoints below, which add, replace, or remove links without touching the rest of the item. To add a reference field to a collection, see [Add a Reference Field](cms-schema-management.md#add-a-reference-field).
+
+> **Warning (verified live)**: writing IDs into a `MULTI_REFERENCE` field through insert, bulk insert, bulk save, or PUT update returns **200 and silently drops that field's value** — no error is raised. Bulk update is a full-item replace like PUT and does the same: `success: true`, value dropped (verified live, bulk save on both its insert and update paths). Never trust the write response for reference links: read the item back with `includeReferencedItems` and confirm the linked items are there.
+
+Linking flow, every time:
+
+1. Resolve the referring item ID and the referenced item IDs (query by a field value; never guess IDs).
+2. Write the links with the reference endpoints below, or with a `SET_FIELD` patch on the reference field. If the field already has links, `insert-references` adds without dropping them; `replace-references` and `SET_FIELD` discard the rest — confirm with the user before replacing unless the request says to.
+3. **Read the referring item back** with Query Data Items and `includeReferencedItems: ["<field>"]` (or `includeReferences: [{ "field": "<field>" }]`), and confirm the linked items are present. The write's 200 is not proof; only the read-back is.
+
+### Insert Multi-Reference Links
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/insert-references`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "dataItemReferences": [
+    {
+      "referringItemId": "product-item-id",
+      "referringItemFieldName": "tags",
+      "referencedItemId": "tag-1-item-id"
+    },
+    {
+      "referringItemId": "product-item-id",
+      "referringItemFieldName": "tags",
+      "referencedItemId": "tag-2-item-id"
+    }
+  ],
+  "returnEntity": true
+}
+```
+
+### Replace All References
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/replace-references`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "referringItemId": "product-item-id",
+  "referringItemFieldName": "tags",
+  "newReferencedItemIds": ["new-tag-1-id", "new-tag-2-id", "new-tag-3-id"]
+}
+```
+
+> **Note**: To remove all references, pass an empty array for `newReferencedItemIds`.
+
+### Remove References (Bulk)
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/remove-references`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "dataItemReferences": [
+    {
+      "referringItemId": "product-id-1",
+      "referringItemFieldName": "tags",
+      "referencedItemId": "tag-to-remove-id"
+    }
+  ]
+}
+```
+
+### Query with Referenced Items Expanded
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/query`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "query": {
+    "filter": {
+      "inStock": true
+    }
+  },
+  "includeReferencedItems": ["category", "tags"]
+}
+```
+
+The method article documents the same expansion as `"includeReferences": [{ "field": "category" }, { "field": "tags", "limit": 50 }]`; both forms work (verified live). Either way the expanded value is an **array of item objects** (with `_id`, `name`, …), not an array of IDs. Without one of these properties a `MULTI_REFERENCE` field is absent from the returned item, and a single `REFERENCE` field is returned as the item ID string (it is stored on the item; verified live).
+
+### Reference Query Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$eq` | Exact match (single reference) | `{ "category": "id" }` |
+| `$hasSome` | Has at least one of | `{ "tags": { "$hasSome": ["id1", "id2"] } }` |
+| `$hasAll` | Has all of | `{ "tags": { "$hasAll": ["id1", "id2"] } }` |
+
 ## Field Types Reference
 
 | Type | Description | Example Value |
@@ -379,7 +613,7 @@ curl -X DELETE \
 | `ARRAY_STRING` | Array of strings | `["tag1", "tag2"]` |
 | `OBJECT` | JSON object | `{"key": "value"}` |
 | `REFERENCE` | Single reference | Item ID string |
-| `MULTI_REFERENCE` | Multiple references, use separate *reference* endpoints to manipulate, `include` to include in queries | Array of IDs |
+| `MULTI_REFERENCE` | Multiple references. Write with a `SET_FIELD` patch (array of item IDs, replaces the set) or the *reference* endpoints (add / replace / remove); expand in queries with `includeReferencedItems` or `includeReferences` | Write: array of item IDs (`SET_FIELD`). Read: absent unless expanded with `includeReferencedItems` / `includeReferences`, then an array of item objects |
 
 ---
 
@@ -465,7 +699,7 @@ confirmation before performing the install.
 | `PERMISSION_DENIED` | Insufficient access | Check API permissions |
 | `WDE0007` | Bulk update: wrong ID field name | Use `id` not `_id` at element level |
 | `WDE0080` | Validation failed (multiple causes) | Bulk update: don't include `_id` in `data`; Bulk patch: use `patches` array not `dataItems` |
-| `WDE0303` | Can't set multi-reference field via data operations | Use reference endpoints: `insert-references`, `replace-references` |
+| `WDE0303` | Multi-reference field value is not an array of item IDs (a single ID string, or `APPEND_TO_ARRAY`); reported per item inside a 200 bulk response | Send `"value": ["id1", "id2"]` with `SET_FIELD`, or use the reference endpoints |
 | `WDE0110` | Wix CMS (Wix Data) application is not installed | Install application with appDefId: `e593b0bd-b783-45b8-97c2-873d42aacaf4` |
 
 ---
@@ -474,6 +708,4 @@ confirmation before performing the install.
 
 - [Data Items API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction)
 - [CMS Schema Management](cms-schema-management.md) - Creating and modifying collections
-- [CMS References & Relationships](cms-references-and-relationships.md) - Linking collections
-- [CMS Data Operations Extended](cms-data-operations-extended.md) - Count, upsert, aggregate
 - [CMS Draft & Publish Workflow](cms-publishing-flow.md) - Collections gated behind a draft/publish (Draft Items plugin) workflow

package/skills/wix-manage/references/cms/cms-schema-management.md

@@ -1,6 +1,6 @@
 ---
 name: "CMS Schema Management"
-description: Create and modify CMS collection structures. Covers listing collections, creating collections with fields, adding/removing fields, and updating collection settings.
+description: Create and modify CMS collection structures. Covers listing collections, creating collections with fields, adding/removing fields (including single- and multi-reference fields that link two collections), and updating collection settings.
 ---
 # CMS Schema Management
 
@@ -86,6 +86,55 @@ curl -X GET \
 }
 ```
 
+### Add a Reference Field
+
+Same endpoint as above: `POST https://www.wixapis.com/wix-data/v2/collections/create-field`. The two bodies below differ only in `type` and `typeMetadata`; omitting `typeMetadata` fails with `WDE0075` (see Error Handling).
+
+| Type | Field Type | Relationship | Example |
+|------|------------|--------------|---------|
+| Single Reference | `REFERENCE` | One-to-one, Many-to-one | Product → Category |
+| Multi-Reference | `MULTI_REFERENCE` | One-to-many, Many-to-many | Product → Tags |
+
+**Single reference** — `typeMetadata.reference` names the referenced collection:
+
+```json
+{
+  "dataCollectionId": "Products",
+  "field": {
+    "key": "category",
+    "displayName": "Category",
+    "type": "REFERENCE",
+    "typeMetadata": {
+      "reference": {
+        "referencedCollectionId": "Categories"
+      }
+    }
+  }
+}
+```
+
+**Multi-reference** — `typeMetadata.multiReference` also names the field created on the other collection:
+
+```json
+{
+  "dataCollectionId": "Products",
+  "field": {
+    "key": "tags",
+    "displayName": "Tags",
+    "type": "MULTI_REFERENCE",
+    "typeMetadata": {
+      "multiReference": {
+        "referencedCollectionId": "Tags",
+        "referencingFieldKey": "products",
+        "referencingDisplayName": "Products"
+      }
+    }
+  }
+}
+```
+
+To link items through these fields, see [Reference Fields](cms-data-items-crud.md#reference-fields) in the CMS Data Items CRUD recipe.
+
 ## Delete a Field from Collection
 
 > **Warning**: This permanently deletes all data stored in this field across all items.
@@ -170,6 +219,8 @@ Don't delete and recreate a collection just to change its permissions — this f
 
 | Error | Cause | Solution |
 |-------|-------|----------|
+| `WDE0075` (`Metadata for Reference type field not provided`) | `create-field` with `type` REFERENCE or MULTI_REFERENCE but no `typeMetadata` | Send `typeMetadata.reference.referencedCollectionId` (or `typeMetadata.multiReference…`), see Add a Reference Field |
+| `WDE0075` (`Not recognized role provided in permissions`) | `PATCH /collections/{id}` with a `permissions` change | Use the full-replace `PUT /collections` (see Update Collection Settings) or the Data Permissions API |
 | `WDE0110` | Wix CMS (Wix Data) app is not installed on the site | Install it: `POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install` with body `{"tenant":{"tenantType":"SITE","id":"<SITE_ID>"},"appInstance":{"appDefId":"e593b0bd-b783-45b8-97c2-873d42aacaf4"}}`, then retry. See the [Install Wix Apps recipe](../app-installation/install-wix-apps.md). |
 
 ## Related Documentation

package/skills/wix-app/references/dashboard-page/DRAFT_TEMPLATE_COLLECTION.md

@@ -1,184 +0,0 @@
-# Draft Template — Collection page (Cases A, B and D)
-
-> Pick your case in [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md) first. This page is shared by A, B
-> and D.
-
-> **You write `fetchData`, the filters and the columns.** This holds whatever the rows are: for a
-> CMS collection `fetchData` calls `@wix/data` `items.query()`
-> ([WIX_DATA.md](../data-collection/WIX_DATA.md)) and nothing else on this page changes.
-
-## Two rules this skeleton encodes, so read them before editing it
-
-**Every row opens a page of its own, never a panel.** `onRowClick` navigates —
-`navigateToEntityPage` to an `EntityPage` route when the record is editable, or to a read-only
-detail route when the page is display-only ([DRAFT_TEMPLATE_ROUTER.md § 4](DRAFT_TEMPLATE_ROUTER.md#4-read-only-detail-route--case-a)).
-A WDS `SidePanel` is not the drill-in: in Cairo it is the host for a page's own side panels — the
-fields card's "Manage fields", a table's column panel — and `example-bm` uses it as a row drill-in
-in exactly nothing. Every collection example there navigates.
-
-**No `SummaryBar` unless the request asked for one.** Not "unless the page seems to want one" —
-unless the prompt named a total, a count, or a "how many / how much" figure. It is absent from this
-skeleton on purpose; adding one uninvited pushes the rows down the page and puts a number on screen
-nobody has to be right about. When you do add one, wire it from
-[SKILL.md § Step 2](../../SKILL.md) — no `SummaryBar` unless the request asked for one.
-
-## The collection page
-
-This is the file [Step 4c's UX Completeness Self-Audit](../../SKILL.md#step-4c-ux-completeness-self-audit)
-is about: a working filter, named filters, and a row that opens.
-
-```tsx
-// {Feature}CollectionPage.tsx — Case A, B, D
-import type { FC } from 'react';
-import {
-  CollectionEmptyState, CollectionErrorState, CollectionNoResultsState, CollectionSearch, CollectionToolbarFilters,
-  MultiSelectCheckboxFilter, Table, stringsArrayFilter,
-  useStaticListFilterCollection, useTableCollection,
-} from '@wix/patterns';
-import { CollectionPage } from '@wix/patterns/page';
-import { usePatternsNavigate } from '@wix/patterns/router';
-import { fetch{Feature}Page, type {Entity}Row } from './{feature}-api';
-
-const STATUS_LABELS: Record<string, string> = { ACTIVE: 'Active', ARCHIVED: 'Archived' };
-// Filter factories are module-level: one instance per page, not per render.
-const statusFilter = stringsArrayFilter<'ACTIVE' | 'ARCHIVED'>({
-  // `name` is NOT the visible title — it feeds a11y legends, BI grouping and dataHooks.
-  // The title comes from the label props in the JSX below; the package's own
-  // `Collection Toolkit.md` guide has the prop model.
-  name: 'Status',
-  itemKey: (item) => item,
-  itemName: (item) => STATUS_LABELS[item] ?? item,
-});
-
-export const {Feature}CollectionPage: FC = () => {
-  const { navigateToEntityPage } = usePatternsNavigate<{Entity}Row>();
-
-  const state = useTableCollection<{Entity}Row, { status: typeof statusFilter }>({
-    queryName: '{feature}',
-    paginationMode: 'cursor', // 'offset' if your API pages by offset
-    itemKey: (item) => item.id,
-    itemName: (item) => item.name,
-    filters: { status: statusFilter },
-    // Every declared filter AND the search box are read here — one that never
-    // reaches the query renders fine and narrows nothing.
-    fetchData: async (query) =>
-      fetch{Feature}Page({
-        limit: query.limit,
-        cursor: query.cursor ?? undefined, // return `cursor: next || undefined` — key always
-        //                                    present, '' walks pages forever
-        search: query.search,
-        filters: { status: query.filters.status },
-      }),
-    // fetchTotal is for a requested aggregate, so it is commented out here. Uncommented, it
-    // must RESOLVE A NUMBER from an endpoint that counts, and it OVERRIDES the fallback to the
-    // loaded-rows count — so a wrong one reports 0 beside a full table while tsc stays green.
-    // Read QUERY_AND_PAGING.md, "What fetchTotal is allowed to call", before uncommenting.
-    // fetchTotal: async (query) => count{Feature}({ search: query.search, filters: query.filters }),
-    fetchErrorMessage: ({ err }) => (err instanceof Error ? err.message : 'Failed to load {feature}'),
-  });
-
-  const statusOptions = useStaticListFilterCollection(statusFilter, ['ACTIVE', 'ARCHIVED']);
-
-  // Nothing here reads `state` directly: the Table observes it internally. The moment you
-  // DO derive a number from it in this component — a header figure, a badge, a requested
-  // SummaryBar — it is MobX, and a plain read is computed once while the collection is still
-  // empty and never recomputed. Wrap it in `useSelector` and select a primitive: TABLE_STATE.md.
-
-  return (
-    <CollectionPage>
-      <CollectionPage.Header title={{ text: '{Page Title}' }} />
-      <CollectionPage.Content>
-        <Table
-          state={state}
-          // `search` defaults to ON, so omitting it ships a box that reaches no
-          // query. Wire it AND read query.search above. If the API has no
-          // free-text filter, resolve the term to one it does support.
-          search={<CollectionSearch placeholder="Search {feature}" />}
-          filters={
-            <CollectionToolbarFilters>
-              {/* BOTH label props, same string, and never accordionItemProps.title.
-                  The resolution model is the package's own `Collection Toolkit.md` guide. */}
-              <MultiSelectCheckboxFilter
-                filter={statusFilter} collection={statusOptions}
-                toolbarItemProps={{ label: 'Status' }}
-                accordionItemProps={{ label: 'Status' }}
-              />
-            </CollectionToolbarFilters>
-          }
-          // Three distinct messages. Without errorState a failed query looks
-          // exactly like a slow one: skeletons, forever.
-          emptyState={<CollectionEmptyState title="No {feature} yet" />}
-          // Name what excluded the rows — a seeded default or a missing scope
-          // looks exactly like "nothing matched", and only one is actionable.
-          noResultsState={<CollectionNoResultsState title="No {feature} match" subtitle="…" />}
-          // errorState is a RENDER FUNCTION: (err, { retry }) => ReactElement.
-          errorState={(err, { retry }) => (
-            <CollectionErrorState
-              title="Couldn't load {feature}"
-              subtitle={String(err)}
-              action={{ text: 'Retry', onClick: retry }}
-            />
-          )}
-          // The drill-in. Editable record → the EntityPage route (`/${item.id}`).
-          // Display-only → the read-only route, DRAFT_TEMPLATE_ROUTER.md §4. Either way a
-          // route, and passing `entity` lets the target title itself before its fetch lands.
-          onRowClick={(item) => navigateToEntityPage({ path: `/${item.id}`, entity: item })}
-          columns={[
-            // One column per field the prompt names; verify each source field —
-            // DATA_SOURCES.md, "A column must show what its header promises."
-            { id: 'name', title: 'Name', render: (item) => item.name },
-          ]}
-        />
-      </CollectionPage.Content>
-    </CollectionPage>
-  );
-};
-```
-
-## Turning `query.search` into a query
-
-`{feature}-api.ts` turns one term into a filter over *several* fields — an OR. **This is where
-search ships broken**: it renders, it reaches the query, and still returns every row, so nothing
-looks wrong until someone counts results.
-
-### A CMS collection — `@wix/data`
-
-`or()` combines two filters; it is **not** a condition. Called on a query or filter holding no
-condition yet it contributes an empty `{}` branch, and `{} OR x` matches the whole collection. Seed
-the filter with the first field, `or()` the rest onto it, then `and()` it onto the query — which is
-also what keeps the facet filters applying to *every* branch:
-
-```ts
-// SHORT_TEXT / LONG_TEXT fields only: `contains` on a number, date or
-// reference field is not a narrower match, it is no match.
-const searchFilter = (term: string, fields: string[]) =>
-  fields.map((f) => items.filter().contains(f, term)).reduce((acc, f) => acc.or(f));
-
-let query = items.query(COLLECTION_ID).eq('status', status).limit(limit);
-const term = search?.trim();
-if (term) query = query.and(searchFilter(term, ['companyName', 'contactEmail']));
-
-// ❌ or() onto a query holding no condition — empty $or branch, every row matches
-items.query(ID).or(items.filter().contains('a', t)).or(items.filter().contains('b', t));
-// ❌ or() onto the query itself — `status` survives only on the first branch
-items.query(ID).eq('status', s).contains('a', t).or(items.filter().contains('b', t));
-```
-
-### A vertical SDK — `@wix/bookings`, `@wix/ecom`, …
-
-No shared free-text operator; the shape differs per endpoint. Read its *Supported Filters* page
-([QUERY_AND_PAGING.md](QUERY_AND_PAGING.md#the-filterable-fields-are-a-closed-list-published-per-endpoint)),
-then `$or` one clause per identity field it lists. Never route the term to a single field by its
-shape — a measured run shipped this, and one branch is always dead:
-
-```ts
-query = term.includes('@')
-  ? query.startsWith('loginEmail', term)
-  : query.startsWith('contact.firstName', term);  // a surname matches nothing, ever
-```
-
-`startsWith` is prefix-only too — "Smith" never finds "John Smith" — so prefer the containment
-operator when the endpoint declares one, and say which you used in `noResultsState`.
-
-**Whatever the shape, prove it narrows.** Run one term you expect to hit a known row and one you
-expect to hit nothing, and check the row count changes for both.