@wix/agent-skills 1.17.0 → 1.18.0

package/skills/wix-app/references/WIX_PATTERNS_DOCS.md

@@ -2,18 +2,49 @@
 
 ## Prerequisites
 
-The docs are pre-built at `node_modules/@wix/patterns/dist/docs/` (160+ markdown files + `index.json`). This requires `@wix/patterns` version **1.367.0** or later. Verify they exist:
+Lookups here are direct file reads — no script. Resolve the installed package root once per session and reuse it:
 
 ```bash
-ls node_modules/@wix/patterns/dist/docs/   # expect ~165 .md files + index.json
+node -e "
+const fs = require('fs'), path = require('path');
+function tryEnablePnp() {
+  let dir = process.cwd();
+  for (;;) {
+    const pnp = path.join(dir, '.pnp.cjs');
+    if (fs.existsSync(pnp)) { try { require(pnp).setup(); } catch {} return; }
+    const parent = path.dirname(dir);
+    if (parent === dir) return;
+    dir = parent;
+  }
+}
+tryEnablePnp();
+try {
+  console.log(path.dirname(require.resolve('@wix/patterns/package.json', { paths: [process.cwd()] })));
+} catch {
+  let dir = process.cwd();
+  for (;;) {
+    const candidate = path.join(dir, 'node_modules', '@wix', 'patterns');
+    if (fs.existsSync(path.join(candidate, 'package.json'))) { console.log(candidate); process.exit(0); }
+    const parent = path.dirname(dir);
+    if (parent === dir) { console.error('@wix/patterns not found'); process.exit(1); }
+    dir = parent;
+  }
+}
+"
 ```
 
-If the directory is missing, install the package at the minimum version:
+A bare `require.resolve` without the PnP-activation step throws in a Yarn Berry project even when the package is installed — run the whole snippet, not a shortened version.
+
+Then confirm the installed version actually ships the bundle index:
 
 ```bash
-npm install @wix/patterns@^1.367.0
+ls <pkgRoot>/dist/dts-bundle/index.json
 ```
 
+**If it's missing, stop — do not look elsewhere for types or docs.** The installed `@wix/patterns` predates the index; it ships from **1.458.0** onward, so upgrade to at least that and re-run the check. A missing *file* is not the same as a name not being covered (see below): the mechanism itself isn't available yet.
+
+**Never inspect `node_modules` by hand** — no `ls`, no `find`, no `cat` of an arbitrary path, and that includes the sanctioned directories: never browse `dist/dts-bundle/` or `dist/docs/` looking around. Every lookup below names the exact file to `Read` — go straight to it.
+
 ## Library Architecture
 
 ### Composition Hierarchy
@@ -29,55 +60,33 @@ Provider                     <- WixPatternsProvider or WixPatternsBMProvider
 
 Each collection type follows the same Component + State + Hook pattern:
 
-| Collection       | Component          | State Type              | Hook                            |
-|------------------|--------------------|-------------------------|---------------------------------|
-| Table            | `Table`            | `TableState`            | `useTableCollection()`          |
-| Grid             | `Grid`             | `GridState`             | `useGridCollection()`           |
-| TableGridSwitch  | `TableGridSwitch`  | `TableGridSwitchState`  | `useTableGridSwitchCollection()`|
-| TableFolders     | `TableFolders`     | `TableFoldersState`     | `useTableFolders()`             |
-| GridFolders      | `GridFolders`      | `GridFoldersState`      | `useGridFolders()`              |
-
-This table covers the common collection types — the full, authoritative list is in `node_modules/@wix/patterns/dist/docs/index.json`.
+| Component | State Type | Hook |
+| --- | --- | --- |
+| `Table` | `TableState` | `useTableCollection()` |
+| `Grid` | `GridState` | `useGridCollection()` |
+| `TableGridSwitch` | `TableGridSwitchState` | `useTableGridSwitchCollection()` |
+| `TableFolders` | `TableFoldersState` | `useTableFolders()` |
+| `GridFolders` | `GridFoldersState` | `useGridFolders()` |
 
-Create state with the hook -> pass it to the component's `state` prop -> wrap in a page component.
+Common types only; `dist/dts-bundle/index.json` has the authoritative set. Create state with the hook -> pass it to the component's `state` prop -> wrap in a page component.
 
 ### Choosing the Right Provider
 
-| Provider                        | When to Use                                                                          |
-|---------------------------------|--------------------------------------------------------------------------------------|
-| `WixPatternsProvider`           | **Default — start here.** Auto-detects the environment (BM, Essentials, Giza) and supplies the right context. |
-| `WixPatternsBMProvider`         | Optional alternative for Yoshi BM Flow over Business Manager.                        |
-| `WixPatternsGizaProvider`       | Optional alternative for Yoshi BM Flow over Giza.                                    |
-| `WixPatternsEssentialsProvider` | Yoshi Fullstack.                                                                     |
-| `WixPatternsBaseProvider`       | App does **not** run under a Giza/WixEssentials environment and you inject services (i18n, sentry) yourself. |
-
-Prefer `WixPatternsProvider` unless the project is on one of the specific Yoshi flows above — it is the documented recommendation for most apps, and it resolves the environment for you rather than making you pick.
+| Provider | When to Use |
+| --- | --- |
+| `WixPatternsProvider` | **Default — start here.** Auto-detects the environment (BM, Essentials, Giza). |
+| `WixPatternsBMProvider` | Optional alternative for Yoshi BM Flow over Business Manager. |
+| `WixPatternsGizaProvider` | Optional alternative for Yoshi BM Flow over Giza. |
+| `WixPatternsEssentialsProvider` | Yoshi Fullstack. |
+| `WixPatternsBaseProvider` | App does **not** run under Giza/WixEssentials and you inject services (i18n, sentry) yourself. |
 
-**Confirm the import path in the provider's own doc file** — these do not all come from the same subpath (`WixPatternsEssentialsProvider` and `WixPatternsBaseProvider` are under `@wix/patterns/essentials`, for instance). Check the project's `package.json` to identify the flow.
+**Confirm the import path in the provider's own bundle** — they don't all share a subpath (`WixPatternsEssentialsProvider` and `WixPatternsBaseProvider` are under `@wix/patterns/essentials`). The project's `package.json` identifies the flow.
 
 ### Keep Provider and Page Separate
 
-The provider **must** be in a separate parent component from the page content. Hooks like `useTableCollection` require the provider's context to already exist above them in the React tree.
+The provider **must** live in a parent component of the page content: hooks like `useTableCollection` need its context to already exist above them in the React tree.
 
-**Wrong — provider and page in the same component:**
-```tsx
-function BadApp() {
-  const state = useTableCollection({
-    queryName: 'my-items',
-    itemKey: (item) => item.id,
-    itemName: (item) => item.name,
-    fetchData: async () => ({ items: [], total: 0 }),
-    filters: {},
-  }); // fails at runtime — no provider context above this component
-  return (
-    <WixPatternsProvider>
-      <CollectionPage>
-        <Table state={state} columns={[{ title: 'Name', render: (item) => item.name }]} />
-      </CollectionPage>
-    </WixPatternsProvider>
-  );
-}
-```
+**Wrong:** calling `useTableCollection` in the same component that renders `WixPatternsProvider`. The hook runs before the provider exists above it, so it throws at runtime — and the JSX nesting looks right, which is what makes this hard to spot.
 
 **Correct — provider in root, page in a separate file:**
 ```tsx
@@ -97,13 +106,14 @@ import { Table, useTableCollection } from '@wix/patterns';
 import { CollectionPage } from '@wix/patterns/page';
 
 function MyCollectionPage() {
+  // works — the provider context exists above this component
   const state = useTableCollection({
     queryName: 'my-items',
     itemKey: (item) => item.id,
     itemName: (item) => item.name,
     fetchData: async () => ({ items: [], total: 0 }),
     filters: {},
-  }); // works — the provider context exists above this component
+  });
   return (
     <CollectionPage>
       <Table state={state} columns={[{ title: 'Name', render: (item) => item.name }]} />
@@ -112,33 +122,33 @@ function MyCollectionPage() {
 }
 ```
 
-Always keep the provider (and router if needed) in the app's root component, and each page in its own file.
+Keep the provider (and router, if any) in the app's root component and each page in its own file.
 
-When the user needs **multiple pages**, use the `@wix/patterns` routing solution (`PatternsReactRouter`, `PatternsReactRoute`, `usePatternsNavigate`) instead of a separate router. Look up the relevant doc files for setup details.
+For **multiple pages**, use the `@wix/patterns` routing solution (`PatternsReactRouter`, `PatternsReactRoute`, `usePatternsNavigate`) rather than a separate router; look the doc files up for setup.
 
 ## How to Look Things Up
 
 **Don't guess which components or props exist — read the doc files first.**
 
-### Finding the right file
+### Finding the right name
+
+`Read <pkgRoot>/dist/dts-bundle/index.json` — one entry per name, grouped implicitly by its `category` field. Lookup is **exact-match only**: no fuzzy matching, no typo suggestions. If the exact key isn't there, scan the index you already hold for something close before concluding the name isn't covered.
 
-- **By name:** Read `node_modules/@wix/patterns/dist/docs/index.json` — it maps every component name to its doc file and category.
-- **By browsing:** List the `dist/docs/` folder. Filenames match component names directly (e.g., `Table.md`, `useTableCollection.md`). Note some names contain spaces (`AI Assistant.md`) or dots (`CollectionPage.Header.md`) — quote paths when searching.
-- **By concept:** Search filenames for keywords (e.g., "filter"). Check `index.json` categories — related components share a category prefix.
+Not every real `@wix/patterns` export is in this index — only the names these guides actually reference. If a name you need genuinely isn't there, **stop and say so rather than falling back to `node_modules`.**
 
 ### Reading doc files
 
-Each doc contains the component's category, import path, description, code examples, and API props table. **Always check the import statement** — not everything comes from `@wix/patterns` (some use subpaths like `@wix/patterns/provider`).
+`Read <pkgRoot>/dist/docs/index.json` to resolve a name to its doc file — or a `symbols` alias, for the cases where the Storybook title doesn't match the export (`ExportTo.md` documents `ExportButton`) — then `Read <pkgRoot>/dist/docs/<file>.md` directly, the whole file, not piped through `head`. It covers more names than the bundle index above: it's produced for every documented component, not just the curated ones.
 
-### Following cross-references
+**Always check the import statement inside the doc** — not everything comes from `@wix/patterns` (some use subpaths like `@wix/patterns/provider`).
 
-Docs contain relative Storybook URLs like `[TableState](./?path=/story/...--tablestate)`. To resolve these, **use the link text as the filename**: `[TableState](...)` -> read `TableState.md`.
+### Reading the file the index names
 
-Links to `https://www.docs.wixdesignsystem.com/` are external (Wix Design System) — not part of `@wix/patterns` docs.
+The mechanics of the file an index names — types the docs don't cover, which one-line stubs are answers rather than truncation, subpath entry points, cross-references, split compound-component docs — are in [Reading bundles and docs](dashboard-page/PATTERNS_BUNDLE_READING.md). Read it before your first `dist/dts-bundle/*.d.ts` of the session.
 
 ## The Collection → Entity Flow
 
-A collection page and its item form are **two patterns pages**, not a page plus a modal. Getting the table right and then hand-building the "add item" form in a dashboard modal is the most common way this goes wrong.
+A collection page and its item form are **two patterns pages**, not a page plus a modal. Getting the table right and then hand-building the "add item" form as a dashboard modal is the most common way this goes wrong.
 
 | Step | What owns it |
 | --- | --- |
@@ -149,24 +159,20 @@ A collection page and its item form are **two patterns pages**, not a page plus
 | Body layout | `EntityPage.Header`, `.MainContent`, `.AdditionalContent`, `.Card` |
 | The individual fields inside those cards | `@wix/design-system` (`FormField`, `Input`, `Text`) |
 
-`navigateToEntityPage` is preferred over a plain route change because the entity header (title, subtitle, breadcrumbs) renders immediately, without waiting for the fetch.
+Prefer `navigateToEntityPage` over a plain route change: the entity header (title, subtitle, breadcrumbs) renders immediately, without waiting for the fetch.
 
-Read `EntityPage.md`, `useEntityPage.md`, and `usePatternsNavigate.md` before implementing — and note that `useCreateCollection` is **not** about creating items; it returns a function that initializes collection state.
+Read `EntityPage.md`, `useEntityPage.md`, and `usePatternsNavigate.md` before implementing — and note `useCreateCollection` is **not** about creating items; it returns a function that initializes collection state.
 
-Reserve dashboard modals for genuine dialogs — delete confirmations, short prompts — not entity editing.
+Three things about the `useEntityPage` call are worth getting right first time — both generics, what `onSave` receives, which params exist: [ENTITY_PAGE_TOOLKIT.md](dashboard-page/ENTITY_PAGE_TOOLKIT.md).
+
+Reserve dashboard modals for dialogs that neither write nor display a listed record — a delete or discard confirmation, an unsaved-changes prompt. **A create / "add new" form is not one of them**: it writes the record, so it is an `EntityPage` even though nothing is being edited yet. Size and field count are not exceptions — a one-field create form is still an `EntityPage`. A page that lists no records is outside this rule.
 
 ## When Patterns Has No Equivalent
 
-A concept is only "missing" from patterns after you've checked `index.json` **and** searched the docs folder by keyword. Then, and only then:
+A concept is only "missing" from patterns after you've checked `dist/dts-bundle/index.json` and `dist/docs/index.json` **and** searched by keyword within what you've read. Then, and only then:
 
 1. Look the component up in `@wix/design-system` via the `wix-design-system` skill.
 2. Render it *inside* the patterns page shell / collection, not as a replacement for it.
-3. If WDS lacks it too, compose from WDS primitives (`Box`, `Card`, `Text`) — never restyle patterns internals or add another UI library.
-
-Anything page- or collection-shaped (page shell, header, table, grid, filters, sorting, paging, row actions, bulk actions) is patterns' territory. If you're about to build one of those from WDS parts, you skipped a lookup.
-
-## Tips
+3. If WDS lacks it too, compose from WDS primitives (`Box`, `Card`, `Text`) — never restyle patterns internals, never add another UI library.
 
-- **Compound components** have separate docs per sub-part: `CollectionPage.md`, `CollectionPage.Header.md`, `CollectionPage.Content.md`.
-- **Hook docs** list configuration options as props in the API table.
-- **Type docs** (e.g., `TableState.md`) describe the shape of state objects.
+Anything page- or collection-shaped (page shell, header, table, grid, filters, sorting, paging, row and bulk actions) is patterns' territory. If you're about to build one from WDS parts, you skipped a lookup.

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

@@ -0,0 +1,79 @@
+# Collection Toolkit — what to reach for, per user need
+
+[UX_SUCCESS_MODEL.md](UX_SUCCESS_MODEL.md) says what a dashboard must do for the person using it. This file says which component does it, so the stage list resolves to real names instead of a hand-rolled approximation.
+
+Everything below is a real name in the installed `@wix/patterns`. Confirm the props before writing JSX by reading its doc from `dist/docs/index.json` — and if a name is missing from `dist/dts-bundle/index.json`, the installed version is older than this file; work from that inventory, not from memory.
+
+> **The two requirements below are not suggestions.** A page that renders a filtered table and nothing else is the single most common failure of a generated dashboard: it answers "what are all the records" and nothing about how many, which one needs attention, or why something happened. Measured runs produce exactly that page unless the requirement is stated.
+>
+> 1. **A dashboard that reports on records shows aggregate numbers**, not only rows.
+> 2. **A dashboard whose rows represent real business records lets the user open one**, unless the prompt is explicitly a report or an export.
+
+## Understand — the aggregate
+
+| Need | Component |
+| --- | --- |
+| Totals, counts, status breakdown above the table | `SummaryBar` |
+| Which subset the numbers describe | wire each metric to the collection's filter state so the count follows the filters |
+
+`SummaryBar` sits inside the page shell, above the collection. Compute the values from the same query the table uses, or a count query alongside it — a metric that disagrees with the visible rows is worse than no metric.
+
+## Focus — narrowing
+
+| Need | Component |
+| --- | --- |
+| Free-text search | `CollectionSearch` |
+| The filter bar itself | `CollectionToolbarFilters` |
+| Pick several values from a known list | `MultiSelectCheckboxFilter`, `MultiInlineCheckboxFilter`, `MultiAutoInlineCheckboxFilter` |
+| Pick one value | `SingleSelectFilter`, `RadioGroupFilter`, `TabsFilter` |
+| Values fetched from an API, not a fixed list | `MultiSelectCollectionFilter` + `useFilterCollection` |
+| Type-ahead over many values | `AutoCompleteFilter` |
+| Date or number ranges | `DateRangeFilter`, `NumberRangeFilter` |
+| Comparison operators (greater than, contains) | `OperatorFilterPicker` + `operatorFilter` |
+| The filter's state object | `idNameArrayFilter`, `stringFilter`, `stringsArrayFilter`, `arrayFilter`, `dateRangeFilter`, `customFilter` |
+| A fixed in-memory option list for a filter | `useStaticListFilterCollection` |
+| Sorting | `Sortable Columns`, `MultiLevelSorting` |
+
+**Ask for several names at once.** `docs`, `types` and `exports` all take a list — `types ComputedQuery OffsetQuery RangeItem`, `exports page form router` — and each call is a full model turn, so five one-name calls cost five turns for one call's worth of answer. `exports` with no argument lists the 31 entry points; that is a one-off orientation, not something to re-run.
+
+**A factory or hook's doc is often empty where its signature should be** — `docs idNameArrayFilter` prints an `## API` heading with nothing under it, because the props table only exists for components. Ask `types idNameArrayFilter` instead and you get the signature: `<T extends { id: string; name: string }>(params?) => ArrayFilterState<T>`. That applies to every `use…` hook and every `…Filter` factory in the table above, and it is the difference between knowing the name and being able to call it.
+
+**A filter must narrow the result.** Declare it in the collection hook's `filters` map and read it inside `fetchData`, so the value reaches the query. Filter UI that renders but never changes the rows is a defect that looks like a feature — and it is the failure mode these components exist to prevent.
+
+## Investigate — opening one record
+
+| Surface | Use when | Built from |
+| --- | --- | --- |
+| **Side panel** | Inspect or lightly edit one record while keeping the filtered list on screen. The V1 default for review dashboards. | WDS `SidePanel` — patterns has no side panel |
+| **Entity page** | Multi-section detail, editing, history, or a link someone can share. | `EntityPage` + `useEntityPage`, reached with `usePatternsNavigate().navigateToEntityPage`, form state from `@wix/patterns/form`. The call itself: [ENTITY_PAGE_TOOLKIT.md](ENTITY_PAGE_TOOLKIT.md) |
+| **Expanded row** | A couple of extra fields, no separate workspace needed. | The collection's own row expansion |
+| **Picker / bulk confirm** | Choosing records, or confirming an action on many. | `PickerModal` + `usePickerModal`, `bulkActionModal` |
+
+A dialog that creates, updates or displays one listed record is **not** a dashboard modal — a create / "add new" form included, since it writes the record. See [DASHBOARD_MODAL.md](../DASHBOARD_MODAL.md). A row the user cannot open is the second most common failure after the missing aggregate.
+
+**Form state on an entity page** comes from `@wix/patterns/form` — `useForm` for the form, `useController` for a single field. That subpath re-exports `@wix/bex-core/form`, which wraps `react-hook-form`, so its API is react-hook-form's and only a handful of its names appear in the patterns docs: `FieldValues`, `ControllerProps` and most of the rest are documented by react-hook-form, not here. `Read <pkgRoot>/dist/dts-bundle/exports/form.d.ts` to see what the subpath actually gives you.
+
+## Act and confirm
+
+| Need | Component |
+| --- | --- |
+| Row actions | `PrimaryActions`, `SecondaryActions`, `More Actions`, `deleteSecondaryAction` |
+| Page-level button | `PrimaryPageButton`, `PrimaryActionButton` |
+| Acting on a multi-row selection | `MultiBulkActionToolbar`, `bulkActionModal` |
+| Immediate feedback, then reconcile | `useOptimisticActions`, `CollectionOptimisticActions` |
+| A banner above the table | `TableTopNotification` |
+
+## The states that are not the happy path
+
+| State | Component |
+| --- | --- |
+| Collection is genuinely empty | `CollectionEmptyState` |
+| Filters or search matched nothing | `CollectionNoResultsState` |
+| Feature needs a paid plan | `CollectionPremiumEmptyState` |
+| Load failed | the collection state's error handling — give the user a way to retry |
+
+Empty and no-results are different messages: one means "add your first record", the other means "loosen the filters". Shipping only the first makes a working filter look broken.
+
+## Export
+
+`ExportButton` (its doc is `ExportTo`) for CSV and similar. Reach for it when the prompt mentions exporting, downloading, or sending records elsewhere.

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

@@ -0,0 +1,73 @@
+# Entity Page Toolkit — calling `useEntityPage`
+
+[COLLECTION_TOOLKIT.md](COLLECTION_TOOLKIT.md) says a row the user cannot open is a defect, and sends you to `EntityPage` + `useEntityPage` to fix it. This file is the call itself.
+
+## The call
+
+```tsx
+import { useEntityPage, EntityPage } from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+
+interface Shift {
+  id?: string;
+  name?: string;
+}
+
+interface ShiftFormFields {
+  name?: string;
+}
+
+const form = useForm<ShiftFormFields>({ defaultValues: { name: '' } });
+
+const state = useEntityPage<Shift, ShiftFormFields>({
+  fetch: () => api.getShift(shiftId).then((entity) => ({ entity })),
+  onSave: ({ widgetsFormData }) =>
+    api
+      .updateShift(shiftId, { ...form.getValues(), ...widgetsFormData })
+      .then((updatedEntity) => ({ updatedEntity })),
+  form,
+  parentPath: '/shifts',
+});
+```
+
+`EntityPage` and `useEntityPage` are **root** exports. `@wix/patterns/page` holds `CollectionPage` and `WidgetsFormProvider` only, so importing the entity page from there is `TS2305: has no exported member` — the collection page and the entity page do not live in the same place. `Read <pkgRoot>/dist/dts-bundle/exports/page.d.ts` to see what that subpath actually gives you.
+
+## Name both generics
+
+`useEntityPage<T, V extends FieldValues = FieldValues>` takes the entity type **and** the form-values type. `V` does not infer from the `form` argument — it falls back to `FieldValues`, and a `useForm<ShiftFormFields>()` then fails to assign with `Type 'UseFormReturn<ShiftFormFields, …>' is not assignable to type 'UseFormReturn<FieldValues>'`. Naming a single generic only works when the form is untyped.
+
+`useEntityPage<any, ShiftFormFields>` makes that error go away and takes the entity type with it — `state.entity` becomes `any`, and every field access below it stops being checked. Name the entity type.
+
+## `onSave` does not hand you the form values
+
+`OnSaveParams` has exactly one key. `widgetsFormData` carries what the **widget** fields contributed — extended fields, tags — not what the user typed into your own fields. Those come from the form you already own:
+
+```tsx
+onSave: ({ widgetsFormData }) => {
+  const values = form.getValues();                  // your fields
+  const { extendedFields, tags } = widgetsFormData; // widget fields
+  …
+};
+```
+
+Reaching for a `values`-shaped key on the `onSave` argument is the usual first guess, and there isn't one.
+
+## The params are a `Pick`
+
+`UseEntityPageParams` picks a fixed set off `EntityPageStateParams` — `fetch`, `onSave`, `saveSuccessToast`, `saveErrorToast`, `deleteAction`, `transformEntityToCollectionItem`, `isNewEntity`, `form`, `parentPageId`, `parentPath`, `parentReferrer`, `schemaSource`. Anything outside that list is an excess-property error on the object literal. `container` is the common guess and is not one of them: the hook calls `useWixPatternsContainer()` itself.
+
+Confirm the shape rather than guessing — the hook's doc has an empty API section, because props tables only exist for components. `Read <pkgRoot>/dist/dts-bundle/index.json`, then `Read` the bundled `.d.ts` for each of `useEntityPage`, `UseEntityPageParams`, and `OnSaveParams` at exactly the `file` path the index gives.
+
+## Around the call
+
+| Step | What owns it |
+| --- | --- |
+| Getting here from the collection page | `usePatternsNavigate()` → `navigateToEntityPage({ path, entity })` |
+| Registering the route | `PatternsReactRoute` inside `PatternsReactRouter` |
+| Form state and field binding | `useForm` / `useController` from `@wix/patterns/form` |
+| Body layout | `EntityPage.Header`, `.MainContent`, `.AdditionalContent`, `.Card` |
+| The fields inside those cards | `@wix/design-system` (`FormField`, `Input`, `Text`) |
+
+`@wix/patterns/form` re-exports `@wix/bex-core/form`, which wraps `react-hook-form` — so `form.getValues()`, `form.reset()` and the rest are react-hook-form's API, documented there rather than in the patterns docs.
+
+A dialog that creates, updates or displays one listed record is **not** a dashboard modal — a create / "add new" form included, since it writes the record. See [DASHBOARD_MODAL.md](../DASHBOARD_MODAL.md).

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

@@ -0,0 +1,52 @@
+# Reading `@wix/patterns` Bundles and Docs
+
+> **Scope.** You are here because a lookup in `dist/dts-bundle/index.json` or
+> `dist/docs/index.json` gave you an entry and you are about to open the file it names. Getting to that index in the first
+> place — resolving the package root, the version floor, the docs lookup, and the rule
+> against browsing `node_modules` by hand — is in
+> [WIX_PATTERNS_DOCS.md](../WIX_PATTERNS_DOCS.md). Nothing here replaces those steps.
+
+## Types the docs don't cover
+
+The docs cover components and props, not the types those props use — `Filter<T>`, `RangeItem<T>`, `CursorQuery`, a `...Props` interface. `Read <pkgRoot>/dist/dts-bundle/index.json`, look up the type name, then `Read <pkgRoot>/dist/dts-bundle/<entry.file>` using exactly the `file` path the index gives — **never reconstruct the path from the name**; bundles are nested one directory per kind (`components/Table.d.ts`, `hooks/useForm.d.ts`, `types/RangeItem.d.ts`, …), so guessing `<Name>.d.ts` at the top level is wrong by construction.
+
+Several of these types (`RangeItem`, `Filter`, `CursorQuery`, the filter factory functions) actually live in `@wix/bex-core` — the bundle already resolves and inlines the real declaration, so you get the full shape with no deep, undeclared `@wix/bex-core/dist/types/...` path to chase. Still always import it from `@wix/patterns`, per the index's `importPath` field, never from wherever the bundle says it's really declared.
+
+That inlining applies to the data shapes you write. State objects you *receive* are a separate case — see the next section.
+
+## A bundle stops where you stop writing code
+
+A bundle carries its own name's declaration plus every shape **you** would write by hand. It deliberately does *not* expand what the library hands you, so two kinds of one-line stub are normal and are answers, not truncation:
+
+```ts
+/**
+ * `TableState` — you receive this, you don't construct it.
+ * Produced by `useTableCollection()` (also `useAmbassadorTable()`, `useTableContext()`).
+ * Look `TableState` up in the bundle index for its own API.
+ */
+declare class TableState<T, F> {
+}
+```
+
+An empty body with a **"Produced by"** note means: call that hook or factory to get one. That is usually the whole answer — `<Table state={...}>` needs `useTableCollection()`, not `TableState`'s internals. If you do need its members (`state.toolbar`, `state.visibleColumns`), it has its own index entry — look the name up and read that bundle, where its body is complete.
+
+A stub saying **"cut here because it has its own bundle"** means the same thing for a shape you *do* write: it wasn't copied in twice, so look the name up and read its own file.
+
+Every bundle fits in a single read; the index's `bytes` field says how big before you open it. So a bundle is never partially shown — if something looks missing, it was cut on purpose and the stub names where to find it.
+
+A handful of names carry `"status": "unreachable"` with a message saying not to import them (the `...BaseProps` interfaces a component's props `extends`). Read those for the props they contribute; don't write an import for them.
+
+## Subpath entry points
+
+`@wix/patterns` is 31 entry points, not one namespace, and `/form` re-exports `@wix/bex-core/form`. To see what's importable from a specific one: `Read <pkgRoot>/dist/dts-bundle/exports/<subpath>.d.ts` directly (`.` is `exports/index.d.ts`; a nested one like `./testkit/backend` is `exports/testkit/backend.d.ts`). This only lists the curated names covered above — a file with nothing in it (a one-line comment) means no curated name lives on that subpath yet, not that the subpath doesn't exist.
+
+## Following cross-references
+
+Docs link to related names as Storybook URLs (`[TableState](./?path=/story/...--tablestate)`) — resolve the link text back to a filename via `dist/docs/index.json`, the same way you found the first doc, and `Read` it if you actually need it. There's no automatic multi-level expansion here; follow only the links you need.
+
+Links to `https://www.docs.wixdesignsystem.com/` are external (Wix Design System) — not part of `@wix/patterns` docs. Likewise, a bundled `.d.ts` that references a deep `@wix/design-system/dist/...` path is pointing at that library's own internals — look the name up via the `wix-design-system` skill's own tool, not by opening the path.
+
+## Tips
+
+- **Compound components** have separate docs per sub-part: `CollectionPage.md`, `CollectionPage.Header.md`, `CollectionPage.Content.md`.
+- **Hook docs** list configuration options as props in the API table.

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

@@ -0,0 +1,184 @@
+# Dashboard UX Success Model
+
+What makes a generated dashboard page actually *succeed* for the person using it. Use this to turn a vague prompt ("help me manage order exceptions") into concrete requirements, and as the checklist before calling a dashboard done.
+
+Ported from the FeatureVibe dashboard product doc.
+
+> **North Star.** A successful dashboard helps a site owner or collaborator **understand what matters, complete the intended task, and trust the result**. It fulfills the user's prompt through a clear workflow, the right presentation, and trustworthy business data.
+
+This file is about *what to build*. For *how* to build it, see [WDS_LAYOUT.md](WDS_LAYOUT.md) for content layout and [DASHBOARD_PAGE.md](../DASHBOARD_PAGE.md) for the `@wix/patterns` → `@wix/design-system` component order — the workflow stages below are user needs, not an excuse to hand-roll shells, tables, or filter bars.
+
+
+## The Success Model
+
+A generated dashboard succeeds across three connected dimensions.
+
+| Success dimension | What must be true |
+|---|---|
+| Workflow success | The dashboard supports a complete journey from understanding to a confirmed outcome. |
+| Presentation success | Information is shown clearly and in the format that best supports the task. |
+| Data success | Information is accurate and consistent, including when it comes from multiple sources. |
+
+
+## The Workflow Journey
+
+The prompt defines the outcome. The stages define the journey from understanding the situation to confirming the result. They are **user needs**, not necessarily separate screens or a rigid sequence.
+
+| Stage | User outcome |
+|---|---|
+| **Understand** | Know the current situation. |
+| **Focus** | Recognize what matters or requires attention. |
+| **Investigate** | Access the details needed to decide. |
+| **Act** | Complete the intended business task. |
+| **Feedback** | See that the action succeeded and the state changed correctly. |
+
+### 1. Understand
+
+**Intent:** Help the user understand the business area this dashboard supports, what the data represents, and how to interpret it.
+
+- Present the most important totals, trends, and status indicators.
+- Make scope, time range, and freshness clear.
+- Distinguish no data, loading, access, connection, and system problems.
+- Connect summaries to underlying items.
+
+**Success:** The user can explain what is happening now.
+
+### 2. Focus
+
+**Intent:** Help the user recognize what matters or requires attention.
+
+- Choose the view that best supports the task.
+- Reduce noise through hierarchy, search, filters, sorting, saved views, and alerts.
+- Explain empty results and offer a useful next step.
+- Make the most important next action clear.
+
+**Success:** The user knows where to direct attention and what to do next.
+
+### 3. Investigate
+
+**Intent:** Give the user enough context to make a confident decision.
+
+- Reveal detail progressively without making users lose their place.
+- Show related information, history, and meaningful connections.
+- Make missing, unmatched, or uncertain information visible.
+
+**Success:** The user can understand why something happened and decide how to respond.
+
+### 4. Act
+
+**Intent:** Let the user complete the intended business task.
+
+- Provide the actions required by the prompt and allowed by permissions.
+- Support individual and bulk actions when both are useful.
+- Make consequences clear and protect against destructive mistakes.
+
+**Success:** The user can complete the task without leaving the workflow or guessing what to do.
+
+### 5. Feedback
+
+**Intent:** Confirm that the action succeeded and the business state changed correctly.
+
+- Provide immediate feedback after an action.
+- Refresh relevant items, summaries, counts, filters, and views.
+- Keep status and history visible when users may need to return later.
+
+**Success:** The user can see the confirmed result everywhere it matters.
+
+
+## The 5 WHATs
+
+How to gain enough context to ensure a complete workflow. Translate each prompt into concrete journey requirements:
+
+- What outcome is the user trying to achieve?
+- What must they understand before acting?
+- What requires deeper investigation?
+- Which actions must be available?
+- What visible result will confirm success?
+
+> **Example:** "Help me manage order exceptions" requires an overview of open issues, ways to focus on urgent cases, enough order context to decide, actions to resolve each issue, and confirmation that resolved items leave the active list.
+
+
+## Presentation Success
+
+Presentation success applies across all five stages. Choose both the right **representation** and the right **interaction surface**, while keeping hierarchy, meaning, and state consistent.
+
+### Choosing the Right View
+
+| View | Use when… | Success looks like… |
+|---|---|---|
+| **Table** | Users compare many records across several attributes. | Records are easy to scan, compare, filter, select, and act on. |
+| **Gallery** | Visual recognition is central. | Images identify items while key status and actions remain visible. |
+| **List** | Items have one dominant identity and limited supporting detail. | Users scan quickly without unnecessary density. |
+| **Kanban** | Work moves through meaningful stages. | Stage, workload, and valid movement are understandable. |
+| **Timeline or calendar** | Time, sequence, or scheduling matters. | Upcoming activity, conflicts, and timing are clear. |
+| **Chart** | The user needs to understand a trend or relationship. | The visualization answers a specific business question. |
+| **Summary metrics** | The user needs a quick health signal. | Metrics clarify current conditions and where to focus. |
+
+- Choose the default view that best supports the primary task.
+- Offer another view only when it provides distinct value.
+- Keep filters, state, and meaning consistent when users change views.
+- Connect summaries and visualizations back to the relevant records.
+
+### Choosing the Right Drill-In
+
+Choose the smallest interface that gives users enough context and room to complete the task. These are defaults, not rigid rules.
+
+| 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. |
+
+Which Wix primitive builds each of these — and which components serve the summaries, filters and empty states named above — is in [Collection Toolkit](COLLECTION_TOOLKIT.md). Patterns has no side panel; that one is WDS.
+
+
+## Data Success
+
+Data success means giving users a complete and trustworthy view of the business. A dashboard may rely on one source or connect related customer, transaction, payment, and operational data.
+
+### Major Data Sources
+
+| Data source | What it provides |
+|---|---|
+| **CMS** | Custom collections, items, references, and custom business records. |
+| **Stores** | Products, variants, categories, inventory, and locations. |
+| **eCommerce** | Carts, checkouts, orders, line items, and fulfillment. |
+| **Bookings** | Services, appointments, classes, courses, staff, availability, and attendance. |
+| **Contacts and Members** | Customer identity, profiles, labels, roles, and audience context. |
+| **Payments and Pricing Plans** | Transactions, refunds, payouts, plans, subscriptions, and renewals. |
+| **Events** | Events, tickets, registrations, guests, and check-ins. |
+| **Other connected sources** | Restaurants, Forms, Invoices, Programs, and external systems. |
+
+### What Must Succeed Across Sources
+
+| Requirement | User outcome |
+|---|---|
+| **Meaningful relationship** | Sources combine around the business item or decision the user cares about. |
+| **Consistent meaning** | Shared concepts use understandable and consistent language. |
+| **Clear gaps** | Missing or unmatched information is visible rather than silently ignored. |
+| **Trusted actions** | Actions update the correct source and the result appears everywhere relevant. |
+| **Right level of combination** | Related items may be combined; useful but distinct sources remain separate. |
+
+> The goal is not to merge everything. Combine sources when the relationship helps users understand or act; otherwise keep them separate but connected.
+
+### Multi-Source Examples
+
+| Single view | Primary record | Connected sources | User outcome |
+|---|---|---|---|
+| **Order exceptions** | eCommerce order | Payments, Contacts, Stores | Resolve unpaid, delayed, or incorrect orders from one queue. |
+| **Booking follow-up** | Booking or appointment | Bookings, Contacts, Payments | Find missed or unpaid appointments and contact the client. |
+
+
+## Evaluation
+
+Rendering is not enough. A successful dashboard passes every check below.
+
+- [ ] **Prompt fulfilled:** The main result requested by the user is delivered.
+- [ ] **Task completion:** The intended task works from entry to confirmed result.
+- [ ] **Presentation fit:** Layout, actions, and empty states make the task easy to understand and complete.
+- [ ] **Trusted data:** All sources and views form one accurate picture of the business.
+- [ ] **Consistent results:** Actions, filters, views, summaries, and details agree.
+- [ ] **Business fit:** The experience matches the user's context, role, and permissions.
+
+> **Final evaluation question.** Does this dashboard give the user a **clear, trustworthy, and effective** way to accomplish what they asked for?