@wix/agent-skills 1.16.1 → 1.16.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.16.1",
+  "version": "1.16.3",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-app/SKILL.md

@@ -16,16 +16,16 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 
 - [ ] **Step 1:** Determined extension type(s) needed
   - [ ] Asked clarifying questions if requirements were unclear
-  - [ ] **🛑 Auto-Patterns Gate (MANDATORY):** If the use case is a single-collection CRUD admin page (table/grid + entity form), you MUST use [AUTO_PATTERNS_DASHBOARD.md](references/AUTO_PATTERNS_DASHBOARD.md). Auto-patterns is the DEFAULT; custom Dashboard Pages are the opt-out. Only fall back to Dashboard Page if a disqualifier applies: multi-collection joins, custom business logic, embedded script configuration, external API integrations, or the user explicitly requested a custom React page.
-  - [ ] **🛑 Iteration Gate (MANDATORY):** Before editing ANY file under `src/extensions/dashboard/pages/<page>/`, check for a sibling `patterns.json`. If it exists, this is an auto-patterns page — you MUST follow [AUTO_PATTERNS_DASHBOARD.md](references/AUTO_PATTERNS_DASHBOARD.md) Part B and use the override topic-index (banners → `custom-slots-override.md`, header → `custom-header-override.md`, actions → `custom-actions-override.md`, columns → `custom-columns-override.md`, sections → `custom-sections-override.md`). Do NOT edit the page component (`<page-name>.tsx`) to add UI elements directly.
   - [ ] Checked for implicit Data Collection need — unless user provided a collection ID directly (see [Data Collection Inference](#data-collection-inference))
   - [ ] Obtained app namespace if Data Collection extension is being created
   - [ ] Determined full scoped collection IDs if Data Collection extension is being created (see [Collection ID Coordination](#collection-id-coordination))
   - [ ] Explained recommendation with reasoning
 - [ ] **Step 2:** Read extension reference file(s) for the chosen type(s) and the project-wide [CODE_QUALITY.md](references/CODE_QUALITY.md)
+  - [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md), then confirm `@wix/patterns` is in the project's `package.json` (install it if absent) and enumerate the real component list with `cat node_modules/@wix/patterns/dist/docs/index.json`. Do this BEFORE writing any JSX. You cannot apply [Component Selection Order](#component-selection-order) without the component list in front of you — skipping this step is why a page ends up built entirely from WDS.
 - [ ] **Step 3:** Checked API references; used MCP discovery only for gaps
 - [ ] **Step 4a:** Scaffolded each CLI-supported extension via `wix generate --params`
 - [ ] **Step 4b:** Filled in business logic in the generated files
+  - [ ] **🛑 Component Selection Gate (MANDATORY, dashboard UI only):** For every UI element on a Dashboard Page, resolved it against `@wix/patterns` BEFORE reaching for `@wix/design-system` — and never hand-rolled a component either library already provides. See [Component Selection Order](#component-selection-order).
   - [ ] Invoked `wix-design-system` skill ONLY before editing the first `.tsx`/`.jsx` file that imports `@wix/design-system`. Skip for backend-only or data-only extensions.
   - [ ] WDS: imported `@wix/design-system/styles.global.css` in the main component entry file (`page.tsx`, modal `.tsx`, etc.) — not child/tab/helper files.
 - [ ] **Step 5:** Ran validation (see [Validation](#validation))
@@ -48,8 +48,9 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 | Using MCP discovery without checking refs   | Check reference files first                    |
 | Reporting done without validation           | Always run validation at the end               |
 | Letting manual action items get buried      | Aggregate all manual steps at the very end     |
-| Writing custom React for single-collection CRUD when auto-patterns applies | Default to [AUTO_PATTERNS_DASHBOARD.md](references/AUTO_PATTERNS_DASHBOARD.md) for CRUD admin pages |
-| Editing the page component (`<page-name>.tsx`) to add UI (banners, headers, custom actions, slots, sections) when `patterns.json` exists | Use the matching `custom-*-override.md` from [AUTO_PATTERNS_DASHBOARD.md](references/AUTO_PATTERNS_DASHBOARD.md) Part B |
+| Building a dashboard page's collection UI (table, grid, filters, sort, bulk actions, page header) out of raw WDS or hand-written React | Use the `@wix/patterns` equivalent — it exists (see [Component Selection Order](#component-selection-order)) |
+| Guessing a `@wix/patterns` or WDS component/prop name from memory | Look it up: patterns docs in `node_modules/@wix/patterns/dist/docs/`, WDS via the `wix-design-system` skill |
+| Hand-rolling a component (empty state, badge, tooltip, pagination) that one of the two libraries already ships | Search patterns first, then WDS; only build custom when both genuinely lack it |
 
 ---
 
@@ -68,8 +69,7 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 
 3. **Where will it appear?**
    - Dashboard sidebar/page →
-     - **Single-collection CRUD admin (default, MANDATORY):** [Auto Patterns Dashboard](references/AUTO_PATTERNS_DASHBOARD.md) — declarative `patterns.json`, faster to author, iterate by editing JSON, no React rewrite.
-     - Custom logic / multi-collection / embedded scripts / external APIs: Dashboard Page
+     - Full admin screen: Dashboard Page — UI built with `@wix/patterns` + `@wix/design-system` (see [Component Selection Order](#component-selection-order))
      - Popup/form: Dashboard Modal
    - Existing Wix app dashboard (widget) → Dashboard Plugin
    - Existing Wix app dashboard (menu item) → Dashboard Menu Plugin
@@ -82,12 +82,75 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 
 ## Decision Flow (Not sure?)
 
-- **Admin:** Single-collection CRUD admin page? → **Auto Patterns Dashboard (DEFAULT)**. Custom React page (multi-collection / custom logic / embedded scripts / external APIs / explicit user request)? → Dashboard Page. Need popup/form? → Dashboard Modal. Extending Wix app dashboard with a visual widget? → Dashboard Plugin. Adding a menu item to a Wix app dashboard's more-actions or bulk-actions menu? → Dashboard Menu Plugin. **Modal constraint:** Dashboard Pages cannot use `<Modal />`; use a separate Dashboard Modal extension and `dashboard.openModal()`.
+- **Admin:** Admin screen in the site owner's dashboard? → Dashboard Page — build its UI with `@wix/patterns` first, `@wix/design-system` for whatever patterns does not cover (see [Component Selection Order](#component-selection-order)). Need popup/form? → Dashboard Modal. Extending Wix app dashboard with a visual widget? → Dashboard Plugin. Adding a menu item to a Wix app dashboard's more-actions or bulk-actions menu? → Dashboard Menu Plugin. **Modal constraint:** Dashboard Pages cannot use `<Modal />`; use a separate Dashboard Modal extension and `dashboard.openModal()`.
 - **Backend:** During business flow (checkout/shipping/tax)? → Service Plugin. Exposing tools to the Wix AI assistant? → App Tools (requires both `APP_TOOLS` declaration + `TOOLS_PROVIDER_CONFIG` handler — see [APP_TOOLS.md](references/APP_TOOLS.md)). After event (webhooks/sync)? → Backend Event Extension. Custom HTTP endpoints? → Backend API. Need CMS collections for app data? → Data Collection.
 - **Site:** User places anywhere (standalone)? → custom element widget. Editor React component with editor manifest (styling, content, elements)? → Editor React component. Fixed slot on Wix app page? → Site Plugin. Scripts/analytics only? → Embedded Script.
 
 ---
 
+## Component Selection Order
+
+Dashboard pages at Wix are built from two libraries. For **every** UI element, resolve in this order and stop at the first hit. Never skip a step, and never decide a component is missing from memory — check.
+
+### 1. `@wix/patterns` — page structure and data collections
+
+Patterns owns the page shell and everything collection-shaped. These concepts are patterns' territory — if you need one, look it up there first rather than assembling it from WDS parts:
+
+| Need | Look for |
+| --- | --- |
+| Page shell, header, content area, sticky footer | `CollectionPage`, `EntityPage`, `SettingsPage` (+ their `.Header` / `.Content` sub-parts) |
+| Table, grid, table↔grid switch, folder views | `Table`, `Grid`, `TableGridSwitch`, `TableFolders`, `GridFolders` |
+| Collection state — paging, sorting, selection, loading | `useTableCollection()` and its sibling hooks (one per collection type) |
+| Filters, search, sorting, view presets/tabs | the collection's filter and view APIs |
+| Row actions, bulk actions, drag-and-drop | the collection's feature APIs |
+| Multiple pages inside one extension | `PatternsReactRouter`, `PatternsReactRoute`, `usePatternsNavigate` |
+| **Add / edit / view one item from a collection** | `EntityPage` + `useEntityPage` (fetch + save + validation), reached with `usePatternsNavigate().navigateToEntityPage`. Form state via `useForm` / `useController` from `@wix/patterns/form`. **Not** a dashboard modal — see [Entity create and edit](#entity-create-and-edit) |
+| Overlays tied to a collection (item picker, bulk-action confirm) | `PickerModal` / `usePickerModal`, `bulkActionModal` |
+
+**Confirm every name and prop against the generated docs — do not guess:**
+
+```bash
+cat node_modules/@wix/patterns/dist/docs/index.json
+```
+
+If that path does not exist, `@wix/patterns` is missing or too old — add it (`^1.367.0` or later ships `dist/docs/`) and re-read. **A missing docs folder is not a reason to fall through to step 2**; it means the lookup has not happened yet. Falling through here is the single most common way a dashboard page ends up built entirely from WDS.
+
+`index.json` maps component name → doc file + category; doc filenames match component names (`Table.md`, `useTableCollection.md`). Full lookup workflow, provider selection, and the provider/page separation rule: [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md).
+
+### 2. `@wix/design-system` — everything inside the shell
+
+The leaf-level UI patterns does not own: inputs, buttons, form fields, text, layout primitives, cards, badges, tooltips, toasts, icons. Pick the component by lookup, not recall — invoke the **`wix-design-system` skill**, whose bundled helper reads the installed package:
+
+```bash
+node <wix-design-system-skill-dir>/scripts/wds.cjs search <keyword>
+node <wix-design-system-skill-dir>/scripts/wds.cjs component <Name>
+```
+
+### 3. Custom React — only after both came back empty
+
+Compose from WDS layout primitives (`Box`, `Card`, `Text`). Do not add a third UI dependency, and do not restyle patterns or WDS internals.
+
+### Overlaps and scope
+
+- When both libraries ship the same concept (page header, page container), the **patterns** one wins inside a patterns page — it is the piece wired into the shell's layout and collection state. Use the WDS equivalent only outside a patterns page shell.
+- **Patterns has its own overlays.** `PickerModal` / `usePickerModal` and `bulkActionModal` cover collection-related overlays. "It's a modal" is not a reason to leave patterns.
+- **Dashboard Plugins** render outside a patterns page shell, so WDS is the default there. Patterns collection components still apply when such a surface displays a data collection.
+
+### Entity create and edit
+
+**Adding, editing, or viewing a single item from a collection page is an `EntityPage` — not a Dashboard Modal.** This is the most common place the selection order gets dropped: the collection gets built correctly with patterns, then the "add item" flow is hand-built as a WDS form in a modal.
+
+The documented flow:
+
+1. From the collection page's action cell or primary action, call `navigateToEntityPage({ path, entity })` from `usePatternsNavigate()`. (The patterns docs give this exact use case — "navigate to an entity page on an action cell click on a collection page" — and it renders the entity header immediately, before the fetch resolves.)
+2. Register the route with `PatternsReactRoute` inside `PatternsReactRouter`.
+3. In the entity page, `useEntityPage({ fetch, onSave })` owns fetching, saving, validation, dirty state, loading skeletons, and error states. Form state comes from `useForm` / `useController` in `@wix/patterns/form`.
+4. Compose the body from `EntityPage.Header`, `EntityPage.MainContent`, `EntityPage.AdditionalContent`, and `EntityPage.Card`. **WDS goes inside those cards** — `FormField`, `Input`, `Text` for the individual fields.
+
+Use a Dashboard Modal only for dialogs that are genuinely not entity editing: a delete confirmation, a short prompt, an unrelated popup. Reach for it because the interaction is a true dialog, never because "the form should open in a modal."
+
+---
+
 ## Extension Types Reference Table
 
 | Extension Type | Category | `extensionType` (for `wix generate --params`) | Reference File |
@@ -130,7 +193,7 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 | App Identifiers (Namespace, Code ID) | [APP_IDENTIFIERS.md](references/APP_IDENTIFIERS.md) |
 | Wix Stores Versioning (V1/V3) | [STORES_VERSIONING.md](references/STORES_VERSIONING.md) |
 | Official Documentation Links | [DOCUMENTATION.md](references/DOCUMENTATION.md) |
-| Auto-patterns Dashboard Pages | [AUTO_PATTERNS_DASHBOARD.md](references/AUTO_PATTERNS_DASHBOARD.md) |
+| Wix Patterns Dashboard Pages | [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md) |
 
 ---
 
@@ -358,6 +421,7 @@ Stop and report errors if any step fails. Check `.wix/debug.log` on failures.
 - **maxResults: 5** for all MCP SDK searches
 - **ReadFullDocsMethodSchema** for SDK method schemas; **ReadFullDocsArticle** for prose guides only
 - **Invoke wix-design-system** first when using WDS (prevents import errors)
+- **Patterns before WDS** for dashboard page UI — check `@wix/patterns` docs before building anything collection- or page-shaped (see [Component Selection Order](#component-selection-order))
 
 ## Documentation
 

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

@@ -26,7 +26,6 @@ Applies to all generated code across every Wix CLI app extension type. Each per-
 
 - If a generated file would exceed ~300 lines, split it into multiple smaller files with imports. Each component or function should stay ~50–100 lines.
 - Extract utilities/helpers into separate files; put types/interfaces into dedicated type files.
-- **Exception — auto-patterns override files** (column / action / slot / section / component / header overrides) ALWAYS live in their own file under `components/<type>/` with a `use*` hook, **regardless of file size**. This is a structural requirement of the override-registration model, not a size-based split — the ~300-line rule does NOT license inlining an override into the page component, even for a single small one. See [AUTO_PATTERNS_DASHBOARD.md](AUTO_PATTERNS_DASHBOARD.md).
 
 ## Error Handling
 

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

@@ -3,6 +3,8 @@
 
 Dashboard modals are popup dialogs triggered from dashboard pages or plugins. They use the Dashboard SDK for lifecycle control via `openModal()` and `closeModal()`.
 
+> **🛑 Scope — genuine dialogs only.** Use a dashboard modal for delete/discard confirmations, short prompts, and dialogs unrelated to editing a collection item. **Adding, editing, or viewing a collection item is NOT a modal** — that is a `@wix/patterns` `EntityPage` reached via `usePatternsNavigate().navigateToEntityPage`. See [Entity create and edit](../SKILL.md#entity-create-and-edit) and [WIX_PATTERNS_DOCS.md](WIX_PATTERNS_DOCS.md).
+
 ## Scaffold
 
 Use `wix generate --params` with all required fields:
@@ -106,29 +108,34 @@ export default {
 
 ## Real-World Example
 
-End-to-end edit-item flow. The scaffolded `<modal>.tsx` already wires up `CustomModalLayout` — the unique parts are on the opener side, in `observeState`, and in the save handler.
+End-to-end delete-confirmation flow. The scaffolded `<modal>.tsx` already wires up `CustomModalLayout` — the unique parts are on the opener side, in `observeState`, and in the confirm handler.
 
 ```typescript
-// Dashboard Page: open the modal with the item to edit
-const handleEdit = (item: Item) => {
-  dashboard.openModal({
-    modalId: "edit-item-modal-guid",
-    params: { item }, // objects are passed directly via params
+// Dashboard Page: open the modal with the item to delete, act on the result
+const handleDelete = async (item: Item) => {
+  const { modalClosed } = dashboard.openModal({
+    modalId: "confirm-delete-modal-guid",
+    params: { itemId: item.id, itemName: item.name }, // objects are passed directly via params
   });
+  // `modalClosed` resolves as `Serializable` (a union) and `openModal` takes no type
+  // parameter, so narrow it to the shape this modal's own close payload uses.
+  const result = (await modalClosed) as { confirmed?: boolean } | undefined;
+  if (result?.confirmed) {
+    // ...your delete logic + collection refresh...
+  }
 };
 
-// Modal: read params, save, toast, close
-const [formData, setFormData] = useState<Item | null>(null);
+// Modal: read params, confirm or cancel
+const [itemName, setItemName] = useState<string | null>(null);
 
 useEffect(() => {
   dashboard.observeState((state) => {
-    if (state.item) setFormData(state.item);
+    if (state.itemName) setItemName(state.itemName);
   });
 }, []);
 
-const handleSave = async () => {
-  // ...your save logic...
-  dashboard.showToast({ message: "Saved!", type: "success" });
-  dashboard.closeModal();
-};
+const handleConfirm = () => dashboard.closeModal({ confirmed: true });
+const handleCancel = () => dashboard.closeModal({ confirmed: false });
 ```
+
+(Editing the item itself would be an `EntityPage`, not a modal — see the scope note at the top.)

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

@@ -1,11 +1,17 @@
-
 # Wix Dashboard Page Builder
 
-> **🛑 STOP — Read this first.**
-> If this page is a single-collection CRUD admin (table/grid view + entity form, no multi-collection joins, no custom business logic, no embedded scripts, no external APIs), STOP and use [AUTO_PATTERNS_DASHBOARD.md](AUTO_PATTERNS_DASHBOARD.md) instead. Auto-patterns is the default; this file documents the custom React variant for cases auto-patterns cannot handle, or when the user explicitly requested a custom React page.
-
 Dashboard pages appear in the site owner's Wix dashboard and enable site administrators to manage data, configure settings, and perform admin tasks.
 
+## UI Libraries — Read Before Writing Any JSX
+
+At Wix, dashboard pages are built from `@wix/patterns` and `@wix/design-system`, in that order of preference:
+
+1. **`@wix/patterns` first** — page shells (`CollectionPage`, `EntityPage`, `SettingsPage`), tables/grids, collection state hooks, filters, sorting, row and bulk actions, in-extension routing. Look every name up in the generated docs at `node_modules/@wix/patterns/dist/docs/` (start with `index.json`). See [WIX_PATTERNS_DOCS.md](WIX_PATTERNS_DOCS.md).
+2. **`@wix/design-system` second** — the leaf UI inside that shell (inputs, buttons, form fields, text, layout, cards, badges, icons). Choose components via the `wix-design-system` skill.
+3. **Custom React last** — only when neither library has it.
+
+Do not hand-write React for anything either library already provides, and do not decide a component is missing without checking. Full rule: [SKILL.md → Component Selection Order](../SKILL.md#component-selection-order).
+
 ## Scaffold
 
 Use `wix generate --params` with all required fields:
@@ -21,6 +27,14 @@ wix generate --params '{"extensionType":"DASHBOARD_PAGE","title":"<title>","rout
 
 The CLI generates the folder, `page.tsx`, the builder file, the UUID, and the `src/extensions.ts` registration. After scaffolding, implement the page UI in the generated `page.tsx`.
 
+**Then, before writing UI:** confirm `@wix/patterns` is a dependency and its docs are present.
+
+```bash
+ls node_modules/@wix/patterns/dist/docs/index.json
+```
+
+If it's missing, add the package (`^1.367.0` or later — earlier versions don't ship `dist/docs/`) and install. Without this, the patterns lookup in step 1 of [Component Selection Order](../SKILL.md#component-selection-order) silently finds nothing and the page gets built entirely from WDS.
+
 ## Capabilities
 
 ### Data Operations (Wix Data SDK)
@@ -54,14 +68,16 @@ See [Dashboard API Reference](dashboard-page/DASHBOARD_API.md) for complete docu
 
 **CRITICAL: Using Modals in Dashboard Pages**
 
-When you need to display popup forms, confirmations, detail views, or any dialog overlays from a dashboard page, you **MUST** use dashboard modals, not regular React modals or WDS Modal components.
+Dashboard Pages cannot use `<Modal />`. When you need a true dialog overlay, you **MUST** use a dashboard modal extension — not a React modal and not the WDS `Modal` component.
 
-- **Use dashboard modals** for: edit forms, delete confirmations, detail views, settings dialogs, any popup content
+- **Use dashboard modals** for: delete/discard confirmations, short prompts, and dialogs unrelated to editing a collection item
 - **Do NOT use** WDS `Modal` component or custom React modal implementations
 - **See [Dashboard Modal reference](DASHBOARD_MODAL.md)** for complete implementation guide
 
 Dashboard modals are opened using `dashboard.openModal()` and provide proper integration with the dashboard lifecycle, state management, and navigation.
 
+> **🛑 Exception — adding, editing, or viewing a collection item is NOT a modal.** That is an `EntityPage` from `@wix/patterns`, reached via `usePatternsNavigate().navigateToEntityPage`, with `useEntityPage` owning fetch/save/validation and `@wix/patterns/form` owning form state. Do not hand-build the entity form as a WDS form inside a dashboard modal — that is the single most common way the patterns-first rule gets dropped after the table is already correct. See [Entity create and edit](../SKILL.md#entity-create-and-edit) and [WIX_PATTERNS_DOCS.md](WIX_PATTERNS_DOCS.md).
+
 **Ecom Navigation:** See [Ecom Navigation Reference](dashboard-page/ECOM_NAVIGATION.md) for ecom-specific navigation helpers.
 
 ### Embedded Script Configuration API
@@ -77,29 +93,31 @@ When building a dashboard page to configure an embedded script, see [Dynamic Par
 
 ## Examples
 
+Each output below names the library that owns each part. Confirm every patterns component and prop in `node_modules/@wix/patterns/dist/docs/` before use — these examples name the shape, not a verified API.
+
 ### Data Management Table
 
 **Request:** "Create a dashboard page to manage blog posts"
 
-**Output:** Page with table displaying posts, search toolbar, add/edit/delete actions, empty state.
+**Output:** A `@wix/patterns` `CollectionPage` shell wrapping a `Table` driven by a collection state hook (`useTableCollection`), with the search, add/edit/delete row actions, and empty state supplied by the collection's own APIs. Add and edit navigate to an `EntityPage` (`navigateToEntityPage` + `useEntityPage`). WDS only for the leaf UI inside cells and the fields inside the entity page's cards. The provider lives in a parent component, in a separate file from the hook call.
 
 ### Settings Form
 
 **Request:** "Build a settings page for notification preferences"
 
-**Output:** Page with form fields, save button with toast confirmation, unsaved changes warning.
+**Output:** A `@wix/patterns` `SettingsPage` shell. WDS form fields inside it (`FormField`, `Input`, `ToggleSwitch`), save button with `dashboard.showToast()` confirmation, and `dashboard.onBeforeUnload()` for the unsaved-changes warning. No collection here, so no table hook.
 
 ### Order Management
 
 **Request:** "Create an admin panel for customer orders"
 
-**Output:** Page with orders table, status badges, filters, detail dashboard modal (using [Dashboard Modal reference](DASHBOARD_MODAL.md)), status update actions.
+**Output:** A `@wix/patterns` `CollectionPage` + `Table`, with filters, sorting, and row actions from the collection APIs — **not** a hand-built WDS filter bar. Status badges are WDS leaf UI inside a cell. Viewing or editing an order opens an `EntityPage` via `usePatternsNavigate().navigateToEntityPage` — not a modal (see [Entity create and edit](../SKILL.md#entity-create-and-edit)). A Dashboard Modal appears only for the delete confirmation.
 
 ### Embedded Script Configuration
 
 **Request:** "Create a settings page for the coupon popup embedded script"
 
-**Output:** Page with form fields for popup headline, coupon code, minimum cart value, and enable toggle. Uses `embeddedScripts` API to load/save parameters.
+**Output:** A `@wix/patterns` `SettingsPage` shell with WDS form fields for popup headline, coupon code, minimum cart value, and enable toggle. Uses `embeddedScripts` API to load/save parameters.
 
 ```typescript
 // Key pattern for embedded script configuration pages
@@ -140,178 +158,6 @@ When an API specification is provided, you can make API calls to those endpoints
 
 ## Layout Guidelines
 
-Layout determines how users interact with your dashboard content. It establishes the structure, hierarchy, and rhythm of your dashboard page, contributing to the overall coherence and user experience. By making mindful and calculated choices in how you organize your content, users can move around more smoothly, saving time and frustration when completing tasks.
-
-### Design Principles
-
-To create dashboard pages optimized for user experience, follow these design principles:
-
-1. **Consistent:** Maintain repetitive layouts and content patterns for intuitive and easy-to-read pages.
-2. **Inclusive:** Create layouts and content that adapt well to various screen sizes.
-3. **Balanced:** Emphasize the priority of regions and content elements through deliberate management of size and white space.
-4. **Connected:** Minimize the distance between related regions or content elements to enhance cohesion and navigation.
-
-
-### Screen Size
-
-Dashboard pages are designed to accommodate various screen sizes rather than being tailored to one specific resolution. The primary content should be at the top of the page to ensure users immediately understand the purpose of the page.
-
-> **Note:** Content displayed in the top 600 pixels of the page will be visible for the majority of users.
-
-
-### Base Unit
-
-The base unit establishes the increment by which all elements and measurements are multiplied. This practice ensures consistency in the spacing and sizing of design elements.
-
-> **Note:** The design system is based on a 6px unit.
-
-The layout grid, spacing tokens, and nearly all visual elements and sizes adhere to multiples of six (6, 12, 18, 24, etc.), with only occasional exceptions.
-
-| TOKEN | SIZE | USE FOR |
-|-------|------|---------|
-| SP1 | 6px | Spacing between components |
-| SP2 | 12px | Spacing between components |
-| SP3 | 18px | Spacing between components |
-| SP4 | 24px | Spacing between components, layout spacing |
-| SP5 | 30px | Layout spacing |
-| SP6 | 36px | Layout spacing |
-| SP7 | 42px | Layout spacing |
-| SP8 | 48px | Layout spacing |
-| SP10 | 54px | Layout spacing |
-| SP11 | 60px | Layout spacing |
-
-
-### Layout Structure
-
-To best design the layout for your app, understand:
-
-1. The core frame of the app (Application frame)
-2. The placement and alignment of each segment within the grid layout (Grid layout)
-3. The content to appear in the grid (Common layouts)
-
-#### Application Frame
-
-The dashboard app frame is used by the majority of Wix applications settings. Dashboard pages consist of 4 areas:
-
-| AREA | USAGE |
-|------|-------|
-| 1. Global navigation (top bar) | General navigation at the top of a page which allows users to navigate between different environments. Full width container with a fixed height of 48px. |
-| 2. Sidebar navigation | Local navigation of an environment. Container with a fixed width of 228px. |
-| 3. Content area | Page content area with a width that's adaptive to screen size. |
-| 4. Side panel (optional) | An optional panel that shows additional actions or content associated with the content of a page. Fixed width of 420px. Can either overlay the main content area or push it from the right side. |
-
-**Side Panel Guidelines:**
-- Let the side panel overlay main content when it contains supplementary actions or settings, such as data filters
-- Push main content with the side panel when users must see the full context to continue
-
-
-#### Grid Layout
-
-The system uses a fluid grid layout with a fixed maximum width. It uses columns that scale and resize the content accordingly.
-
-The grid is constructed from 3 elements:
-- **Columns** - The design system uses a 12-column grid. Column width is fluid and changes according to the page width.
-- **Gutters** - The gaps between the columns. Gutter width has a fixed value of 24px.
-- **Margins** - By default, a page's content area has 48px side margins and a 48px bottom margin.
-
-**Grid Specifications:**
-- Minimum content area width: 864 pixels (each grid column is 50px wide)
-- Maximum content area width: 1248px (each column is 82px wide)
-- Wider screens maintain 1248px content width with side margins stretching to center content
-- Use 24px gap between cards both vertically and horizontally
-
-
-### Common Layouts
-
-Page layouts can be divided by intention into the following types:
-
-#### 1. Form Layouts
-
-Forms are pages that allow users to fill in data or edit existing data. Two variations:
-
-- **2/3 layout with optional sidebar (8/4 column split)** - Provides flexibility to expose primary and secondary content at the same time
-- **Full width (12 columns)** - Supports advanced product needs with complex structures
-
-Both form page layouts include mandatory **Save** and **Cancel** actions in the header and footer areas.
-
-**2/3 Layout Best Practices:**
-- Use to expose primary and secondary content at the same time
-- Keep the form easy to scan and comprehend
-- Display a live content preview on the side (widget can be sticky)
-- Use 8 columns for forms to keep text lines and input fields narrow for quicker reading
-- Bring actions closer to related titles (e.g., toggle switches near settings)
-
-**Full Width Layout Best Practices:**
-- Use when a form includes complex structures such as tables
-- Use for list items that contain many data columns
-
-**Combining Layouts:**
-- Avoid coast-to-coast inputs; keep inputs to 2/3 width of a card, or lay them out in two columns
-- Use white space on the right side for content preview
-- Use full width for tables with many columns and dividers that separate sections
-
-> **Note:** A column is easy to read if it is wide enough to accommodate an average of 10 words per line.
-
-#### 2. Display Layouts
-
-Display pages showcase data or content without accepting input from users. They can contain minor actions such as data filtering.
-
-**List (Table):**
-- Tables display large data sets and provide users with a quick overview
-- Use a 12-column layout for tables
-- Enables users to manipulate and act on a data set
-
-**List (Grid) Options:**
-- 2 columns (6/6 split) - For items with lengthy descriptions
-- 3 columns (4/4/4 split) - For visual items with multiple data types
-- 4 columns (3/3/3/3 split) - For user-generated galleries and collections, reveals up to 50% more content above the fold than 4/4/4
-- Custom - For mixed content needs
-
-**Grid Selection Considerations:**
-- Total amount of items to show
-- Content to display in each list item
-- What objects the list items reflect (match physical shapes when applicable)
-
-**Dashboards:**
-Display different types of data on a specific topic using a combination grid.
-
-Column span recommendations:
-- **3 or 4 columns** - For list items, previews, marketing, statistics, and charts
-- **12 columns (full width)** - For tables and marketing content
-- **8 columns** - For lists, tables with few data columns, setup wizards, and charts
-- **6 columns** - For lists, tables with few data columns, and statistics
-
-**Empty States:**
-- Use full width layout for empty state of a page
-- Indicates feature/product has no data yet, all data cleared, or not set up yet
-- Include clear CTA indicating what to do to fill the page
-- Can combine with other layout elements such as tabs, statistics widgets, or marketing cards
-
-#### 3. Marketing Layouts
-
-Marketing pages promote new products that site owners are not aware of yet. Built using the `<MarketingPageLayout/>` component split into 2 columns:
-
-1. Promo messaging
-2. Visual representation of product and features
-
-Optional footer area can display features or testimonials list.
-
-#### 4. Wizard Layouts
-
-Wizard pages guide users through setting up a product or feature. They split complex forms into steps for easier completion.
-
-**Entry Points:**
-- A marketing page
-- A marketing card
-- The primary action of a page
-- An empty state
-
-> **Note:** Wizards must have a final destination. After completing all steps, users should end up on a relevant page: a dashboard, a details page, or any other relevant location.
-
-
-### Related WDS Components
+Content layout inside the page shell — the 6px base unit, the 12-column grid, spacing tokens, form/display/marketing/wizard layouts: see [WDS Layout Reference](dashboard-page/WDS_LAYOUT.md).
 
-- `<Page />` - Main page wrapper
-- `<Layout />` - Grid layout container
-- `<MarketingPageLayout />` - Marketing page wrapper
-- `<Card />` - Content container with 24px gaps between cards
+Remember the split: `@wix/patterns` owns the page shell and anything collection-shaped (tables, grids, filters, sorting, empty states); that reference covers the content you place inside it.

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

@@ -67,10 +67,12 @@ File where you can override the generated manifest from `<componentName>.generat
 3. Edit the generated React and CSS files in
    `src/extensions/site/components/component-name/`. Apply
    [`editor-react-component/DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) while
-   authoring: every interactive named part must use interactive markup and
-   pair each native state selector with its prefixed global modifier (for
-   example, `.cta:global(.component-name-cta--hover), .cta:hover`). A
-   pseudo-class without the matching global modifier is incomplete.
+   authoring: every interactive named part must use interactive markup, and
+   every native design state supported by the eligibility table must pair its
+   selector with the prefixed global modifier (for example,
+   `.cta:global(.component-name-cta--hover), .cta:hover`). A standalone
+   `:focus-visible` keyboard indicator on a non-input control is not an editor
+   design state and intentionally has no global modifier.
 4. **MANDATORY** — execute the full A11y Review on the edited component per [`editor-react-component/A11Y-REVIEW.md`](editor-react-component/A11Y-REVIEW.md). Run both scanners over the component's `.tsx`/`.jsx` files, complete the Phase 3 manual semantic review, fix confirmed findings, and re-run the scanners after fixes. Reading the reference without executing these steps is not a review. Do not proceed to the build or report completion until the review is complete.
 5. Run `npx wix build && npx wix generate manifest` so the editor picks up
    the new/updated prop schema. This command regenerates manifest
@@ -79,7 +81,7 @@ File where you can override the generated manifest from `<componentName>.generat
    ≥ 1.1.210, but prop-triggered `ElementState` states need ≥ 1.1.215). If a
    design state is missing from `<componentName>.generated.ts`, the installed
    CLI is older than required — tell the user, and let them decide whether to
-   upgrade.
+   upgrade. If the command exits with an error, diagnose using [`editor-react-component/MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md).
 6. Update `Component.extensions.ts` file according to [`editor-react-component/COMPONENT-CONFIGURATION.md`](editor-react-component/COMPONENT-CONFIGURATION.md)
 
 If the component's primary content is a **playable animation** (Lottie/JSON,
@@ -102,6 +104,11 @@ before writing the code. Triggers, and the only cases that warrant it:
 
 Otherwise, do not reach for a hook at all — data the site owner can type or pick
 belongs in props.
+If the component displays **an array of items where only one body is visible at a
+time** (tabs, slides, steps), follow the
+[active-item rules](editor-react-component/COMPONENT-API.md#active-item-components-one-body-visible-at-a-time)
+in [`editor-react-component/COMPONENT-API.md`](editor-react-component/COMPONENT-API.md) (`ActiveItemIndex<>`,
+`name` on each item, render-all-panels visibility).
 
 Reference: when modifying an _existing_ component, follow
 [`editor-react-component/EDIT-FLOW.md`](editor-react-component/EDIT-FLOW.md).
@@ -117,7 +124,8 @@ Topic-focused references (rules + patterns + common mistakes in one place):
 - [`editor-react-component/DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) — Which design states a part supports (heuristic) and how to author them
 - [`editor-react-component/DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) — RTL/LTR rules and patterns
 - [`editor-react-component/PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) — What should be a React prop vs CSS
-- [`editor-react-component/COMPONENT-API.md`](editor-react-component/COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props
+- [`editor-react-component/COMPONENT-API.md`](editor-react-component/COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props, active-item components
+- [`editor-react-component/FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) — Standard SDK event handler props, DOM wiring, custom callbacks
 - [`editor-react-component/ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md) — Play/pause control and autoplay for animated/playable components
 - [`editor-react-component/COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) — Editor-specific entry point (`component.preview.tsx`), `useIsEditMode()`, when to modify
 - [`editor-react-component/SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) — Hooks for runtime site context (site pages, current URL, language direction, editor mode) — read only when a trigger above applies

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

@@ -230,6 +230,12 @@ await embeddedScripts.embedScript({
 });
 ```
 
+## Releasing Updates
+
+`embedScript()` is not only a one-time setup step. A site only ever renders whatever content was active the last time `embedScript()` was called for it — releasing a new app version (even a minor one, e.g. via `wix release`, that only changes the script's HTML/JS with no dynamic-parameter changes) does **not** re-embed the script on sites that already called it. Always prompt the site owner to re-run the dashboard-page action (or call `embedScript()` yourself) after any release that changes an embedded script's content, or production sites will silently keep serving the old version.
+
+Adding, removing, or renaming a dynamic parameter is additionally a **major** version change — those sites only pick up the new version after the user clicks Update on the Manage Apps page (or you drive them through the app-installer update flow). See [About App Versioning](https://dev.wix.com/docs/build-apps/manage-your-app/versioning/about-app-versioning).
+
 ## Enable Embedded Script Permission
 
 After implementation, the app developer must manually enable the embedded script permission: