@wix/agent-skills 1.21.0 → 1.22.0

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

@@ -0,0 +1,203 @@
+# Draft Template — Cases A, B and D (router-wired)
+
+**Applies to [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md)'s Cases A, B and D.** All three need `PatternsReactRouter`, because in all three a row opens a page of its own — a panel is not the drill-in ([UX_SUCCESS_MODEL.md](UX_SUCCESS_MODEL.md)). Case A's detail route is read-only (§4); B and D route to a full `EntityPage`. The collection and settings components live in [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md); this file covers only what a router adds — the entry file, the app shell, and the detail/entity page.
+
+Every snippet below is copied from the installed `dist/docs/*.md` this session read, not from memory.
+
+## 1. Entry — `location` is manual in a Wix CLI app, and only because the router needs it
+
+`PatternsReactRouter` reads the page location through `container.usePageLocation()`, which only `withDashboard`'s `location` prop feeds — nothing supplies it automatically in a Wix CLI app the way Yoshi BM flow does:
+
+```tsx
+// {feature}.tsx — Case A, B or D
+import { useEffect, useState, type FC } from 'react';
+import { dashboard } from '@wix/dashboard';
+import { WixDesignSystemProvider } from '@wix/design-system';
+import '@wix/design-system/styles.global.css';
+import { {Feature}App } from './{Feature}App';
+
+type PageLocation = Parameters<Parameters<typeof dashboard.observeState>[0]>[1]['pageLocation'];
+
+const Page: FC = () => {
+  const [location, setLocation] = useState<PageLocation | undefined>();
+
+  useEffect(() => {
+    const subscription = dashboard.observeState((_pageParams, environment) => {
+      setLocation(environment.pageLocation);
+    });
+    return () => subscription.disconnect();
+  }, []);
+
+  return (
+    <WixDesignSystemProvider>
+      {location ? <{Feature}App location={location} /> : null}
+    </WixDesignSystemProvider>
+  );
+};
+
+export default Page;
+```
+
+**Skipping this is a runtime-only failure.** Per `PatternsReactRouter`'s own docs: "Nothing catches this before runtime — type checking and bundling both pass, because neither renders the page." `tsc` and `wix build` will not catch a missing `location` — only opening the page in a browser will. This is exactly why [Step 5's Preview](../../SKILL.md#validation) is not optional for Case B/D.
+
+## 2. App shell — provider, router, routes
+
+```tsx
+// {Feature}App.tsx — Case A, B or D
+import { withDashboard } from '@wix/patterns';
+import { WixPatternsProvider } from '@wix/patterns/provider';
+import { PatternsReactRouter, PatternsReactRoute } from '@wix/patterns/router';
+import { {Feature}CollectionPage } from './{Feature}CollectionPage';
+import { {Feature}EntityPage } from './{Feature}EntityPage';
+// Case D only:
+import { {Feature}SettingsPage } from './{Feature}SettingsPage';
+
+export const {Feature}App = withDashboard(() => (
+  <WixPatternsProvider>
+    <PatternsReactRouter>
+      <PatternsReactRoute type="collection" path="/" element={<{Feature}CollectionPage />} />
+      {/* Case B/D — editable record. Case A registers this ONE route instead, with
+          {Feature}DetailPage as the element and no /new route (§4). Either way the
+          type is `editEntity`: it wires back-navigation to the collection. */}
+      <PatternsReactRoute type="editEntity" path="/:id" element={<{Feature}EntityPage />} />
+      {/* Case B/D only — Case A has nothing to create: */}
+      <PatternsReactRoute type="createEntity" path="/new" element={<{Feature}EntityPage />} />
+      {/* Case D only: */}
+      <PatternsReactRoute type="other" path="/settings" element={<{Feature}SettingsPage />} />
+    </PatternsReactRouter>
+  </WixPatternsProvider>
+));
+```
+
+`PatternsReactRoute`'s `type` is one of exactly `"collection" | "createEntity" | "editEntity" | "other"` — no dedicated settings value, so a settings route is `"other"`. Case B: delete the `/settings` route and the import above it — nothing else changes.
+
+`{Feature}CollectionPage` is [DRAFT_TEMPLATE_COLLECTION.md](DRAFT_TEMPLATE_COLLECTION.md)'s component, unchanged; `{Feature}SettingsPage` (Case D) is [DRAFT_TEMPLATE_SETTINGS.md](DRAFT_TEMPLATE_SETTINGS.md).
+
+## 2b. The collection side of the handoff
+
+The router file above registers `/new`; something has to navigate there. All three of these live on
+the collection page, and `usePatternsNavigate` comes from **`@wix/patterns/router`** — not the root
+export, which is where it is easy to reach for it:
+
+```tsx
+import { PrimaryPageButton } from '@wix/patterns';
+import { usePatternsNavigate } from '@wix/patterns/router';
+
+const { navigateToEntityPage } = usePatternsNavigate<{Entity}>();
+const openNew = () => navigateToEntityPage({ path: '/new' }); // no record yet — omit `entity`
+
+// CollectionPage.Header — primaryAction takes an ELEMENT, not a { text, onClick } config:
+<CollectionPage.Header
+  title={{ text: '{Page Title}' }}
+  primaryAction={<PrimaryPageButton text="Add {entity}" onClick={openNew} />}
+/>
+
+// the empty state should offer the same action, and this one IS a config object:
+<CollectionEmptyState title="No {feature} yet" addNewCta={{ text: 'Add {entity}', onClick: openNew }} />
+
+// and a row opens the edit route:
+onRowClick={(item) => navigateToEntityPage({ path: `/${item.id}`, entity: item })}
+```
+
+The two shapes differ on purpose — `primaryAction` is an element, `addNewCta` is `{ text, onClick }`.
+Guessing either costs a compile round.
+
+## 3. Entity page — one component for both `/new` and `/:id`
+
+Full call details (both generics, what `onSave` receives, the `UseEntityPageParams` pick list) are in `<pkgRoot>/dist/docs/useEntityPage.md` — read it before filling in fields. The part specific to this router-based shape:
+
+```tsx
+// {Feature}EntityPage.tsx — Case B or D (sketch — see dist/docs/useEntityPage.md for the full call)
+import { useParams } from 'react-router-dom'; // NOT @wix/patterns/router — PatternsReactRoute wraps react-router-dom's Route, but only exports PatternsReactRoute/PatternsReactRouter/usePatternsNavigate itself
+import { useEntityPage, EntityPage } from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+import { fetch{Entity}, save{Entity}, type {Entity} } from './{feature}-api';
+
+// The form's shape is yours to declare, and need not match the saved entity type.
+type {Entity}FormFields = { name: string };
+
+export const {Feature}EntityPage = () => {
+  const { id } = useParams<{ id?: string }>();
+  const form = useForm<{Entity}FormFields>();
+
+  const state = useEntityPage<{Entity}, {Entity}FormFields>({
+    parentPath: '/', // NOT parentPageId — this shape always uses Patterns Router
+    isNewEntity: () => !id, // a getter: the route can change (/new -> /:id after save) while this stays mounted
+    form,
+    fetch: () => (id ? fetch{Entity}(id).then((entity) => ({ entity })) : Promise.resolve({ entity: undefined })),
+    onSave: ({ widgetsFormData }) =>
+      save{Entity}({ id, ...form.getValues(), ...widgetsFormData }).then((updatedEntity) => ({ updatedEntity })),
+  });
+
+  return (
+    <EntityPage state={state}>
+      <EntityPage.Header title={{ text: id ? 'Edit {Entity}' : 'New {Entity}' }} />
+      <EntityPage.Content>
+        <EntityPage.MainContent>{/* form cards — see dist/docs/EntityPage.md */}</EntityPage.MainContent>
+      </EntityPage.Content>
+    </EntityPage>
+  );
+};
+```
+
+`useEntityPage`'s own docs are explicit about both details above: `parentPath` "Must be passed if using Patterns Router" (`parentPageId` is the non-router alternative — irrelevant here, since Case B/D always uses the router), and `isNewEntity` should be "a getter when the route can change while the page stays mounted" — exactly this component's case, since a successful create typically navigates `/new` → `/:newId`.
+
+**`UseEntityPageParams` is a `Pick<>`, so a param missing from it is a compile error, not an ignored prop.** `isNewEntity` is in that list at 1.470.0 and absent before ~1.46x. If it doesn't compile, read the pick list in your installed `dist/types/hooks/useEntityPage.d.ts` and upgrade — deleting the line makes a create route behave as an edit.
+
+## 4. Read-only detail route — Case A
+
+A display-only collection still routes its rows to a page — but not an `EntityPage`, which has no
+read-only mode and still has none at **1.471.0**: `fetch` and `onSave` are both required, and
+`actionsBarConfig` (`saveCta.text`, `cancelCta`) can retext Save but not remove it. It would ship
+two buttons that either do nothing or save a form nobody was offered.
+
+Use a WDS `Page` — what Cairo does itself: `example-bm`'s `DataExtensionEntityViewPage` and
+auto-patterns' `ViewModeEntityPage` are both plain WDS `Page`s, the latter unexported.
+
+```tsx
+// {Feature}DetailPage.tsx — Case A
+import { useEffect, useState } from 'react';
+import { useParams } from 'react-router-dom';
+import { Card, Loader, Page, Text } from '@wix/design-system';
+import { usePatternsNavigate } from '@wix/patterns/router';
+import { fetch{Entity}, type {Entity} } from './{feature}-api';
+
+export const {Feature}DetailPage = () => {
+  const { id } = useParams<{ id: string }>();
+  const { navigateToCollectionPage } = usePatternsNavigate();
+  const [entity, setEntity] = useState<{Entity} | undefined>();
+
+  useEffect(() => {
+    if (id) {
+      fetch{Entity}(id).then(setEntity);
+    }
+  }, [id]);
+
+  return (
+    <Page>
+      {/* The way back is the header's back button — a read-only page has no Cancel. */}
+      <Page.Header
+        title={entity?.name ?? '{Entity}'}
+        showBackButton
+        onBackClicked={() => navigateToCollectionPage({ path: '/' })}
+      />
+      <Page.Content>
+        {entity ? (
+          <Card>
+            <Card.Header title="Details" />
+            <Card.Divider />
+            <Card.Content>
+              <Text>{entity.name}</Text>
+            </Card.Content>
+          </Card>
+        ) : (
+          <Loader />
+        )}
+      </Page.Content>
+    </Page>
+  );
+};
+```
+
+If the request later grows an edit form this becomes §3's `EntityPage`, route type and `onRowClick`
+unchanged — which is why Case A registers `editEntity`, not `other`.

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

@@ -0,0 +1,44 @@
+# Draft Template — Settings page (Cases C and D)
+
+> Pick your case in [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md) first; this page covers Case C or D.
+
+## The settings page
+
+No dedicated toolkit file exists for this yet (unlike Entity/Collection) — the shape, verified against `useSettingsPage.md`:
+
+```tsx
+// {Feature}SettingsPage.tsx — Case C or D
+import { SettingsPage, useSettingsPage, useSettings } from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+import { fetch{Feature}Settings, save{Feature}Settings, type {Feature}Settings } from './{feature}-api';
+
+// The form's shape is yours to declare, and need not match the saved settings type —
+// one field per control on the page.
+type {Feature}SettingsFormFields = { reminderHours: number; notifyStaff: boolean };
+
+export const {Feature}SettingsPage = () => {
+  const form = useForm<{Feature}SettingsFormFields>();
+
+  const state = useSettingsPage<{Feature}Settings, {Feature}SettingsFormFields>({
+    form,
+    fetch: () => fetch{Feature}Settings().then((settings) => ({ settings })),
+    onSave: () => save{Feature}Settings(form.getValues()),
+    onCancel: async () => form.reset(),
+    saveSuccessToast: 'Settings saved',
+    saveErrorToast: (err, { retry }) => ({ message: 'Failed to save settings', action: { text: 'Retry', onClick: retry } }),
+  });
+
+  const settings = useSettings<{Feature}Settings, {Feature}SettingsFormFields>(state);
+
+  return (
+    <SettingsPage state={state}>
+      <SettingsPage.Header title={{ text: '{Settings Page Title}' }} />
+      <SettingsPage.Content>
+        <SettingsPage.MainContent>{/* form cards — same field-controller patterns as EntityPage */}</SettingsPage.MainContent>
+      </SettingsPage.Content>
+    </SettingsPage>
+  );
+};
+```
+
+`useSettingsPage`'s params are all required except `saveSuccessToast`/`saveErrorToast`: `form`, `fetch`, `onSave`, `onCancel`. There is no `parentPath`/`parentPageId` — a settings page isn't reached by drilling into a row, so it carries no back-navigation contract, and Case C needs no router at all to reach it (Section 1's entry renders it directly).

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

@@ -0,0 +1,182 @@
+# Querying and paging a Wix API from a collection page
+
+> [DATA_SOURCES.md](DATA_SOURCES.md) covers finding the method and its fields; this page is about
+> calling it.
+
+Filters are written in **WQL**, which is shared across the platform — the rules below come from
+[About the Wix API Query Language][wql], not from one endpoint's behaviour, so they hold for
+`@wix/ecom`, `@wix/stores`, `@wix/bookings` and the rest alike.
+
+## The filterable fields are a closed list, published per endpoint
+
+> "This endpoint declares which fields it can filter and sort by, and with which operators; that
+> list is closed and covers this endpoint only. Anything else errors or silently returns the wrong
+> rows." — [WQL][wql]
+
+So a field path is never inferable from the entity shape, and the endpoint's own prose is not
+authoritative either. **Most query endpoints publish a "Supported Filters and Sorting" page**, and
+the SDK typedoc for the query's `filter` field links to it — Contacts, Orders, Products V3,
+Pipelines and Bookings all do. Find the link before you guess:
+
+```bash
+grep -rho "https://[^)]*supported-filters[^)]*" node_modules/@wix/<pkg>/build/es/*.d.mts | sort -u
+```
+
+**Read the page, don't just find it.** It is a table of field → operators, and it routinely lists
+more than the endpoint's prose implies — Query Extended Bookings' prose mentions filtering courses
+"by `scheduleId`", while its table also declares `serviceId` and the staff `resource.id` on both
+`bookedEntity` branches, and `contactDetails.contactId` / `.email`. Those are the difference between
+a page with two working filters and one with five.
+
+**Honour the *Filter Performance* note.** Many pages carry one, naming fields to include in every
+request — Query Extended Bookings "strongly recommends" `startDate` in all of them. Don't satisfy it
+by hiding a clause in `fetchData`: a filter the user cannot see or clear makes rows go missing for no
+visible reason. Seed the visible filter instead, so the default is applied, labelled and adjustable:
+
+```ts
+const dateFilter = dateRangeFilter({
+  name: 'Date',
+  initialValue: { from: startOfDay(subDays(new Date(), 30)), to: null },
+});
+```
+
+`initialValue` is on every filter factory (`FilterStateBaseParams`), so the same trick seeds a status
+or category default. Pick a window that matches the page's job — a booking review wants recent and
+upcoming, an audit log wants the last 24 hours.
+
+**A seeded default must not defeat search.** Search is a "find this anywhere" gesture, so a window
+the user never chose silently hiding matches from it reads as broken search — a measured run shipped
+exactly that, and the report was "search doesn't work", not "the date filter is too narrow". Bypass
+the range while it is still the seeded value, and keep it once the user has set their own:
+
+```ts
+const DEFAULT_FROM = startOfDayDaysAgo(30);
+const isUntouchedDefault = (r?: { from?: Date; to?: Date }) =>
+  !r?.to && r?.from?.getTime() === DEFAULT_FROM.getTime();
+// in fetchData AND fetchTotal:
+dateRange: search?.trim() && isUntouchedDefault(range) ? undefined : range,
+```
+
+Whatever a filter or a permission removes from the result, **say so in `noResultsState`** — "no
+matches" and "no matches because a default you didn't set, or a scope you don't hold, excluded them"
+look identical, and only the second is actionable.
+
+Two traps the list resolves, both of which look like a working filter:
+
+**Nested paths.** A field that reads as top-level on the entity is often only filterable at its full
+path. Query Extended Bookings describes itself as filtering "by `scheduleId` of the relevant
+service", and a bare `scheduleId` is rejected outright — the accepted paths are nested under
+`bookedEntity`. The error names the offending path exactly, so one call settles it:
+
+```json
+{ "code": "INVALID_FILTER", "data": { "unknownField": { "fieldPath": "scheduleId" } } }
+```
+
+**Oneof branches.** When the entity has a oneof, one path covers only one branch, and a filter over
+just that branch silently drops every row of the other kind — exactly as the row mapper has to
+handle both. Cover them with `$or`, and check each branch separately before wiring it into a page:
+
+```ts
+$or: [
+  { 'bookedEntity.item.slot.scheduleId':     { $in: scheduleIds } },
+  { 'bookedEntity.item.schedule.scheduleId': { $in: scheduleIds } },
+]
+```
+
+## One operator per field
+
+> "The filter is written in WQL, where each field takes a single operator, so conditions are
+> combined with the logical operators instead: `$and` and `$or` take an array of expressions,
+> `$not` takes one, and they can nest. They are WQL syntax, not field capabilities." — [WQL][wql]
+
+A date range written the obvious way therefore fails, and the error quotes the whole object back as
+the offending "operator", which reads like a parser bug and is actually the rule:
+
+```ts
+{ startDate: { $gte: from, $lte: to } }   // INVALID_FILTER — unknownOperator
+```
+
+Ranges are two clauses under `$and`; `$or` nests inside it:
+
+```ts
+{ $and: [
+  { status: { $in: statuses } },
+  { startDate: { $gte: from } },
+  { startDate: { $lte: to } },
+  { $or: [ /* the oneof branches */ ] },
+] }
+```
+
+Build the filter as a list of clauses and wrap it at the end — return the bare clause when there is
+only one, `{}` when there are none — rather than mutating one object and hoping the operators do not
+collide. A page with several filters hits this the moment two of them apply at once, which is
+usually after the single-filter case has already been called working. The full operator set —
+including `$not`, `$nin`, `$exists`, `$isEmpty`, `$hasAll`, `$hasSome` — is in the [WQL article][wql].
+
+## A follow-up cursor page carries the cursor alone
+
+The cursor already encodes the filter and sort of the query that produced it, so re-sending them is
+rejected. This is not one API's quirk: it is stated on the `cursorPaging.cursor` field of every
+generated Wix SDK that offers cursor paging — 46 of the 179 `auto_sdk_*` packages in one install —
+in a standard sentence you can read before making a request:
+
+> "Cursor token pointing to a page of results. Not used in the first request. Following requests use
+> the cursor token and not `filter` or `sort`."
+
+Build the first request and the follow-ups differently:
+
+```ts
+const response = await ns.query(
+  query.cursor
+    ? { cursorPaging: { limit: query.limit, cursor: query.cursor } }
+    : { filter, sort, cursorPaging: { limit: query.limit } },
+);
+```
+
+Sending them together answers `"Invalid cursor. Sort or filter can not be specified together with
+cursor"` — and because the collection retries, that renders as a spinner under the last row, which
+reads as "still loading". What you return on the **last** page is the collection's own contract, and
+has its own trap: [TABLE_STATE.md](TABLE_STATE.md#query-and-result-shapes).
+
+Cursor mode also takes a separate `fetchTotal`, since a cursor-paged response carries no total.
+Build its filter exactly as the page's, or the count disagrees with the rows it counts.
+
+## What `fetchTotal` is allowed to call
+
+`fetchTotal: (query) => Promise<number>`. It has to resolve **a number from something that
+counts** — and the obvious-looking source is not one. A cursor-paged response carries no total,
+so `pagingMetadata.total` is `undefined` — and `undefined` reaches the collection as `0`.
+`@wix/data` spells the rule out on `PagingMetadataV2.total`: "Returned if offset paging is used,
+`returnTotalCount` is `true` in the request, and `tooManyToCount` is false." Read the field's own
+doc comment in the SDK you are calling rather than assuming it is populated. That is the whole of the
+"`SummaryBar` reads 0 while the table under it is full of rows" bug, and it survives review
+because nothing throws and nothing fails to compile.
+
+Use a real count, in this order:
+
+```ts
+// 1. A CMS collection: `items.query(id)` returns a builder whose `.count()` is
+//    `Promise<number>` and honours the filter you put on it. Apply the page's
+//    filter with the same function fetchData uses, so the two cannot drift.
+//    (The standalone `items.count(id)` is marked @internal and takes no filter.)
+const count{Feature} = (q: {Feature}Query): Promise<number> =>
+  apply{Feature}Filter(items.query(COLLECTION_ID), q).count();
+
+// 2. A vertical SDK with its own count endpoint: call that — it already returns a number.
+
+// 3. Offset paging only — ask for the count, then read it back:
+const { pagingMetadata } = await ns.query({ paging: { limit, offset }, returnTotalCount: true });
+return pagingMetadata?.total ?? 0; // `?? 0` is honest HERE: you asked for the count
+```
+
+**If the API offers no count at all, omit `fetchTotal`.** `collection.total` then falls back to the
+rows loaded so far, which is a real number you can label ("50 shown") instead of a confident `0`.
+Never paper over the gap with `?? 0` on a field that is simply absent.
+
+## When a table will not settle
+
+An extension runs in a cross-origin iframe whose console you cannot read, but its own `SummaryBar`
+will happily display `state.collection.status.status`, a fetch counter and the last rejection
+message. That is what turns "it spins" into a named error in one reload.
+
+[wql]: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language

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

@@ -0,0 +1,133 @@
+# Reading the state object `useTableCollection` hands you
+
+> **Scope.** The [Component Docs Gate](../../SKILL.md) covers component *names and props*, and the
+> package's own `TableState` declaration is the member list. This file covers only what that
+> declaration cannot tell you: the plausible members that are absent from it, and the behaviour
+> behind the ones that are there.
+
+## Why guessing here always fails
+
+`useTableCollection()` returns a `TableState`. For the members themselves, read the declaration the
+index names — `Read <pkgRoot>/dist/dts-bundle/index.json`, then its `file`. Reading them is not the
+hard part; the hard part is that several plausible members don't exist at all, and one that does
+means something other than its name suggests (see
+[Four that bite in practice](#four-that-bite-in-practice)).
+
+**One thing not to conclude from the docs bundle.** `dist/dts-bundle/` publishes `CollectionState`
+as a stub:
+
+```ts
+declare class CollectionState<T = any, F = any> { [key: string]: unknown }
+```
+
+That is a documentation abridgement, not the declaration your code compiles against. `tsc` resolves
+`dist/types/index.d.ts`, which re-exports the **fully typed** `CollectionState` from
+`@wix/bex-core` — no index signature. So `state.collection.…` is properly typed, a wrong member is a
+compile error at the access, and reading `state.collection.status.status` to debug a stuck table is
+sound. See [WIX_PATTERNS_DOCS.md § 5](../WIX_PATTERNS_DOCS.md#5--traps-that-make-a-read-wrong).
+
+Prefer a typed member on `TableState` itself anyway — it is the object the hook hands you, and the
+table's own view of the collection.
+
+## Four that bite in practice
+
+**`state.filters` does not exist.** Filter state lives on the filter objects you created with
+`stringsArrayFilter()` / `dateRangeFilter()` and passed into `filters`. Keep those in module-level
+consts and reference the const in both the hook config and the JSX — that is also what
+`MultiSelectCheckboxFilter`'s `filter` prop wants.
+
+**`showLoadingState` is not "the query is running".** It stays `true` when the query resolves with
+zero rows, so binding `SummaryBar`'s `status` to it leaves the bar on skeleton pills permanently on
+an empty collection — which reads as a hung network rather than an empty result. Use
+`state.showErrorState ? 'error' : 'success'`.
+
+**`collection.isLoading` and `collection.refresh()` are not members.** They look plausible, they
+compile against the index signature, and neither exists at runtime.
+
+### A `fetchTotal` that resolves undefined shows 0, not the rows
+
+This is the "`SummaryBar` says 0 while the table under it is full" report, and it is worth tracing
+once because every step is silent. `FetchTotalState` wraps your function in a second, one-item
+collection whose page is literally `{ items: [], total: await fetchTotal(query) }`. That page then
+goes through `CollectionState.updateResult`, which computes
+`lastPage.total ?? lastPage.items.length` — so a `total` of `undefined` becomes `0`, because the
+synthetic page has no items to fall back on. And `QueryResultState.total` reads
+`fetchTotal ? fetchTotal.total : this._totals.processed`: **the moment `fetchTotal` exists it wins,
+and the loaded-rows fallback is gone.**
+
+Two consequences worth keeping in mind:
+
+- **A wrong `fetchTotal` is worse than no `fetchTotal`.** Omit it and `total` degrades to the rows
+  you have; wire it to something that resolves `undefined` and a page with 4,000 matching rows
+  reports `0`. Nothing throws, nothing fails `tsc`, and the table beside it is correct.
+- **`pagingMetadata.total` is not a count.** A cursor-paged response carries no total, and
+  `@wix/data` documents the field as returned only under *offset* paging with
+  `returnTotalCount: true`. Under the cursor paging these pages default to, expect `undefined`.
+  Call something that counts —
+  [QUERY_AND_PAGING.md](QUERY_AND_PAGING.md#what-fetchtotal-is-allowed-to-call).
+
+To tell the two apart in a running page, show `state.collection.totalStatus` next to the number:
+it is the totals collection's own status, so a `success` beside a `0` means your function resolved
+nothing, not that the query failed.
+
+## Reading state outside the table: it is MobX
+
+`@wix/patterns` depends on `mobx` and `mobx-react-lite`, so the state object is observable and a
+plain React component does not track it. Anything you derive from `state` in your own component —
+a `SummaryBar` count, a badge total, a header figure — is computed once on first render, when the
+collection is still empty, and never recomputed. The table itself updates because it observes
+internally; your derived numbers sit at zero next to a table full of rows, which reads as a bug in
+the query rather than in the wiring.
+
+`useSelector` from `@wix/patterns` subscribes:
+
+```tsx
+const loadedCount = useSelector(() => state.keyedItems.length);
+const rows = useMemo(() => state.keyedItems.map((k) => k.item), [loadedCount]);
+```
+
+**Select a primitive.** Returning a fresh array or object from the selector gives it a new identity
+on every evaluation. Select a length, a total or an id, then derive the rest once it fires.
+
+## Query and result shapes
+
+`fetchData(query)` receives a `ComputedQuery<F>`: `limit`, `offset`, `page`, `search`, `rawSearch`,
+`cursor`, `filters`, `rawFilters`, `sort`.
+
+**Read the return type from `@wix/bex-core`, not from `@wix/patterns`.** The name
+`CursorQueryResult` exists in both packages and they are different types. The one your `fetchData`
+must satisfy is the generic in `node_modules/@wix/bex-core/dist/types/hooks/paginationModeConfig.d.ts`:
+
+```ts
+interface DataResultRaw<T> {
+  items: T[];
+  total?: number | null;
+  available?: number;                          // total BEFORE filters
+  cursor?: string | undefined | null;
+  hasNext?: boolean | null;
+}
+type OffsetQueryResult<T> = Omit<DataResultRaw<T>, 'cursor'>;
+type CursorQueryResult<T> = Omit<DataResultRaw<T>, 'cursor'> & { cursor: string | undefined | null };
+```
+
+Three consequences, each of which has shipped as a bug:
+
+**In cursor mode the `cursor` key is required; its value may be `undefined`.** The intersection
+re-declares `cursor` without `?`, so `return { items }` does not compile — but
+`{ items, cursor: undefined }` does. "Required" is about the key, not the value.
+
+**On the last page return `undefined`, never `''`.** An empty string is still a cursor to the
+collection: it requests the next page forever and appends the same rows each pass, a table that
+grows without end while the API is perfectly happy, rendering as a spinner under the last row that
+reads as "still loading". Derive it so the empty case collapses:
+
+```ts
+cursor: response.pagingMetadata?.cursors?.next || undefined,
+```
+
+**`hasNext` and `total` exist in both modes** — they are on `DataResultRaw`, which both aliases
+extend. Cursor mode also accepts a separate `fetchTotal`, since a cursor-paged response carries no
+total; build its filter exactly as the page's or the count disagrees with the rows it counts.
+
+Look any of these up yourself with `Read <pkgRoot>/dist/dts-bundle/index.json` and the `file` path it
+gives; the index is the single source of truth, and it moves between versions.

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

@@ -124,12 +124,17 @@ Choose the smallest interface that gives users enough context and room to comple
 
 | Interface | Use when… | Success looks like… |
 |---|---|---|
-| **Side panel** | The user should review or update one item while keeping the dashboard visible. | Context is preserved while deeper work remains focused. |
-| **Modal** | The user needs to complete a focused, bounded task or decision. | Attention stays on one task and the user can return cleanly. |
-| **Entity page** | The task involves complex details, multi-section editing, history, or related information. | The user has enough space and structure to complete deeper work. |
-| **Inline or expanded row** | The user needs a quick inspection or simple action. | Detail appears without creating a separate workspace. |
+| **Entity page** | The item is editable — the default for a business record. | Enough space and structure to complete deeper work. |
+| **Read-only detail page** | The collection is display-only. | Fully readable, linkable, one back-click from the list. |
+| **Modal** | A focused, bounded task that is not "open this record". | Attention stays on one task; the user returns cleanly. |
+| **Inline or expanded row** | A quick look *alongside* the drill-in, not instead of it. | Detail appears without a separate workspace. |
 
-Which Wix primitive builds each of these — and which components serve the summaries, filters and empty states named above — is in the installed package's `Collection Toolkit.md` guide — reached through [The Discovery Chain](../WIX_PATTERNS_DOCS.md#the-discovery-chain). Patterns has no side panel; that one is WDS.
+Opening an item is a **route**, editable or not — a constraint, not a preference, and it outranks
+"smallest interface". A side panel is not one of the choices: in Cairo it hosts a page's own
+panels. A display-only record still routes, just to a WDS `Page`, since `EntityPage` has no view
+mode.
+
+Which Wix primitive builds each of these — and which components serve the summaries, filters and empty states named above — is in the installed package's `Collection Toolkit.md` guide — reached through [The Discovery Chain](../WIX_PATTERNS_DOCS.md#the-discovery-chain).
 
 
 ## Data Success

package/skills/wix-app/references/data-collection/LIFECYCLE.md

@@ -0,0 +1,68 @@
+# Data Collection — getting it onto the site
+
+> Declaring a collection is not the same as creating one. Releasing, updating the site, the CMS
+> prerequisite, and what access the extension actually grants.
+
+## Item access and collection management are different scopes
+
+The data-collections extension gives your app read/write access to the **items** in its own
+collections — `items.query/insert/update` work with no extra scope. It does **not** grant the
+collection-*management* API: `collections.listDataCollections()` and friends answer 403 unless the
+app holds a Data Collections management scope.
+
+That asymmetry is worth knowing before you debug: a page whose table loads rows has proved its
+collection exists, because Wix Data errors on a missing collection rather than returning empty. If
+that same page cannot list collections, the app is missing a management scope — a separate fact
+about tooling, not evidence about the collection.
+
+## Reading the collection from a dashboard page
+
+A page over a CMS collection is an ordinary collection page: the template is
+[DRAFT_TEMPLATE_COLLECTION.md](../dashboard-page/DRAFT_TEMPLATE_COLLECTION.md), and its `fetchData`
+calls `@wix/data` `items.query()` — see [WIX_DATA.md](WIX_DATA.md) for the query, result and paging
+shapes. You write the filters and the columns yourself, exactly as for a vertical SDK.
+
+## The site must have CMS, or nothing is created at all
+
+**The installing site needs the CMS (Content Manager) app.** Per the extension's own docs:
+"Without it, collections added by the extension won't appear after installation." Nothing warns
+you — the release succeeds, the update succeeds, and the collection silently never exists. Bundle
+CMS as an [app dependency](https://dev.wix.com/docs/build-apps/launch-your-app/market-listing/add-app-dependencies)
+so installing your app brings it, and list "add CMS to the site" under
+[Manual Steps Required](../../SKILL.md#-manual-steps-required) for any site that may not have it.
+
+This is the first thing to check when a collection is missing after a correct release and update.
+
+## The extension does not create the collection
+
+Scaffolding the extension, compiling, and even releasing all leave the site's CMS unchanged.
+A collection appears only when the app is **installed or updated on the site** with a version that
+contains the extension — and any change under `data-collections/` needs a **major** version:
+
+```bash
+npx wix release --version-type major -c "<what changed>"
+```
+
+Releasing is only half of it. **Report both remaining browser steps under
+[Manual Steps Required](../../SKILL.md#-manual-steps-required)** — they are the difference between a
+page that works and one that shows an empty table:
+
+1. Update the app on the site to the new version.
+2. Wait up to 5 minutes for propagation.
+
+A dev server running a version override does not create collections either, so "I ran `wix dev` and
+the collection isn't in the CMS" is this step, not a bug.
+
+## App Version Updates
+
+Changes to your data collections extension require releasing a new major version of your app. When a user updates to the new major version, their collections are updated as follows:
+
+- **Adding a new collection:** The new collection is created on the site.
+- **Removing a collection:** If the old app version defined a collection and the new version doesn't, the collection is removed from the site.
+- **Modifying a collection schema:** Field additions, removals, and type changes are applied to the collection. Existing data is preserved.
+
+**Important notes:**
+
+- Collection changes only affect users who update to the new major version. Users who don't update retain their current collections.
+- Collection changes take up to 5 minutes to propagate after an update.
+- **Initial data is only imported when a collection is first created.** If a collection already contains data, `initialData` is ignored during updates.