@wix/agent-skills 1.17.0 → 1.18.1

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

@@ -1,32 +1,26 @@
 # Wix Editor React Component Builder
 
-Build Editor React Components for Harmony Editor and Studio2 in Wix CLI
-applications. These components are not supported in other Wix editors.
-
-## Before You Start
-
-Determine whether the request creates a component or edits an existing one.
-Inspect the existing component before changing it.
+Build Editor React Components for Harmony/Studio2 Wix CLI apps only. First
+determine **create vs edit**; for edits, inspect the existing component and
+never re-scaffold.
 
 ## File Contract
 
 Use the Wix CLI scaffold as the source of truth. Do not replace it with a custom
-layout or a hand-written manifest. After applying this workflow, preserve these
-file responsibilities:
+layout or a hand-written manifest. Preserve these file responsibilities:
 
 | File | Ownership | Purpose |
 | --- | --- | --- |
-| `<component-name>.props.ts` | Edit | Export the props type and `defaultProps` from one shared source. |
-| `<component-name>.tsx` | Edit | Implement the component UI and behavior. |
-| `<component-name>.module.css` | Edit | Define scoped component styles. |
-| `component.tsx` | Keep generated | Wire the component and `defaultProps` with `withDefaults`. |
-| `component.preview.tsx` | Usually keep generated | Customize only for editor-specific behavior, such as suppressing autoplay. |
-| `<component-name>.generated.ts` | NEVER edit | Generated manifest consumed by the editor. |
-| `<component-name>.extension.ts` | Edit narrowly | Apply supported partial manifest overrides. |
-
-Supplementary files such as `constants.ts`, hooks, or internal sub-components
-are allowed when the implementation needs them. Keep the scaffolded files and
-their responsibilities intact.
+| `<component-name>.props.ts` | Edit | Props type + `defaultProps` |
+| `<component-name>.tsx` | Edit | Component UI and behavior |
+| `<component-name>.module.css` | Edit | Scoped component styles |
+| `component.tsx` | Keep generated | Wire component and `defaultProps` with `withDefaults` |
+| `component.preview.tsx` | Edit narrowly | Sync preview adapter, one crucial data field, root class |
+| `<component-name>.generated.ts` | NEVER edit | Generated manifest — do not edit |
+| `<component-name>.extension.ts` | Edit narrowly | Supported partial manifest overrides |
+
+Supplementary files (constants, hooks, sub-components) are allowed; keep scaffold
+roles intact.
 
 ## Workflow
 
@@ -36,9 +30,8 @@ their responsibilities intact.
    npx wix generate --params '{"extensionType":"EDITOR_REACT_COMPONENT","name":"ComponentName","folder":"component-name","description":"A brief description"}'
    ```
 
-   The command creates `src/extensions/site/components/<component-name>/` and
-   registers the extension in `src/extensions.ts`. Do not rerun it for an
-   existing component.
+   Creates `src/extensions/site/components/<component-name>/` and registers the
+   extension in `src/extensions.ts`. Do not rerun for an existing component.
 
 2. **Run the dependency preflight.** Verify that all component creation and
    accessibility-review dependencies are installed:
@@ -47,24 +40,24 @@ their responsibilities intact.
    node -e "const fs=require('fs'),path=require('path'),ps=['@wix/react-component-schema','@wix/react-component-utils','@wix/editor-react-types','@babel/parser','@babel/traverse','@babel/types','eslint','eslint-plugin-jsx-a11y','@typescript-eslint/parser','typescript','@types/eslint-plugin-jsx-a11y'];const missing=ps.filter(p=>!(require.resolve.paths(p)||[]).some(d=>fs.existsSync(path.join(d,p,'package.json'))));if(missing.length){console.error('Missing dependencies: '+missing.join(', '));process.exit(1)}" || { d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/yarn.lock" ]; do d="${d%/*}"; done; if [ -f "$d/yarn.lock" ]; then yarn add @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && yarn add -D @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y; else npm install @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && npm install --save-dev @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y; fi; }
    ```
 
-3. **Plan the contract and structure.** Identify content and behavior props,
-   elect the semantic root, identify named inner parts, and decide which design
-   states each part supports. Read the relevant references from the routing
-   table below before writing code.
+3. **Plan the contract and structure.** Identify props, semantic root, named
+   parts, and design states; read routed references below before writing code.
 
-4. **Implement the editable sources.** Preserve the scaffold contract. Keep
-   props/defaults in the props file, component logic in the main TSX file, and
-   static styling in the CSS Module. Do not edit `*.generated.ts`.
+4. **Implement the editable sources.** Preserve the scaffold contract: props in
+   the props file, logic in TSX, styles in the CSS Module. Do not edit
+   `*.generated.ts`.
 
 5. **Run the accessibility review.** Follow
-   [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md): run both bundled
-   scanners, triage their output, complete the manual semantic checklist, fix
-   confirmed issues, and rerun the scanners on changed JSX files.
+   [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md): run scanners,
+   triage output, complete the manual checklist, fix issues, rerun on changed
+   JSX.
 
 6. **Configure the editor extension when required.** For a new component or a
    requested sizing, installation, or manifest change, apply
    [`editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md)
-   to `<component-name>.extension.ts`. Otherwise preserve the existing file.
+   to `<component-name>.extension.ts`. Otherwise leave the file unchanged.
+   Synchronize `requiredDataFields` and `rootClassName` in
+   `component.preview.tsx`.
 
 7. **Generate and validate.** Run:
 
@@ -73,73 +66,71 @@ their responsibilities intact.
    npx tsc --noEmit
    ```
 
-   Run relevant project tests and lint commands when available. Inspect the
-   regenerated manifest; never repair it by hand. Design-state generation needs
-   `@wix/cli` 1.1.210 or newer, and prop-triggered `ElementState` generation
-   needs 1.1.215 or newer. If expected states are absent on an older CLI, report
-   the version constraint and let the user decide whether to upgrade. If the
-   build or manifest command exits with an error, diagnose it with
-   [`editor-react-component/MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md), apply the
-   matching fix, and rerun both commands.
+   Run relevant tests and lint when available. Inspect the regenerated manifest;
+   never repair it by hand. On failure, diagnose with
+   [`editor-react-component/MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md).
 
 8. **Report the result.** Summarize edited files and checks. Call out any
-   unresolved instruction conflict, missing dependency, unsupported CLI
-   version, or check that could not run.
+   unresolved conflict, missing dependency, unsupported CLI version, or check
+   that could not run.
 
 ## Reference Policy
 
-Read every reference required for the current scope. Read an optional reference
-only when its trigger applies; when it does, that reference becomes required.
-Apply every matching row; do not load the entire reference set by default.
+- Read **only** matching required + triggered optional rows; optional triggers
+  become required when they match.
+- References refine the active step; they do not restart workflow or expand scope.
+- Never re-scaffold an existing component or edit `*.generated.ts`.
 
-References refine the active workflow step; they do not restart the workflow or
-expand the user's requested scope. `SKILL.md` is the only reference router;
-reference files are self-contained leaves and do not route to other references.
-For an existing component, preserve out-of-scope public props, styling,
-extension configuration, and supporting files. Never re-scaffold an existing
-component or edit `*.generated.ts` as a reference-driven fix.
+`SKILL.md` is the only reference router; reference files are self-contained
+leaves. For existing components, preserve out-of-scope public props, styling,
+extension configuration, and supporting files.
 
 ### Required References
 
 | Scope | Required references |
 | --- | --- |
-| Creating a component | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), and [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
-| Editing React or JSX | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md) and [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) |
-| Changing the public contract, semantic root, or named parts | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), and [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) |
-| Creating or changing an item array where only one body is visible | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), and [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Creating a component | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md), [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
+| Editing React or JSX | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) |
+| Changing public contract, semantic root, or named parts | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) |
+| Changing public data props or elected root global class | [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
+| Item array where only one body is visible | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
 | Creating or changing CSS | [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md) |
-| Changing the root direction contract, direction-sensitive behavior, or a `ReactNode` slot | [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) |
-| Changing sizing, installation, or manifest overrides | [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
+| Root direction contract, direction-sensitive behavior, or `ReactNode` slot | [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) |
+| Sizing, installation, or manifest overrides | [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
 
 ### Optional References
 
 | Trigger | Read |
 | --- | --- |
-| An interactive or selectable part is created or changed—for example a button, link, input, tab, accordion trigger, or carousel control—or a custom state is added | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
-| Public event callbacks are added or changed | [`FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) |
-| Browser APIs, effects, or time-dependent output are introduced | [`SSR.md`](editor-react-component/SSR.md) |
+| Interactive/selectable part or custom state | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Public event callbacks added or changed | [`FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) |
+| Browser APIs, effects, or time-dependent output | [`SSR.md`](editor-react-component/SSR.md) |
+| Non-established CSS feature or DOM API, or user asks for one by name | [`BROWSER-SUPPORT.md`](editor-react-component/BROWSER-SUPPORT.md) |
 | `npx wix build` or manifest generation exits with an error | [`MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md) |
-| Primary content is playable, looped, or autoplaying | [`ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md) and [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
-| Runtime site pages, URLs, JavaScript direction, or reduced-motion context is needed | [`SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) |
-| Non-animation behavior must differ in editor design mode | [`SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) and [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
-| The prompt explicitly requests a branded, themed, or brand-aware component | [`BRANDED-COMPONENTS.md`](editor-react-component/BRANDED-COMPONENTS.md) |
+| Animation, video, carousel, or other playable/looped/autoplaying content | [`ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
+| Site/runtime/editor context hooks needed | [`SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) (+ [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) when design-mode behavior differs) |
+| Branded, themed, or brand-aware component requested | [`BRANDED-COMPONENTS.md`](editor-react-component/BRANDED-COMPONENTS.md) |
 
-## Core Invariants
+## Non-Negotiables
 
-- Use React 18-compatible APIs; do not assume React 19 runtime features.
+- React 18 only; do not assume React 19 runtime features.
 - Include typed `id`, `className`, `direction`, and `a11y` support.
-- Apply `dir={direction}` and the unconditional fallback-direction class to the
-  elected root. Use logical CSS properties for direction-sensitive layout.
-- Keep render output deterministic and avoid browser globals during render.
-- Route ARIA through the typed `a11y` contract; do not add one-off ARIA props.
-- Give every named inner part a global class, a CSS Module class, and a matching
-  `elementProps` entry. The elected root uses top-level props instead.
-- Pair each eligible native editor design-state selector with its
-  editor-injected global modifier. Keep a non-input control's keyboard-only
-  `:focus-visible` indicator standalone unless editable focus styling is
-  explicitly requested. Toggle custom global state classes from data.
-- For an item array where only one body is visible, give every item a `name`,
-  use `ActiveItemIndex<'arrayPropName'>`, render every body, and hide inactive
-  bodies accessibly.
-- If primary content autoplays or loops, provide an accessible play/pause
-  control, honor reduced motion, and suppress autoplay in editor design mode.
+- Elected root: `dir={direction}`, fallback-direction class, logical CSS for
+  direction-sensitive layout.
+- Deterministic render; no browser globals during render.
+- Explicit foreground colors need a known contrasting background; transparent
+  roots inherit from the host.
+- Baseline Widely Available CSS/DOM only, or supported fallbacks.
+- Route ARIA through `a11y`; no one-off ARIA props.
+- Named parts: global class, module class, and `elementProps` (root uses
+  top-level props).
+- Native design states: pair selectors with injected modifiers; keep non-input
+  `:focus-visible` standalone unless editable focus is requested; toggle custom
+  state classes from data.
+- Single-visible-body arrays: `name` per item, `ActiveItemIndex<'prop'>`, render
+  all bodies, hide inactive accessibly.
+- Autoplay/loop: play/pause control, honor reduced motion, suppress autoplay in
+  editor design mode.
+- `component.preview.tsx`: keep `withDefaults` and `withFallbackPlaceholder`,
+  wrap the preview adapter when present, one crucial `requiredDataFields`
+  entry, and `rootClassName` matching the root global class.

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

@@ -344,6 +344,18 @@ const wixClient = createClient({ modules: { items, products } });
 await wixClient.items.query(...); // Wrong — API surface differs through client
 ```
 
+### Identity of SDK Calls in Site Plugins
+
+A plugin runs as the **site visitor or member**, never as the app — see [Identity and Elevation Requirement](../SKILL.md#identity-and-elevation-requirement) before routing any SDK call out to a backend endpoint.
+
+The three calls above are correct exactly as written, and each for a different reason:
+
+| Call | Why it works directly |
+| --- | --- |
+| `items.query(...)` | Wix Data enforces the collection's `dataPermissions` per caller — the scaffolded default reads as `ANYONE`. See [Permissions](DATA_COLLECTION.md#permissions) |
+| `currentCartV2.getCurrentCart()` | Resolves the cart from the caller's session. Elevating it would return the app's cart, not the visitor's |
+| `products.queryProducts()` | Catalog base fields are public. `MERCHANT_DATA` and non-visible products are withheld unless the app holds `SCOPE.STORES.PRODUCT_READ_ADMIN` — don't request them from a plugin |
+
 ### Performance Considerations
 
 - Keep bundle size small - plugins load on user-facing pages

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.