@wix/agent-skills 1.21.0 → 1.23.0

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

@@ -0,0 +1,182 @@
+# Finding the real SDK shape behind a dashboard page
+
+> **Scope.** [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md) gives you the page. This file is the other half:
+> locating the method and the *field names* for the data it lists. Read it before Step 3's MCP
+> discovery — the installed package answers most of it faster and more accurately than a doc search,
+> because it is the version your code will compile against.
+
+## Where the types actually live
+
+A Wix vertical package such as `@wix/ecom` is a thin re-export barrel. `build/es/index.d.mts` is a
+list of namespaces (`orders`, `orderTransactions`, `currentCart`, …), each re-exported from its own
+generated package:
+
+```
+node_modules/@wix/ecom/build/es/index.d.mts          # namespace list only, ~90 lines
+node_modules/@wix/auto_sdk_ecom_orders/build/es/
+  index.d.mts                                        # the callable functions
+  index.typings.d.mts                                # request/response types
+  ecom-v1-order-orders.universal-<hash>.d.mts        # the domain entities
+```
+
+Three consequences worth knowing before you start grepping:
+
+1. **The directory name is not the namespace name.** Namespaces are camelCase, package directories
+   are kebab-case — `extendedBookings` lives in `auto_sdk_bookings_extended-bookings`, not
+   `auto_sdk_bookings_extendedBookings`. Don't derive one from the other; list them:
+   `ls node_modules/@wix | grep <vertical>`.
+2. **The entity is not always in `index.typings.d.mts`.** `Order`, `Refund`, `Service` live in the
+   hashed `*.universal-*.d.mts` when the package has one. The hash changes between versions, so glob
+   for it, never hard-code it, and fall back to `index.typings.d.mts` when no universal file exists.
+3. **Never `cat` *or plain-`grep`* the barrel's export block.** These files end with a single
+   several-hundred-KB `export { … as a, … as b }` line, so `grep -n "queryServices" index.d.mts`
+   prints that whole line. Anchor to the declarations instead —
+   `grep -oE "^declare (const|function) [a-zA-Z]+"` — or pipe any barrel grep through `cut -c1-200`.
+
+## Confirming a method
+
+```bash
+E=node_modules/@wix/auto_sdk_ecom_order-transactions/build/es
+grep -oE "^declare function [a-zA-Z]+" $E/index.d.mts
+```
+
+Prefer this to recall: `listTransactionsForMultipleOrders(orderIds: string[])` and
+`listTransactionsForSingleOrder` differ by exactly the shape a collection page needs, and only one
+of them avoids an N+1 across the visible page.
+
+## Confirming a field — the part that ships bugs
+
+Once you have the entity, read the declaration for **every field you map into a column**, not just
+the uncertain ones. Two failure modes recur:
+
+**Deprecated fields still compile.** On `RegularPaymentDetails`, `paymentMethod` carries
+`@deprecated Use paymentMethodName.buyerLanguageName instead` — the deprecated one is a bare code,
+the replacement is the localised name a person expects to read. Grep before you map:
+
+```bash
+grep -B4 "paymentMethod?:" $E/index.typings.d.mts   # shows the @deprecated banner above it
+```
+
+A column bound to a deprecated field renders something plausible and wrong, which is the hardest
+kind of defect to catch in review.
+
+**Aggregates hide one level down.** Money on a refund is not on the refund — it is
+`refund.summary.refunded.amount` (`AggregatedRefundSummary`, with `pendingRefund`, `failedRefundAmount`
+and `requestedRefund` beside it), while per-transaction status is
+`refund.transactions[].refundStatus`. Summing the wrong one silently under-reports.
+
+**A generic-sounding field is not the related entity.** Treat `.title`, `.name` and `.summary` as
+unverified until you read the declaration: an `Extended*` / `*WithDetails` shape exists precisely to
+attach the real related entity, and a summary field on the base item is not a substitute. A column
+must show what its header promises.
+
+**A mapper must cover every shape the response returns.** Responses often carry a oneof — Bookings'
+`bookedEntity` is `slot` for an appointment, `schedule` for a class — and a mapper reading one
+variant renders blank cells for the other while passing `tsc`.
+
+## Joining two sources for one row
+
+A collection page usually needs one query plus one batch lookup, never a lookup per row:
+
+```ts
+const { orders: found } = await orders.searchOrders({ filter, sort, cursorPaging: { limit, cursor } });
+const ids = found.map((o) => o._id).filter((id): id is string => Boolean(id));
+const { orderTransactions: txns } = await orderTransactions.listTransactionsForMultipleOrders(ids);
+const byId = new Map(txns.map((t) => [t.orderId, t]));
+```
+
+Build the `Map` once and index it in the row mapper. Guard the empty case before the second call —
+a batch endpoint given `[]` is a wasted round trip at best.
+
+## Filter syntax
+
+`searchOrders` takes a `CursorSearch`: `{ cursorPaging, filter, sort }`, where `filter` is a
+Mongo-shaped `Record<string, any>` — `{ paymentStatus: { $in: [...] } }`,
+`{ _createdDate: { $gte, $lte } }`, `{ number: { $startsWith } }`. Enum values come from the
+declaration, not from memory: order payment status is `FULLY_REFUNDED` / `PARTIALLY_REFUNDED` /
+`PAID` / `NOT_PAID` / `PENDING` / `PARTIALLY_PAID` / `PENDING_MERCHANT` / `CANCELED` / `DECLINED` /
+`UNSPECIFIED`.
+
+## The SDK is not the REST API
+
+Docs search returns REST pages, and a dashboard page calls the **SDK**. Append `?apiView=SDK` to the
+URL of whatever page you landed on and read that view — it answers two of the four differences
+before you write a line.
+
+**1 and 2 — namespace and id naming. The SDK view states both.** It prints the package and namespace
+outright (`SDK Package: @wix/members`, `SDK Namespace: customFields`), and uses `_id` in its own
+parameter list. Infer either from the REST page and you get them wrong: REST paths say `services/v2`,
+so `servicesV2` looks right, and the SDK exports `services`; REST responses show `"id"`, and the SDK
+type declares `_id` — same for `_createdDate` / `_updatedDate`. Offline, the barrel is the fallback
+for the namespace list:
+
+```bash
+grep -oE "as [a-zA-Z_]+" node_modules/@wix/<pkg>/build/es/index.d.mts | sed 's/as //' | sort -u
+```
+
+The next two are codegen artifacts that no docs page mentions — read them off the declaration.
+
+**3. Don't derive types from `ReturnType`.** Most SDK functions are overloaded — a direct call
+and an `httpClient` form — so `Awaited<ReturnType<typeof ns.method>>['items'][number]` resolves
+against the wrong overload and fails. Import the entity type the package exports instead:
+
+```ts
+type Row = <namespace>.<Entity>;   // e.g. extendedBookings.ExtendedBooking — not ReturnType<typeof …>
+```
+
+**4. Paging metadata carries no `hasNext`.** `PagingMetadataV2` is `count`, `offset`, `total`,
+`tooManyToCount`, `cursors` — nothing else, in every generated package. Whether another page exists
+is knowable only from `pagingMetadata.cursors.next`. What the collection wants you to *return* is a
+separate question — see [TABLE_STATE.md](TABLE_STATE.md#query-and-result-shapes).
+
+## Two things to settle before you write the page
+
+**Is the package even installed?** A vertical's SDK is not a default dependency. `@wix/bookings`,
+`@wix/ecom` and the rest have to be present before the import resolves:
+
+```bash
+node -e "const p=require('./package.json');console.log(!!({...p.dependencies,...p.devDependencies})['@wix/<pkg>'])"
+npm install @wix/<pkg>     # if false
+```
+
+**Does the app hold the scope?** This is the one that produces a page which builds, mounts, renders
+its shell, and shows nothing — the hardest failure to read, because an empty table looks like empty
+data. Reads of a vertical's data need that vertical's permission scope, granted in **Dev Center →
+Permissions**; it cannot be declared in the repo, and the app's install consent screen names what it
+actually has.
+
+**Don't guess the scope name — the method's own docs page prints it.** In SDK view every method
+carries `Method Permissions` and `Method Permissions Scopes IDs`, for example
+`Manage Members: SCOPE.DC-MEMBERS.MANAGE-MEMBERS`. Look it up for the exact method you are calling,
+assume it is missing on a fresh app, and report it under
+[Manual Steps Required](../../SKILL.md#-manual-steps-required) by name. Wiring `errorState` on the
+table (the draft template does) is what turns this from silent skeletons into a message you can read.
+
+## A second vertical is a second scope
+
+The two checks above are easy to run once, at Step 3, for the vertical the page is obviously about —
+and then to skip for the *next* one, because by then you are deep in Step 4b adding a detail column
+or resolving a search term. That second package needs the same two things, and it fails differently:
+the page already worked, so the regression looks like something you broke in the UI.
+
+A measured run added `@wix/crm` mid-implementation to resolve a client-name search. The app held
+Bookings scopes and not `SCOPE.DC-CONTACTS.READ-CONTACTS`, the contacts call answered 403, and
+because the search awaited it unconditionally, a page that had been loading fine stopped loading at
+all.
+
+**Run the package-and-scope check for every `@wix/*` import you add, whenever you add it** — and
+then decide what its failure should cost:
+
+- **Primary source** — the rows themselves. Its failure is the page's failure; `errorState` reports it.
+- **Secondary source** — an enrichment lookup, a filter's option list, a term resolved to ids. Its
+  failure must cost only that feature. Wrap the call, fall back to the empty result, and say so in
+  the UI (`TableTopNotification` is the patterns component for it) rather than degrading silently.
+
+Ask which one you are adding before you write the `await`. An unwrapped secondary call is a page
+whose availability is the *intersection* of every scope it touches.
+
+## Querying and paging
+
+Filter field paths, WQL's one-operator-per-field rule, and the two cursor-paging traps are in
+[QUERY_AND_PAGING.md](QUERY_AND_PAGING.md). Read it before writing `fetchData` — every rule there
+was a shipped bug first.

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

@@ -0,0 +1,97 @@
+# Draft Template — the starting point for every dashboard page
+
+**Start here for any Dashboard Page request, before writing a shell, provider, or router from scratch.** Pick the case below, copy its files, rename, and adapt fields/API calls/data source. Only leave this file when the request needs something no case shows, and then go to [WIX_PATTERNS_DOCS.md](../WIX_PATTERNS_DOCS.md) first — before any lookup inside `node_modules/@wix/patterns`, `index.json` included. It routes you to the package's own `Collection Toolkit.md` guide, a component doc or an example; [TABLE_STATE.md](TABLE_STATE.md) and MCP lookups come after it.
+
+Every snippet below was copied from the installed `dist/docs/*.md` and `dist/dts-bundle/*.d.ts`, not from memory — confirm props against your own installed version before deviating.
+
+## Which case matches the request?
+
+| The request needs… | Case | Router? |
+| --- | --- | --- |
+| A list/report whose rows are read-only — no create/edit form | **A — Collection + read-only detail** | Yes |
+| A list **and** create/edit for each record (no separate app-settings area) | **B — Collection + Entity** | Yes |
+| Only app-wide settings/config — no list at all | **C — Settings only** | No |
+| A list, create/edit, **and** an app-settings area, all in one extension | **D — Collection + Entity + Settings** | Yes |
+
+Don't default to D because it's the most complete — [Step 4c's checklist](../../SKILL.md#step-4c-ux-completeness-self-audit) doesn't ask for a settings or entity page unless the request needs one. If unsure between B and D, re-read the prompt for "settings," "configure," "preferences" — their absence means B.
+
+## Then: what `fetchData` calls
+
+Case tells you how many pages. This tells you only what `fetchData` calls — the page itself is
+[DRAFT_TEMPLATE_COLLECTION.md](DRAFT_TEMPLATE_COLLECTION.md) either way:
+
+| The rows come from | `fetchData` calls |
+| --- | --- |
+| A vertical SDK (`@wix/bookings`, `@wix/ecom`, …) or any API you call yourself | that SDK's own query method — [DATA_SOURCES.md](DATA_SOURCES.md) |
+| A **CMS collection** — one your Data Collection extension ships, or an existing site collection | `@wix/data` `items.query()` — [WIX_DATA.md](../data-collection/WIX_DATA.md) |
+
+A CMS collection is not a different template, just a different call inside the same one: you write
+`fetchData`, the filters and the columns for both.
+
+**Cases B and D both need a router** — their entry file, app shell, and entity page are in [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md). The collection and settings files are shared by every case that uses them, B and D included; the router file links back rather than repeating them.
+
+## File layout
+
+```
+src/extensions/dashboard/pages/{feature}/
+  {feature}.extension.ts        # single wix generate scaffold — always exactly one route registered here
+  {feature}.tsx                 # entry — Case C: Section 1 below. Cases A/B/D: DRAFT_TEMPLATE_ROUTER.md
+  {Feature}App.tsx              # Case A/B/D only — see DRAFT_TEMPLATE_ROUTER.md
+  {Feature}CollectionPage.tsx   # Case A, B, D — see DRAFT_TEMPLATE_COLLECTION.md
+  {Feature}DetailPage.tsx       # Case A only — read-only detail route, DRAFT_TEMPLATE_ROUTER.md §4
+  {Feature}EntityPage.tsx       # Case B, D only — see DRAFT_TEMPLATE_ROUTER.md
+  {Feature}SettingsPage.tsx     # Case C, D only — see DRAFT_TEMPLATE_SETTINGS.md
+  {feature}-api.ts              # fetch/save calls — keep these out of the components
+```
+
+Scaffold with a single call regardless of case — this is always one extension:
+
+```bash
+wix generate --params '{"extensionType":"DASHBOARD_PAGE","title":"<title>","route":"<route>"}'
+```
+
+## 1. Entry — Case C only (router-free, no location plumbing)
+
+Case C has one page and no rows to open, so it needs no router and no manual `location` wiring. **Cases A, B and D all route** — a row opens a page of its own in every one of them — so their entry file is [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md) §1:
+
+```tsx
+// {feature}.tsx — Case C
+import type { FC } from 'react';
+import { withDashboard } from '@wix/patterns';
+import { WixPatternsProvider } from '@wix/patterns/provider';
+import { WixDesignSystemProvider } from '@wix/design-system';
+import '@wix/design-system/styles.global.css';
+import { {Feature}SettingsPage } from './{Feature}SettingsPage'; // DRAFT_TEMPLATE_SETTINGS.md
+
+const Page: FC = () => (
+  <WixDesignSystemProvider>
+    <WixPatternsProvider>
+      <{Feature}SettingsPage />
+    </WixPatternsProvider>
+  </WixDesignSystemProvider>
+);
+
+export default withDashboard(Page);
+```
+
+Cases A, B and D differ — they need `location` supplied manually for `PatternsReactRouter`. See [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md) rather than adding that plumbing here; it's dead code without a router underneath it.
+
+## 2. Collection page — Case A, B, D
+
+In [DRAFT_TEMPLATE_COLLECTION.md](DRAFT_TEMPLATE_COLLECTION.md) — `useTableCollection`, a working
+filter, the four placeholder states, and a row that opens. Shared by Cases A, B and D. No
+`SummaryBar` unless the request asked for one, and the drill-in is always a route — never a side
+panel.
+
+## 3. Settings page — Case C, D
+
+In [DRAFT_TEMPLATE_SETTINGS.md](DRAFT_TEMPLATE_SETTINGS.md) — `useSettingsPage` + `useForm`,
+with the same field-controller patterns as the entity page.
+
+## What to change vs. keep, per case
+
+| Change per request | Keep as shown |
+| --- | --- |
+| Feature/entity names, fields, columns, API calls in `{feature}-api.ts` | Which case (A/B/C/D) — don't over-build D for a request that only named a list |
+| Detail fields, form field types, columns | The drill-in being a route, and the absence of a `SummaryBar` the request never asked for |
+| Real data source (SDK-first per [SDK-First Rule](../../SKILL.md#sdk-first-rule-existing-wix-app-data-is-never-cms)) vs CMS | B/D wiring (provider/router nesting, `parentPath`, `location`): [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md) |

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

@@ -0,0 +1,184 @@
+# 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.