@wix/agent-skills 1.17.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "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,13 +16,22 @@ 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
+  - [ ] **🛑 SDK-First Gate (MANDATORY before any Data Collection):** Confirmed the data is NOT owned by an existing Wix app — if it is, use its SDK module, never CMS (see [SDK-First Rule](#sdk-first-rule-existing-wix-app-data-is-never-cms))
   - [ ] 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.
+  - [ ] **Dashboard page UI:** Translated the prompt into a workflow before choosing components — what the user must understand, focus on, investigate, act on, and see confirmed. See [UX Success Model](references/dashboard-page/UX_SUCCESS_MODEL.md), and [Collection Toolkit](references/dashboard-page/COLLECTION_TOOLKIT.md) for which component serves each need.
+    - [ ] **The page shows aggregate numbers, not only rows** (`SummaryBar`) — unless the prompt asks for a single record. "How many, and which ones need me" is why someone opens a dashboard.
+    - [ ] **A row the user can open** — WDS `SidePanel` to inspect without losing the filtered list, or `EntityPage` for deep or shareable detail — unless the prompt is explicitly a report or an export.
+    - [ ] **Every filter reaches the query**: declared in the collection hook's `filters` and read inside `fetchData`. Filter UI that never narrows the rows is a defect that looks like a feature.
+
+    A filtered table with none of the three is what gets built when nobody states the requirement — it is the most common way a generated dashboard disappoints.
+  - [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md), then `Read` `dist/dts-bundle/index.json` for the component inventory, upgrading `@wix/patterns` if that file is missing. The patterns docs are only ever read directly from those two published files — never by hand from anywhere else in `node_modules`.
+  - [ ] **🛑 Component Docs Gate (MANDATORY, dashboard UI only):** Printed the doc for every patterns component, hook, and state type you are about to write — `Read` its file from `dist/docs/index.json`, and `Read` its bundled `.d.ts` from `dist/dts-bundle/index.json` for any patterns type you name in your own code. The inventory gives the name; the doc gives the props and the import path. Name what you read before the first line of JSX.
 - [ ] **Step 3:** Checked API references; used MCP discovery only for gaps
+  - [ ] Site/editor extensions only: kept SDK calls in the extension by default, routing out only business-wide methods a visitor genuinely cannot call (see [Identity and Elevation Requirement](#identity-and-elevation-requirement))
 - [ ] **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).
@@ -43,14 +52,18 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 
 | ❌ WRONG                                    | ✅ CORRECT                                     |
 | ------------------------------------------- | ---------------------------------------------- |
+| Creating a CMS Data Collection for data an existing Wix app already owns (orders, products, bookings, contacts…), or deciding "no SDK exists" without a single MCP search | Use the domain's SDK module per the [SDK-First Rule](#sdk-first-rule-existing-wix-app-data-is-never-cms) |
 | Hand-writing builder files, folders, UUIDs, or extension registration | Run `wix generate --params` — it owns scaffolding |
 | Implementing without reading the extension reference | Always read the relevant reference file first |
 | 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     |
 | 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 |
+| Guessing a `@wix/patterns` or WDS component/prop name from memory | Look it up: patterns via `dist/docs/index.json` + `dist/dts-bundle/index.json` (see [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md)), 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 |
+| Calling `auth.elevate` from a site or editor extension, or calling an admin-only method there | Put the call in a backend extension and elevate there — elevation only works in backend code |
+| Elevating a session-resolved `current*`/`my*` method (`currentCartV2.*`, `members.getMyMember`) to "be safe" | Call it directly — elevating replaces the caller's session identity and retargets the operation |
+| Elevating a read the platform filters by caller (`members.getMember`/`queryMembers`, `items.*`, catalog) to "make it return more" | Call it directly — elevating removes the filter and returns data the visitor was never entitled to |
 
 ---
 
@@ -59,7 +72,7 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 1. **What are you trying to build?**
    - Admin interface → Dashboard Extensions
    - Backend logic → Backend Extensions
-   - Data storage / CMS collections → Data Collection
+   - Data storage / CMS collections → Data Collection (app-owned data only — see [SDK-First Rule](#sdk-first-rule-existing-wix-app-data-is-never-cms))
    - Editor React component → Site Extensions (app projects only)
 
 2. **Who will see it?**
@@ -83,7 +96,7 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 ## Decision Flow (Not sure?)
 
 - **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.
+- **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-owned data? → Data Collection (see [SDK-First Rule](#sdk-first-rule-existing-wix-app-data-is-never-cms)).
 - **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.
 
 ---
@@ -107,15 +120,19 @@ Patterns owns the page shell and everything collection-shaped. These concepts ar
 | **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:**
+**Looking a component up is two direct file reads** — no script, never `node_modules` browsed by hand. Resolve the installed package root once per session ([Prerequisites](references/WIX_PATTERNS_DOCS.md#prerequisites)), then reuse it. Start with what exists:
 
 ```bash
-cat node_modules/@wix/patterns/dist/docs/index.json
+cat <pkgRoot>/dist/dts-bundle/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.
+Then read the doc for each name you plan to use, including the state types they cross-reference — `Read <pkgRoot>/dist/docs/index.json` to find the file, then `Read` it directly. Props and import paths exist only there, and patterns is not a flat namespace — `@wix/patterns/page`, `/provider`, `/form` — so an import from memory is a guess.
 
-`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).
+Each doc gives its import line, props table, and an example. For a TypeScript type rather than a component — `Filter<T>`, `RangeItem<T>`, `CursorQuery`, a `...Props` interface — look it up the same way in `dist/dts-bundle/index.json` instead and `Read` the `.d.ts` at exactly the `file` path it gives; it's already fully resolved, which is what keeps a deep `@wix/bex-core/dist/types/...` path out of the tree.
+
+If `dist/dts-bundle/index.json` doesn't exist, the installed `@wix/patterns` predates this feature — upgrade it, then re-check. See [Prerequisites](references/WIX_PATTERNS_DOCS.md#prerequisites). **A missing index 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.
+
+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
 
@@ -138,16 +155,20 @@ Compose from WDS layout primitives (`Box`, `Card`, `Text`). Do not add a third U
 
 ### 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.
+**Any dialog that creates, updates, or displays one record listed by a collection page is an `EntityPage` — not a Dashboard Modal.** This holds whether the records come from a CMS collection or an existing Wix app's SDK. A create / "add new" form is included: it **writes** the record, so it is an `EntityPage` even though nothing is being edited yet. "It's a simple data-entry dialog, not an entity edit" is the wrong reading of this rule.
+
+A page that lists nothing — a settings page, an embedded-script config page — carries no `EntityPage` obligation. But "I built the list without `@wix/patterns`" is not an exception: a page that lists records should be a `CollectionPage`.
+
+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`.
+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`. The call itself — both generics, what `onSave` receives, which params exist — is in [ENTITY_PAGE_TOOLKIT.md](references/dashboard-page/ENTITY_PAGE_TOOLKIT.md).
 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."
+Use a Dashboard Modal for dialogs that neither write nor display a listed record: a delete or discard confirmation, an unsaved-changes prompt, an informational notice, or any dialog on a page that lists nothing. Dialog size and field count are not exceptions — a one-field create form over a listed record is still an `EntityPage`. Reach for a modal because the interaction persists nothing, never because "the form should open in a modal."
 
 ---
 
@@ -194,6 +215,56 @@ Use a Dashboard Modal only for dialogs that are genuinely not entity editing: a
 | Wix Stores Versioning (V1/V3) | [STORES_VERSIONING.md](references/STORES_VERSIONING.md) |
 | Official Documentation Links | [DOCUMENTATION.md](references/DOCUMENTATION.md) |
 | Wix Patterns Dashboard Pages | [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md) |
+| Dashboard UX Success Model (what a good dashboard contains) | [UX_SUCCESS_MODEL.md](references/dashboard-page/UX_SUCCESS_MODEL.md) |
+| Dashboard Collection Toolkit (which component per user need) | [COLLECTION_TOOLKIT.md](references/dashboard-page/COLLECTION_TOOLKIT.md) |
+| Reading a patterns bundle or doc file the index names | [PATTERNS_BUNDLE_READING.md](references/dashboard-page/PATTERNS_BUNDLE_READING.md) |
+
+---
+
+## SDK-First Rule (Existing Wix App Data Is Never CMS)
+
+**CRITICAL:** Data owned by an existing Wix business app is read and written through that app's SDK module — NEVER modeled as a new CMS Data Collection. A custom collection for such data starts empty and stays disconnected from the real records (e.g., a "refunds dashboard" built on CMS shows an empty state while refunded orders exist in Wix eCommerce).
+
+**Entity → SDK module map** (find the entity the user mentioned, use that package):
+
+| Entity | SDK package |
+| --- | --- |
+| orders / carts / checkout / refund records / fulfillments | `@wix/ecom` — orders live here regardless of vertical |
+| products / inventory / catalog | `@wix/stores` — ⚠️ V1/V3 check, see [STORES_VERSIONING.md](references/STORES_VERSIONING.md) |
+| payments / refunds / disputes | `@wix/payments` |
+| invoices / payment links / receipts | `@wix/get-paid` |
+| gift cards | `@wix/gift-vouchers` |
+| coupons | `@wix/marketing` |
+| pricing plans / subscriptions | `@wix/pricing-plans` |
+| bookings / services / staff / time slots | `@wix/bookings` |
+| calendar events / schedules | `@wix/calendar` |
+| table reservations | `@wix/table-reservations` |
+| restaurant menus / online orders | `@wix/restaurants` |
+| blog posts | `@wix/blog` |
+| site events / tickets / RSVPs | `@wix/events` |
+| reviews | `@wix/reviews` |
+| comments | `@wix/comments` |
+| groups | `@wix/groups` |
+| online programs | `@wix/online-programs` |
+| donations | `@wix/donations` |
+| portfolio | `@wix/portfolio` |
+| media files | `@wix/media` |
+| contacts / labels / tasks | `@wix/crm` |
+| members | `@wix/members` |
+| inbox conversations | `@wix/inbox` |
+| forms / form submissions | `@wix/forms` |
+| loyalty points / rewards | `@wix/loyalty` |
+| email marketing | `@wix/email-marketing` |
+| notifications | `@wix/notifications` |
+| analytics | `@wix/analytics-data` |
+| automations | `@wix/automations` |
+| SEO tags / redirects | `@wix/seo` |
+| site search | `@wix/search` |
+| secrets | `@wix/secrets` |
+| locations / site properties | `@wix/business-tools` |
+| app instances | `@wix/app-management` |
+
+If the entity isn't listed or you're unsure, run `SearchWixSDKDocumentation` for it — **never conclude CMS with zero MCP calls**. CMS is only for data your app itself introduces (configuration, rules, app-specific records) that no Wix app manages.
 
 ---
 
@@ -201,6 +272,8 @@ Use a Dashboard Modal only for dialogs that are genuinely not entity editing: a
 
 **CRITICAL:** Data collections are often needed implicitly — don't wait for the user to explicitly say "create a CMS collection." Infer the need automatically.
 
+**⚠️ Apply the [SDK-First Rule](#sdk-first-rule-existing-wix-app-data-is-never-cms) first** — the indicators below only apply to data your app itself owns, not to entities a Wix app already manages.
+
 **Skip this section if the user provides a collection ID directly** (e.g., an existing site-level collection). In that case, use the provided ID as-is — no Data Collection extension or namespace scoping needed.
 
 **Always include a Data Collection extension when ANY of these are true:**
@@ -249,6 +322,35 @@ This is non-negotiable — V1 and V3 are NOT backwards compatible.
 
 ---
 
+## Identity and Elevation Requirement
+
+**Applies whenever an extension calls a Wix SDK method.** Decide where the call runs before writing it.
+
+Who the extension runs as decides everything below — the Category column in [Extension Types Reference Table](#extension-types-reference-table) tells you which one you have:
+
+- **Site and editor extensions** — custom element widgets, site plugins, Editor React components, embedded scripts — run as the site visitor or member, never as the app.
+- **Dashboard extensions** run as the Wix user — not as a site visitor, and not as the app.
+- **Backend extensions** — Backend API, Backend Event, Service Plugin — run as the app.
+
+**`auth.elevate` works only in backend code.** In a site, editor, or dashboard extension it doesn't work at all.
+
+**Default: call the SDK directly from the extension.** Routing a call that didn't need it is not a harmless extra hop — it is how working features break. Sort by who the call acts for, never by its scope name:
+
+- **Acts for the current visitor or member** — their cart, checkout, booking, order, reservation, or profile: `currentCartV2.*`, `cartV2.placeOrder`, `bookings.createBooking`, `members.getMyMember`, and anything else operating on "my" or "the current" entity. These resolve the actor from the caller's session, so elevating runs them as the app and detaches the result from the person who asked — an order with no buyer, a booking with no attendee.
+- **The platform filters the result by caller** — an elevated call returns what the direct call withheld, so a "fix" for a sparse result becomes a leak. Wix Data `items.*` follows the collection's `dataPermissions` (scaffolded default: `itemRead: 'ANYONE'`, writes `'PRIVILEGED'` — fix writes with permissions, not routing; see [DATA_COLLECTION.md](references/DATA_COLLECTION.md)). Catalog reads return base fields to anyone, withholding `MERCHANT_DATA` and non-visible products unless the app holds `SCOPE.STORES.PRODUCT_READ_ADMIN`. `members.getMember`/`queryMembers` withhold `PRIVATE` members from visitor and member callers.
+
+**Route out only when the method acts on the business as a whole**, which a visitor or member genuinely cannot do: `archiveLocation`, `queryLocations`, catalog and inventory writes, `bookings.confirmBooking`, order management. **When the method's docs show the call elevated, route it out and elevate there** — from any host, dashboard included, because `auth.elevate` only works in backend code, so the endpoint is the only place the documented pattern can run.
+
+**When you're unsure, call it directly and let it fail.** A method a site extension may not call returns a permission error you see immediately; a method wrongly routed and elevated *succeeds* and silently returns the wrong data or acts for the wrong person. Some method pages carry a prose note that settles it — `get-my-member`: "This method requires visitor or member authentication." Authoritative when present, but only a minority of pages have one, so its absence decides nothing.
+
+Two signals never settle it: the scope name — `locations.queryLocations` is `SCOPE.DC-MULTILOCATION.READ-LOCATIONS` yet admin-only, while `currentCartV2.addLineItemsToCurrentCart` carries `SCOPE.ECOM.MANAGE-ADMIN` yet is visitor-callable and breaks if elevated — and the SDK schema line's client prefix, which varies by docs channel for the same method, so carries nothing and isn't worth re-deriving.
+
+Routing out means a Backend API endpoint that elevates and is reached with `httpClient.fetchWithAuth()`. Elevation bypasses Wix's permission check, so the endpoint must re-check the caller itself — see [Identity and Authorization](references/BACKEND_API.md#identity-and-authorization) for what each host can actually verify, and why an owner-only operation belongs in a dashboard extension instead.
+
+Add the scope in Dev Center → **Permissions** (it isn't declared in a repo file) and report it under [Manual Steps Required](#-manual-steps-required).
+
+---
+
 ## App Market Review
 
 **Applies when a user wants to submit their app to the Wix App Market, list it publicly, prepare for App Market review, audit decline risk, or fix App Market review feedback.** Not needed for private apps or routine version releases.
@@ -288,13 +390,14 @@ Use the Extension Types Reference Table and decision content above. State extens
 - Wix Data, Dashboard SDK, Event SDK (common events), Service Plugin SPIs
 
 **Vertical APIs (discover if needed):**
-- Wix Stores (**⚠️ MUST use Stores Versioning reference** — V1/V3 catalog check required), Wix Bookings, Wix Members, Wix Pricing Plans, third-party integrations
+- Wix Stores (**⚠️ MUST use Stores Versioning reference** — V1/V3 catalog check required), Wix eCommerce, Wix Bookings, Wix Members, Wix Pricing Plans, third-party integrations — find the right `@wix/*` package in the [SDK-First Rule](#sdk-first-rule-existing-wix-app-data-is-never-cms) module map first, then discover methods via MCP
 
 **Decision table:**
 
 | User Requirement                     | Check References / Discovery Needed? | Reason / Reference File                             |
 | ------------------------------------ | ------------------------------------ | --------------------------------------------------- |
 | "Display store products"             | ✅ YES (MCP discovery)               | Wix Stores API — **include Stores Versioning reference** |
+| "Dashboard for orders / refunds"     | ✅ YES (MCP discovery)               | Wix eCommerce API (`@wix/ecom`) — **NEVER a CMS collection** |
 | "Show booking calendar"              | ✅ YES (MCP discovery)               | Wix Bookings API not in reference files             |
 | "Send emails to users"               | ✅ YES (MCP discovery)               | Wix Triggered Emails not in reference files         |
 | "Get member info"                    | ✅ YES (MCP discovery)               | Wix Members API not in reference files              |

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

@@ -292,7 +292,7 @@ Use these IDs for traceability when mapping findings to review feedback.
 | 122 | Handle site duplication through `originInstanceId`. | Multi-instance |
 | 123 | External pricing page is broken or used instead of Wix internal billing. | Billing |
 | 125 | Premium features require a clear upgrade path; do not infer app billing from Business Solutions Pricing Plans API usage. | Billing |
-| 130 | Apps supporting Wix Stores catalog data must support both Catalog V1 and Catalog V3. | Stores |
+| 130 | Apps using Wix Stores catalog data must support Catalog V1 and Catalog V3 — see [STORES_VERSIONING.md](STORES_VERSIONING.md). | Stores |
 | 132 | App installation process fails or results in errors. | Installation |
 | 133 | Login/session issues occur during or after installation. | Identity |
 | 151 | Custom element has quality issues such as pixelated images or missing descriptions. | Component quality |

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

@@ -201,6 +201,24 @@ const res = await httpClient.fetchWithAuth(
 const data = await res.json();
 ```
 
+## Identity and Authorization
+
+Endpoints run as the **app**, so this is one of the few places `auth.elevate` is valid — it works only in backend code, never in a site, editor, or dashboard extension. It wraps the SDK method rather than being called around it, so inside a request handler you invoke the wrapper:
+
+```typescript
+import { auth } from "@wix/essentials";
+import { locations } from "@wix/business-tools";
+
+const elevatedArchive = auth.elevate(locations.archiveLocation);
+const archived = await elevatedArchive(locationId); // locationId read from the request
+```
+
+**Only create an endpoint for calls that need it.** Settle that with [Identity and Elevation Requirement](../SKILL.md#identity-and-elevation-requirement) *before* adding a file under `src/pages/api/` — an endpoint wrapping a call the extension could have made itself is a correctness or privacy bug, not extra indirection, because elevating inside it re-targets a session-resolved call away from the visitor or hands back what the platform deliberately withheld.
+
+**Elevation bypasses Wix's permission check, so the endpoint must re-check the caller itself** — otherwise every caller who can reach it gets the elevated operation, and only `httpClient.fetchWithAuth()` (see [Frontend Integration](#frontend-integration)) sends the caller's identity for the handler to check; a bare `fetch` sends nothing and leaves the endpoint open.
+
+What you can establish depends on the host: a dashboard caller is a Wix user, whose roles already limit them. From a site or editor extension `members.getMyMember()` identifies a logged-in member, but there is **no documented way to prove the caller is the site owner** — a real constraint, not an oversight, so an owner-only operation belongs in a dashboard extension, where the Wix user identity already carries the authority, rather than behind an endpoint reachable from a site extension.
+
 ## Build, Deploy, and Delete
 
 To take HTTP endpoints to production, build and release your project:

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

@@ -138,6 +138,12 @@ The convention differs by pattern, but the settings panel side is always kebab-c
 | React component props interface | camelCase | `displayName?: string` |
 | `<name>.panel.tsx` — `widget.getProp` / `widget.setProp` | kebab-case | `"display-name"`, `"bg-color"` |
 
+## Identity and SDK Calls
+
+A widget runs on the live site 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.
+
+A widget's collection reads also need permissions that admit an anonymous visitor — see [Permissions](DATA_COLLECTION.md#permissions), since the scaffolded default allows `ANYONE` to read but only `PRIVILEGED` to write.
+
 ## Wix Data API Integration
 
 When using the Wix Data API in widgets, you **must** handle the Wix Editor environment gracefully — fetching data inside the Editor produces empty results and noisy errors.

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

@@ -3,7 +3,15 @@
 
 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).
+> **🛑 Scope — apply this test before building a modal.** Does the dialog **create, update, or display one record that a table or list in your app enumerates**? If yes, it is not a modal — it is a `@wix/patterns` `EntityPage`, reached via `usePatternsNavigate().navigateToEntityPage`. This holds whether those records come from a CMS collection or an existing Wix app's SDK.
+>
+> A create / "add new" form is included: it **writes** the record, so it is an `EntityPage` even though nothing is being edited yet. "It's a simple data-entry dialog, not an entity edit" is the wrong reading of this rule, and it is the most common way the rule is lost. Dialog size and field count are not exceptions either — a one-field create form is still an `EntityPage`.
+>
+> **A page that lists nothing is out of scope.** A settings page, an embedded-script config page, or any dashboard page that does not enumerate records carries no `EntityPage` obligation, and a dashboard modal is a normal choice there.
+>
+> So a dashboard modal is for: **destructive confirmations** (delete, discard, unsaved changes), **dialogs that persist nothing and show no record detail** (an informational notice, a picker that returns a selection), and **dialogs on pages that list nothing**. Never the add/edit form of a listed record — and "I built the list without `@wix/patterns`" is not an exception: a page that enumerates records should be a `CollectionPage`, so the fix is the page, not the dialog.
+>
+> See [Entity create and edit](../SKILL.md#entity-create-and-edit) and [WIX_PATTERNS_DOCS.md](WIX_PATTERNS_DOCS.md).
 
 ## Scaffold
 
@@ -138,4 +146,4 @@ 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.)
+(Creating, updating, or displaying 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,12 +1,18 @@
 # Wix Dashboard Page Builder
 
-Dashboard pages appear in the site owner's Wix dashboard and enable site administrators to manage data, configure settings, and perform admin tasks.
+Dashboard pages appear in the site owner's Wix dashboard, where administrators manage data, configure settings, and perform admin tasks.
+
+## Plan the Workflow Before the Components
+
+A dashboard page is a workflow, not a screen. The site owner has to understand the situation, focus on what needs attention, investigate one record, act, and see the result confirmed — so translate the prompt into those needs before choosing any component: which view fits, which drill-in surface, which data sources have to line up.
+
+Do this first because a bare filtered table answers "what are all the records" and none of "how many", "which one needs my attention", or "why did this happen" — and a table is what you get by default if the workflow was never named. Read [UX Success Model](dashboard-page/UX_SUCCESS_MODEL.md) now, and run its evaluation checklist before calling the page done. Which component serves each need: [Collection Toolkit](dashboard-page/COLLECTION_TOOLKIT.md).
 
 ## 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).
+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 directly in `dist/dts-bundle/index.json` and `dist/docs/index.json` (start with the inventory). 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.
 
@@ -27,22 +33,16 @@ 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.
+**Then, before writing UI:** resolve the package root and `Read <pkgRoot>/dist/dts-bundle/index.json` once, per [Prerequisites](WIX_PATTERNS_DOCS.md#prerequisites). Each Bash call is a fresh shell, so if you keep the path in a variable, set it again in every call.
 
 ## Capabilities
 
+A dashboard page runs as the **Wix user** — see [Identity and Elevation Requirement](../SKILL.md#identity-and-elevation-requirement) before deciding where an SDK call runs.
+
 ### Data Operations (Wix Data SDK)
 
 See [Wix Data Reference](data-collection/WIX_DATA.md) in the Data Collection reference for complete documentation.
 
-**Summary:**
-
 - Read: `items.query('Collection').filter/sort.limit.find()` → `{ items, totalCount, hasNext }`
 - Write: `items.insert | update | remove`. Ensure collection permissions allow the action
 
@@ -52,48 +52,41 @@ See [Wix Data Reference](data-collection/WIX_DATA.md) in the Data Collection ref
 
 See [Dashboard API Reference](dashboard-page/DASHBOARD_API.md) for complete documentation including all methods, page IDs, and examples.
 
-**Key methods:**
+**Key methods**, all on the `dashboard` object from `@wix/dashboard` (signatures, page IDs, and examples in the reference above):
 
-- `dashboard.navigate()` - Navigate between dashboard pages
-- `dashboard.observeState()` - Receive contextual state and environmental information
-- `dashboard.showToast()` - Display toast notifications
-- `dashboard.openModal()` - Open dashboard modal extensions (see [Dashboard Modal reference](DASHBOARD_MODAL.md))
-- `dashboard.navigateBack()` - Navigate back to previous page
-- `dashboard.getPageUrl()` - Get full URL for a dashboard page
-- `dashboard.openMediaManager()` - Open Wix Media Manager
-- `dashboard.onBeforeUnload()` - Register beforeunload handler
-- `dashboard.addSitePlugin()` - Add site plugin to slots
-- `dashboard.setPageTitle()` - Set page title in browser tab
-- `dashboard.onLayerStateChange()` - Handle foreground/background state changes
+- Navigation: `navigate()`, `navigateBack()`, `getPageUrl()`
+- Feedback and chrome: `showToast()`, `setPageTitle()`
+- Overlays: `openModal()` (see [Dashboard Modal reference](DASHBOARD_MODAL.md)), `openMediaManager()`
+- State and lifecycle: `observeState()`, `onBeforeUnload()`, `onLayerStateChange()`
+- Slots: `addSitePlugin()`
 
 **CRITICAL: Using Modals in Dashboard Pages**
 
-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.
+Dashboard Pages cannot use `<Modal />`. For a true dialog overlay you **MUST** use a dashboard modal extension — never a React modal, never the WDS `Modal` component. Reserve it for dialogs that neither write nor display a record this app lists (delete/discard confirmations, unsaved-changes prompts, informational notices), plus any dialog on a page that lists nothing (settings, config). They open via `dashboard.openModal()`, which integrates them with the dashboard lifecycle, state management, and navigation — implementation guide: [Dashboard Modal reference](DASHBOARD_MODAL.md).
 
-- **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).
+> **🛑 The test — does the dialog create, update, or display one record this page lists?** If yes, it is an `EntityPage`, not a modal — whether those records come from a CMS collection or an existing Wix app's SDK. **A create / "add new" form is included**: it writes the record, so it is an `EntityPage` even though nothing is being edited yet. "It's a simple data-entry dialog, not an entity edit" is the wrong reading, and it is the single most common way the patterns-first rule gets dropped after the table is already correct.
+>
+> The `EntityPage` comes from `@wix/patterns`, reached via `usePatternsNavigate().navigateToEntityPage`, with `useEntityPage` owning fetch/save/validation and `@wix/patterns/form` owning form state. Its route is registered with `PatternsReactRoute` inside `PatternsReactRouter` — so do not hand-roll page location state to fake a second view (`useState<PageLocation>`, a `location` cast on `withDashboard`); that is the router's job, and needing the cast is the signal you skipped it.
+>
+> **If this page lists nothing** — a settings page, an embedded-script config page — the rule does not apply and a dashboard modal is a normal choice. But "I built the list without `@wix/patterns`" is not an exception: a page that lists records should be a `CollectionPage`.
+>
+> See [Entity create and edit](../SKILL.md#entity-create-and-edit) and [WIX_PATTERNS_DOCS.md](WIX_PATTERNS_DOCS.md); for the `useEntityPage` call itself, [Entity Page Toolkit](dashboard-page/ENTITY_PAGE_TOOLKIT.md).
 
 **Ecom Navigation:** See [Ecom Navigation Reference](dashboard-page/ECOM_NAVIGATION.md) for ecom-specific navigation helpers.
 
 ### Embedded Script Configuration API
 
-When building a dashboard page to configure an embedded script, see [Dynamic Parameters Reference](dashboard-page/DYNAMIC_PARAMETERS.md) for complete implementation guide.
+When building a dashboard page to configure an embedded script, see [Dynamic Parameters Reference](dashboard-page/DYNAMIC_PARAMETERS.md) for the implementation guide.
 
 **Key points:**
 
 - Use `embeddedScripts` from `@wix/app-management`
-- Parameters are returned as strings - handle type conversions when loading
-- All parameters must be saved as strings (convert booleans/numbers to strings)
-- Use `withProviders` wrapper when dynamic parameters are present
+- Parameters cross the API as strings in both directions — convert on load, and convert booleans/numbers back to strings on save
+- Use the `withProviders` wrapper when dynamic parameters are present
 
 ## 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.
+Each output below names the library that owns each part. Confirm every patterns component and prop by reading its doc from `dist/docs/index.json` before use — these examples name the shape, not a verified API.
 
 ### Data Management Table
 
@@ -117,47 +110,16 @@ Each output below names the library that owns each part. Confirm every patterns
 
 **Request:** "Create a settings page for the coupon popup embedded script"
 
-**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
-import { embeddedScripts } from "@wix/app-management";
-
-// Load on mount
-useEffect(() => {
-  const load = async () => {
-    const script = await embeddedScripts.getEmbeddedScript();
-    const data = script.parameters || {};
-    setOptions({
-      headline: data.headline || "Default",
-      enabled: data.enabled === "true",
-      threshold: Number(data.threshold) || 0,
-    });
-  };
-  load();
-}, []);
-
-// Save handler
-const handleSave = async () => {
-  await embeddedScripts.embedScript({
-    parameters: {
-      headline: options.headline,
-      enabled: String(options.enabled),
-      threshold: String(options.threshold),
-    },
-  });
-  dashboard.showToast({ message: "Saved!", type: "success" });
-};
-```
+**Output:** A `@wix/patterns` `SettingsPage` shell with WDS form fields for popup headline, coupon code, minimum cart value, and enable toggle. `embeddedScripts.getEmbeddedScript()` loads the parameters on mount and `embeddedScripts.embedScript()` saves them back — both sides string-converted, per [Dynamic Parameters](dashboard-page/DYNAMIC_PARAMETERS.md).
 
 
 ## API Spec Support
 
-When an API specification is provided, you can make API calls to those endpoints. See [API Spec Reference](dashboard-page/API_SPEC.md) for details on how to use API specs in dashboard pages.
+When an API specification is provided, you can call those endpoints — see [API Spec Reference](dashboard-page/API_SPEC.md).
 
 
 ## Layout Guidelines
 
 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).
 
-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.
+Remember the split: `@wix/patterns` owns the page shell and anything collection-shaped; that reference covers only the content you place inside it.

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

@@ -20,7 +20,7 @@ file responsibilities:
 | `<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.preview.tsx` | Edit narrowly | Keep generated wrappers; sync the preview adapter, one crucial data field, and root class. |
 | `<component-name>.generated.ts` | NEVER edit | Generated manifest consumed by the editor. |
 | `<component-name>.extension.ts` | Edit narrowly | Apply supported partial manifest overrides. |
 
@@ -64,7 +64,9 @@ their responsibilities intact.
 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.
+   Finally, synchronize `requiredDataFields` and `rootClassName` in
+   `component.preview.tsx`.
 
 7. **Generate and validate.** Run:
 
@@ -103,9 +105,10 @@ component or edit `*.generated.ts` as a reference-driven fix.
 
 | 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) |
+| 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), 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) |
+| Changing public data props or the elected root global class | [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.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 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) |
@@ -118,6 +121,7 @@ component or edit `*.generated.ts` as a reference-driven fix.
 | 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) |
+| A CSS feature or DOM API that is not clearly long-established is introduced, or the 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) |
@@ -131,6 +135,9 @@ component or edit `*.generated.ts` as a reference-driven fix.
 - 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.
+- Use only Baseline Widely Available CSS features and DOM APIs, or ones that
+  fall back to them. When a design needs a feature that is not, build the
+  supported alternative.
 - 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.
@@ -143,3 +150,7 @@ component or edit `*.generated.ts` as a reference-driven fix.
   bodies accessibly.
 - If primary content autoplays or loops, provide an accessible play/pause
   control, honor reduced motion, and suppress autoplay in editor design mode.
+- In `component.preview.tsx`, keep `withDefaults` and `withFallbackPlaceholder`,
+  wrap the preview adapter when present, normally put
+  only the one data prop crucial to meaningful rendering in
+  `requiredDataFields`, and match `rootClassName` to 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