@wix/agent-skills 1.31.2 → 1.33.0

package/README.md

@@ -10,7 +10,7 @@ Agent skills for building Wix app extensions, managing Wix business solutions, d
 
 ### Claude Code Plugin
 
-In [Claude Code](https://docs.anthropic.com/en/docs/claude-code), run: 
+In [Claude Code](https://docs.anthropic.com/en/docs/claude-code), run:
 
 ```bash
 /plugin marketplace add wix/skills
@@ -63,7 +63,7 @@ npx skills add wix/skills -g
 | [wix-headless](skills/wix-headless/SKILL.md) | Connect Wix business services to a headless frontend (SDK + Wix CLI), and optionally build & host the site | Setting up a Wix Headless backend or adding Wix business features (Stores, Bookings, CMS, Blog, Events, Forms, Members, Restaurants, Portfolio, Pricing Plans) — install apps, seed content, and produce an SDK-integration guide; for managed projects also scaffold a new site (create) or wire an existing design (connect), then build and release. Works across managed, self-managed, and stripe project types |
 | [wix-vibe-headless](skills/wix-vibe-headless/SKILL.md) | Connect an existing front end to Wix over client-only REST | Wiring a vibe-coded / HTML / Vite app to a live Wix site (storefront, bookings, blog, events, portfolio, restaurants, CMS, pricing plans) from the browser with a public `WIX_CLIENT_ID` — no SDK, no backend |
 | [wix-docs](skills/wix-docs/SKILL.md) | Look up the Wix API/SDK docs (shared fallback) | Confirming an exact Wix endpoint, method schema, field, or enum before writing code — `curl` doc-search + the `.md`-twin trick, or the Wix MCP tools. Referenced by the other skills as their docs-lookup fallback |
-| [replatform](replatform/README.md) | Migrate sites from WordPress and other platforms into Wix | Migrating an exiting business from another platform into Wix. Both backend data and website. `npx skills add wix/skills/replatform` |
+| [wix-replatform](wix-replatform/README.md) | Migrate sites from WordPress and other platforms into Wix | Migrating an existing business from another platform into Wix. Both backend data and website. `npx skills add wix/skills/wix-replatform` |
 
 ## Supported Agents
 
@@ -89,21 +89,13 @@ These skills work with any agent that supports the [Agent Skills specification](
 
 When a major bump is required (a breaking change in the underlying `wix-cli`), the previous major continues on a `release/<N>.x` maintenance branch and receives backports for genuine bugs only — no new features.
 
-## Releasing
-
-Run the [`release-bump`](.github/workflows/release-bump.yml) workflow from the **Actions** tab and pick a `version_strategy`. The rest is automatic — the bump PR auto-merges once checks pass and [`release.yml`](.github/workflows/release.yml) publishes to npm via Trusted Publishing.
-
 ## Serving (`www.wix.com/skills`)
 
-Besides the npm package, skills are served as raw markdown / `.tgz` at `https://www.wix.com/skills/<name>` (also `dev.wix.com/skills`), directly from this repo's `main` branch with no build step. Responses are cached, so a merge to `main` reflects there within a few minutes.
+Besides the npm package, skills are served as raw markdown / `.tgz` at `https://www.wix.com/skills/<name>` (also `dev.wix.com/skills`), directly from the `main` branch of `wix/skills` with no build step. Responses are cached, so a change reflects there within a few minutes of reaching that branch.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding new skills.
-
-### Eval Token Budgets
-
-Eval scenarios under `yaml/wix-manage-evals/` may define a top-level `maxTokens` value. The GitHub Actions eval gate compares that budget against the PR run's total tokens for the scenario and fails the PR check when the budget is exceeded. This gate-owned field is separate from `llm_judge.maxTokens`, which only configures the judge assertion.
+To report a problem with a skill or suggest a change, [open an issue](https://github.com/wix/skills/issues/new). Pull requests are not merged in this repository; accepted changes are made by the maintainers. See [CONTRIBUTING.md](CONTRIBUTING.md) for what makes a useful report.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.31.2",
+  "version": "1.33.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

@@ -33,8 +33,8 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
   - [ ] **🛑 Component Docs Gate (MANDATORY, dashboard UI only):** For each patterns symbol you are about to write, decided **from the lookup output** which single artifact answers the question you actually have — the import line, an example, or the props file — and read only that one, per [Component Selection Order](#component-selection-order)'s "the short version". State which artifact you read per symbol, and why, before the first line of JSX. Reading a doc *and* its bundle for the same symbol, or opening a page for an import line the lookup already gave you, is the failure this gate exists to prevent.
 
     For the object `useTableCollection()` returns, read [TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md) — a state object you receive rather than construct, whose members are unobvious and several plausible ones absent.
-- [ ] **Step 3:** Checked API references; used MCP discovery only for gaps
-  - [ ] **Dashboard page over Wix data:** located the method and verified every mapped field against the installed SDK's own declaration first — see [DATA_SOURCES.md](references/dashboard-page/DATA_SOURCES.md), and [QUERY_AND_PAGING.md](references/dashboard-page/QUERY_AND_PAGING.md) before writing `fetchData`. A field marked `@deprecated` still compiles and renders something plausible and wrong.
+- [ ] **Step 3:** Checked API references; resolved every vertical entity in **one** `sdk-lookup.cjs` call ([SDK lookup](#sdk-lookup-one-call-for-every-vertical-entity)); used the docs only for what it does not print
+  - [ ] **Dashboard page over Wix data:** took the method from the lookup and verified every mapped field against the declaration it points to (`type … file:line`) — see [DATA_SOURCES.md](references/dashboard-page/DATA_SOURCES.md), and [QUERY_AND_PAGING.md](references/dashboard-page/QUERY_AND_PAGING.md) before writing `fetchData`. A field marked `@deprecated` still compiles and renders something plausible and wrong.
   - [ ] **Vertical SDK prerequisites — for every `@wix/*` vertical the page touches, including one added later:** confirmed the package is actually a dependency (installed it if not), and noted the Dev Center permission scope the read needs — a missing scope produces a page that builds, mounts and shows nothing. Both in [DATA_SOURCES.md](references/dashboard-page/DATA_SOURCES.md#two-things-to-settle-before-you-write-the-page); the scope goes under [Manual Steps Required](#-manual-steps-required). **A second vertical added during Step 4b needs this check too, and its failure must not take down the page** — see [A second vertical is a second scope](references/dashboard-page/DATA_SOURCES.md#a-second-vertical-is-a-second-scope).
   - [ ] **Modelled the call on the SDK, not the REST page:** namespace name, `_id` vs `id`, no `ReturnType` on overloaded methods, no `hasNext` on `PagingMetadataV2` — see [The SDK is not the REST API](references/dashboard-page/DATA_SOURCES.md#the-sdk-is-not-the-rest-api).
   - [ ] 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))
@@ -43,6 +43,7 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
   - [ ] **Compile as you go:** ran `npx tsc --noEmit` after the first file that imports `@wix/patterns`, not only at Step 5. Patterns' state and filter APIs are the most common source of errors, and finding twenty of them in one batch after the page is written costs far more than finding two early.
   - [ ] **🛑 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.
+  - [ ] **When rendering images, for every collection source:** followed [IMAGE_RENDERING.md](references/dashboard-page/IMAGE_RENDERING.md). Keep schema image renderers and raw form values; custom WDS/native images must normalize the actual SDK image value before choosing a fallback or empty state. SDK decoding can replace REST image objects with URI strings. Verify loaded collection thumbnails and detail previews, or report browser verification as unavailable.
   - [ ] WDS: the design-system stylesheets are imported in exactly one place per app — `BusinessManagerTheme.tsx` for a dashboard surface (see the next item), or the main component entry file for a site/editor extension. Never in child, tab or helper files, and never twice.
   - [ ] **🛑 Business Manager theme (every dashboard surface — page, modal AND plugin):** wrote `BusinessManagerTheme.tsx` once (both stylesheets, including `themes/odeditor.global.css`, plus `WixDesignSystemProvider` → `WixDesignSystemIconThemeProvider` → `IconThemeProvider theme="odeditor"` → `WixDesignSystemDefaultPropsProvider`), and wrapped **each** extension's root in it — above `WixPatternsProvider` and above `CustomModalLayout`. Every extension is a separate iframe that inherits none of the redesign, so theming the page does nothing for a modal it opens or a plugin in a slot; each one needs its own wrapper. Also: every icon from `@wix/wix-ui-icons-common/lazy`, and `--wds-*` tokens or `skin`/`size` props rather than hardcoded colours, font sizes or inline `style` ([BUSINESS_MANAGER_TOKENS.md](references/BUSINESS_MANAGER_TOKENS.md) — note the theme rebases the `SP*` spacing unit from 6px to 4px). `tsc`, `wix build` and `wix preview` all pass on an unthemed surface — only looking at it catches this. See [BUSINESS_MANAGER_THEME.md](references/BUSINESS_MANAGER_THEME.md).
 - [ ] **Step 4c (dashboard page UI only):** Re-opened and read the page file(s) just written — not recalled intent — and confirmed against the actual code: no `SummaryBar` unless the request asked for one, a routed drill-in (`navigateToEntityPage`) for every row and no `SidePanel` used as one, every declared filter name also appearing inside `fetchData`, and — for every template with a router — the entry file both passes and guards `location`. See [UX Completeness Self-Audit](#step-4c-ux-completeness-self-audit).
@@ -219,6 +220,7 @@ Use a Dashboard Modal for dialogs that neither write nor display a listed record
 | Draft template — start here for any dashboard page: finding, copying and adapting the package's page templates | [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md) |
 | The state object `useTableCollection()` returns | [TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md) |
 | Finding the SDK method and field names behind a page | [DATA_SOURCES.md](references/dashboard-page/DATA_SOURCES.md) |
+| Images from any collection source — CMS, vertical SDKs, and custom data | [IMAGE_RENDERING.md](references/dashboard-page/IMAGE_RENDERING.md) |
 | Filter paths, WQL operators and cursor paging | [QUERY_AND_PAGING.md](references/dashboard-page/QUERY_AND_PAGING.md) |
 
 ---
@@ -227,7 +229,7 @@ Use a Dashboard Modal for dialogs that neither write nor display a listed record
 
 **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).
 
-Find the entity the user mentioned in the [entity → SDK module map](references/SDK_MODULE_MAP.md) and use that package. 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.
+Find the entity the user mentioned in the [entity → SDK module map](references/SDK_MODULE_MAP.md) and use that package; the [SDK lookup](#sdk-lookup-one-call-for-every-vertical-entity) then names the namespace and method. If the entity isn't listed and the lookup finds nothing, run `SearchWixSDKDocumentation` for it — **never conclude CMS without one of the two**. CMS is only for data your app itself introduces (configuration, rules, app-specific records) that no Wix app manages.
 
 **SDK types:** access them through the namespace you import, as `<namespace>.<TypeName>`, using any type name shown in the docs — never import a type by name from the `@wix/<pkg>` root.
 
@@ -237,6 +239,8 @@ const rows: orders.Order[] = [];              // ✅
 // import type { Order } from '@wix/ecom';    // ❌ has no exported member 'Order'
 ```
 
+**A map keyed by an SDK enum:** fields are typed `<Enum>WithLiterals` (the enum or its string values). `Partial<Record<bookings.BookingStatusWithLiterals, V>>` cannot be indexed by a status (TS7053). Use `Record<…WithLiterals, V>` with an entry for every value, or key a partial map by the string values: `` Partial<Record<`${bookings.BookingStatus}`, V>> ``.
+
 ---
 
 ## Data Collection Inference
@@ -307,14 +311,14 @@ Who the extension runs as decides everything below — the Category column in [E
 
 **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.
+- **Acts for the current visitor or member** — their cart, checkout, booking, order, reservation, or profile: `currentCartV2.*`, `cartV2.placeOrder`, `bookings.createBooking`, `members.getCurrentMember` (REST *Get My Member*), 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.
+**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 (the SDK lookup prints it as the method's `note`), 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.
+Two signals never settle it: the scope name — the methods whose scope name points the wrong way are rules in [sdk-curated.json](scripts/sdk-curated.json), which the [SDK lookup](#sdk-lookup-one-call-for-every-vertical-entity) prints as `note` — 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.
 
@@ -344,7 +348,7 @@ Use the Extension Types Reference Table and decision content above. State extens
 
 ### Step 3: Read Extension Reference, Check API References, Then Discover (if needed)
 
-**Workflow: Read extension reference → Check API references → Use MCP only for gaps.**
+**Workflow: Read extension reference → Check API references → SDK lookup for vertical entities → docs only for what the lookup does not print.**
 
 1. **Read the extension reference file** for the chosen extension type from the table above
 2. **Identify required APIs** from user requirements
@@ -355,23 +359,23 @@ Use the Extension Types Reference Table and decision content above. State extens
    - Service Plugin SPIs → read `references/SERVICE_PLUGIN.md` together with the matching `references/service-plugin/<NAME>.md` leaf
    - App Tools (AI assistant tools) → read `references/APP_TOOLS.md`; it links to `references/app-tools/TOOLS.md` (declaration) and `references/service-plugin/TOOLS_PROVIDER.md` (handler)
 4. **Verify the specific method/event exists** in references
-5. **ONLY use MCP discovery if NOT found** in reference files
+5. **For vertical entities, run the [SDK lookup](#sdk-lookup-one-call-for-every-vertical-entity)** once, with every entity; use MCP discovery only for what neither the references nor the lookup answer
 
 **Platform APIs (never discover - in references):**
 - 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 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
+- 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, install it, then get the namespace and method from the [SDK lookup](#sdk-lookup-one-call-for-every-vertical-entity)
 
 **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              |
+| "Display store products"             | ✅ YES (SDK lookup)                  | Wix Stores API — **include Stores Versioning reference** |
+| "Dashboard for orders / refunds"     | ✅ YES (SDK lookup)                  | Wix eCommerce API (`@wix/ecom`) — **NEVER a CMS collection** |
+| "Show booking calendar"              | ✅ YES (SDK lookup)                  | Wix Bookings API (`@wix/bookings`); SPI leaves cover only service plugins |
+| "Send emails to users"               | ✅ YES (SDK lookup, then MCP)        | Wix Triggered Emails not in reference files         |
+| "Get member info"                    | ✅ YES (SDK lookup)                  | Wix Members API not in reference files              |
 | "Listen for cart events"             | Check `COMMON-EVENTS.md`             | MCP discovery only if event missing in reference    |
 | "Store data in collection"           | WIX_DATA.md ✅ Found                 | ❌ Skip discovery (covered by reference)             |
 | "Create CMS collections for my app"  | Data Collection reference            | ❌ Skip discovery (covered by dedicated reference)   |
@@ -381,7 +385,27 @@ Use the Extension Types Reference Table and decision content above. State extens
 | "Settings page with form inputs"     | N/A (UI only, no external API)       | ❌ Skip discovery                                   |
 | "Dashboard page with local state"    | N/A (no external API)                | ❌ Skip discovery                                   |
 
-**MCP Tools for discovery (when needed):**
+#### SDK lookup: one call for every vertical entity
+
+```bash
+node <this-skill-dir>/scripts/sdk-lookup.cjs contacts orders --intent search   # search | read | write | event | all
+```
+
+Run it from the app directory, after the vertical packages are installed, with **every entity the feature touches in one call**. Pick the intent from the feature, once. A dashboard collection page edits its records by default ([DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md#2-choose-then-read-the-chosen-templates-page)), so it uses `all`: that holds the `search` and `write` lines, the search methods first. Use `search` (with a search box) or `read` only for a read-only page, and `write` for a feature that only writes. Do not pipe the output through `head`. Per entity it prints:
+
+- the namespace to use and why (a curated rule; within one package, a `search*` method for a search, then the highest API version; across packages that export the same name, the module map's package, else the package named after it), and the other namespaces — across packages, each with its entity description, so switch when the feature matches another one;
+- the import line;
+- `shape`: the one call to write for the intent, with its reason and, for a search, where the term goes;
+- each method for the intent, with its call shape (`search`, `query-builder`, `query`, …), permission, required fields (`revision`) and its docs notes (`note`, with an update's field rules: what a missing field does, and how to clear one); `fieldsets` when an option decides which fields come back (members default to `PUBLIC`, without `loginEmail` or `contact`: ask for the set that holds every field you show); for a search, query or list method also `arg` and `returns`, the keys of its argument (`cursorPaging`, `filter`, `sort`, `search`) and of its response (`pagingMetadata.cursors.next`); a filter list only when the package declares one (otherwise the method docs page lists the fields) — not who may call it: that stays with [Identity and Elevation Requirement](#identity-and-elevation-requirement);
+- the entity type as `file:line` — the declaration to verify fields against ([DATA_SOURCES.md](references/dashboard-page/DATA_SOURCES.md#confirming-a-field--the-part-that-ships-bugs));
+- each method's own declaration as `decl file:line` — read the types behind `arg` and `returns` there, not by searching the typings;
+- the curated rules for the entity (`note`), such as the Stores V1/V3 check.
+
+Take the namespace, the method and the call shape from its output; do not re-derive them from the typings, and follow the lines under `shape`. When the lookup prints `site`, the choice depends on the site (Stores: call `getCatalogVersion()` and support both). `not installed` prints the install command: install, then run the lookup again. A name it does not know exits 1 with near matches.
+
+It prints each search and query method's closed filter list (free-text fields, operators per field, sort) from the package's own declarations. It prints a method's **permission scope ID** only when the package declares it; when the output says `scope: not in the package`, get the scope from the method's docs page (the next list).
+
+**MCP Tools for discovery (for what the lookup does not print):**
 
 - `SearchWixSDKDocumentation` - SDK methods and APIs (**Always use maxResults: 5**)
 - `ReadFullDocsMethodSchema` - Full type schema for a specific SDK method (parameters, return type, permissions)

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

@@ -227,7 +227,7 @@ caller before invoking an elevated method. Use `httpClient.fetchWithAuth()` to
 send caller identity; a bare `fetch` does not supply that identity. Authentication
 alone does not grant permission to perform the operation.
 
-Dashboard callers are Wix users. For site/editor callers, `members.getMyMember()`
+Dashboard callers are Wix users. For site/editor callers, `members.getCurrentMember()`
 identifies a logged-in member but does not prove site ownership. Owner-only
 operations belong in a dashboard extension; do not expose them to site visitors
 on the assumption that member authentication proves ownership.

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

@@ -19,6 +19,24 @@ Keep the Wix CLI scaffold and file roles:
 
 Supplementary files are allowed; keep scaffold roles intact.
 
+## Required Reading (blocking)
+
+Before writing code, open and read in full every reference in the matching
+row. An unopened one is a failed run. Open paths directly; never skim or
+grep instead.
+
+| 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), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md), [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md), [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
+| Editing React or JSX | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) |
+| Changing public contract, semantic root, or named parts | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) |
+| Changing public data props or elected root global class | [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
+| Item array where only one body is visible | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Creating or changing CSS | [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md) |
+| Creating or changing layout/content | [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
+| Root direction contract, direction-sensitive behavior, or `ReactNode` slot | [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) |
+| Sizing, installation, or manifest overrides | [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
+
 ## Workflow
 
 1. **Scaffold only when creating.** Run in the Wix app (`wix.config.json`).
@@ -31,9 +49,9 @@ Supplementary files are allowed; keep scaffold roles intact.
    Never rerun the scaffold for an existing component.
    Write a meaningful `description` in 1-2 plain sentences (max 300 chars): what
    the user sees, when to use it, and capabilities that affect that choice.
-   Don't repeat the component name or add implementation details.
+   Don't repeat the name or add implementation details.
 
-2. **Run the dependency preflight.** Check required packages:
+2. **Run the dependency preflight.**
 
    ```bash
    deps=(@wix/react-component-schema @wix/react-component-utils @wix/editor-react-types)
@@ -56,15 +74,15 @@ Supplementary files are allowed; keep scaffold roles intact.
    }
    ```
 
-3. **Plan.** Identify props, root, parts, and states; read routed references.
-   Use the scaffold and references before package declarations; probe an API
-   only when undocumented or a typecheck fails.
+3. **Plan.** Identify props, root, parts, and states; open all required references first.
+   Use them and the scaffold before inspecting package declarations; inspect
+   only for undocumented APIs or fields, or typecheck failures. Declarations
+   govern API shapes; retain editor rules.
 
 4. **Implement.** Keep props, logic, and styles in their scaffolded editable
-   files. Format edited source files with the app's configured formatter before
-   checking formatting. Never edit or format `*.generated.ts`.
+   files. Format edited source files with the app's formatter. Never edit or format `*.generated.ts`.
 
-5. **Run the accessibility review.** Once the JSX is complete, run from the
+5. **Run the accessibility review (mandatory).** Once the JSX is complete, run from the
    same folder (`<SKILL_ROOT>` is the directory containing the active `SKILL.md`):
 
    ```bash
@@ -88,43 +106,30 @@ Supplementary files are allowed; keep scaffold roles intact.
    ```
 
    Run `npx tsc --noEmit`, relevant tests/lint, and the accessibility review.
-   If later edits affect a check, rerun that
-   check. Inspect the manifest when generated; never hand-repair it. Diagnose
-   failures with
+   If later edits affect a check, rerun that check. Inspect the manifest when generated; never hand-repair it.
+   Diagnose failures with
    [`editor-react-component/MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md).
 
    For creation/layout changes, complete the routed overflow resize review.
 
-8. **Report.** Summarize files, checks, blockers, and checks that could not run.
+8. **Report.** Summarize files, checks, blockers, unrun checks.
+   List required references as read/unread; read any unread one and fix first.
 
 ## Reference Policy
 
-Read only matched references. Preserve unrelated behavior. `SKILL.md` routes;
-references are leaves.
-
-### Required References
-
-| Scope | Required references |
-| --- | --- |
-| Creating a component | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md), [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
-| Editing React or JSX | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) |
-| Changing public contract, semantic root, or named parts | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) |
-| Changing public data props or elected root global class | [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
-| Item array where only one body is visible | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
-| Creating or changing CSS | [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md) |
-| Creating or changing layout/content | [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
-| Root direction contract, direction-sensitive behavior, or `ReactNode` slot | [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) |
-| Sizing, installation, or manifest overrides | [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
+Read every required reference for the matched scope, optional ones only on
+trigger. Preserve unrelated behavior. References are leaves.
 
 ### Optional References
 
 | Trigger | Read |
 | --- | --- |
-| Interactive/selectable part, custom state, or open/collapse toggle | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Interactive/selectable part, custom state, or open/reveal toggle | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Disabled or invalid state | [`DISABLED-INVALID.md`](editor-react-component/DISABLED-INVALID.md) |
 | Creating interactive components or changing interactions/callbacks | [`FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) |
 | Browser APIs, effects, or time-dependent output | [`SSR.md`](editor-react-component/SSR.md) |
 | Non-established CSS feature or DOM API, or user asks for one by name | [`BROWSER-SUPPORT.md`](editor-react-component/BROWSER-SUPPORT.md) |
-| `npx wix build` or manifest generation exits with an error | [`MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md) |
+| `npx wix build` or manifest generation errors or warns | [`MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md) |
 | Animation, video, carousel, or other playable/looped/autoplaying content | [`ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
 | Site/runtime/editor context hooks needed | [`SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) (+ [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) when design-mode behavior differs) |
 | Branded, themed, or brand-aware component requested | [`BRANDED-COMPONENTS.md`](editor-react-component/BRANDED-COMPONENTS.md) |
@@ -136,27 +141,24 @@ references are leaves.
 - Elected root: `dir={direction}`, fallback-direction class, logical CSS for
   direction-sensitive layout.
 - Deterministic render; no browser globals during render.
-- Explicit foreground colors need a known contrasting background; transparent
-  roots inherit from the host.
-- Baseline Widely Available CSS/DOM only, or supported fallbacks.
+- Baseline Widely Available CSS/DOM only, or fallbacks.
 - Accessibility per part, per [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md):
   read only `a11y.ariaLabel`, and only for a control without a visible name;
   never spread the `a11y` object or add one-off ARIA props.
 - Named parts: global class, module class, and `elementProps` (root uses
   top-level props).
-- Native design states: pair selectors with injected modifiers; keep non-input
-  `:focus-visible` standalone unless editable focus is requested; toggle custom
-  state classes from data, each with a matching `:global()` rule.
-- Open/collapse components: expose a props-only `isOpen: ElementState<boolean>`
-  root state and sync internal state from it.
+- Every visible text: a text prop plus a named part; no JSX text literals.
+- Native design states: interactive elements only, never a non-interactive root
+  or part; pair selectors with injected modifiers; toggle custom state classes
+  from data, each with a matching `:global()` rule.
+- Open/close/reveal: props-only root
+  `isOpen: ElementState<boolean>` synced to state; module classes, no `--open` class.
 - Single-visible-body arrays: `name` per item, `ActiveItemIndex<'prop'>`, render
   all bodies, hide inactive accessibly.
+- No arrays inside array items; keep group fields flat (no object props).
 - Autoplay/loop: play/pause control, honor reduced motion, suppress autoplay in
   editor design mode.
-- Resizable layout: keep required content usable at 320px. Reflow visible
-  groups inside their page and cap track minima with
-  `minmax(min(100%, <minimum>), 1fr)`. Follow [`OVERFLOW.md`](editor-react-component/OVERFLOW.md).
-- Preview composition, inline or through variables:
-  `withDefaults(withFallbackPlaceholder(PreviewOrComponent, options), defaultProps)`.
-  Keep `withDefaults` outermost; use one crucial data field and match the root
-  class.
+- Resizable layout: keep required content usable at 320px, per
+  [`OVERFLOW.md`](editor-react-component/OVERFLOW.md).
+- Preview: `withDefaults` outermost, one crucial data field, matching root
+  class, per [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md).

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

@@ -43,4 +43,4 @@ Data owned by an existing Wix business app is read and written through that app'
 
 Types from these packages are accessed as `<namespace>.<TypeName>` — see [SDK types](../SKILL.md#sdk-first-rule-existing-wix-app-data-is-never-cms).
 
-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.
+This map names the package, never the namespace or the method: install the package, then run the [SDK lookup](../SKILL.md#sdk-lookup-one-call-for-every-vertical-entity) for the namespace and method. If the entity isn't listed and the lookup finds nothing, run `SearchWixSDKDocumentation` for it — **never conclude CMS without one of the two**. CMS is only for data your app itself introduces (configuration, rules, app-specific records) that no Wix app manages.

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

@@ -101,13 +101,35 @@ For the full table see the [Catalog V1 to V3 Migration Guide](https://dev.wix.co
 | `manageVariants: false` (customizations) | `modifiers[i]` |
 | `collectionIds[i]` | `directCategories[i].id` |
 | `ribbon`, `brand` (string) | `ribbon.name`, `brand.name` (managed via `ribbonsV3` / `brandsV3`) |
-| `media.mainMedia.image.url` (main image URL) | `media.main.image ?? media.main.url` — in V3, `ProductMedia.image` is a `string` (Wix-hosted URL), `url` is a `string` (external URL); check both |
+| `media.mainMedia.image.url` (main image URL) | `media.main.image` can be a `wix:image://` URI. Use `media.main.url` only for image media; it can otherwise describe a video. See [Image rendering](dashboard-page/IMAGE_RENDERING.md) for browser URL conversion. |
 | `lastUpdated` | `updatedDate` |
 
 **Pricing model** — V1 had a `discount` object; V3 removed it. Discounts are now expressed by the relationship between two fields on the variant: `actualPrice` (required, what the customer pays) vs `compareAtPrice` (optional, original price shown struck through). With discount: V1 `price`/`discountedPrice` → V3 `compareAtPrice`/`actualPrice`. Without discount: V1 `price` → V3 `actualPrice`, leave `compareAtPrice` empty.
 
 ---
 
+## Display SDK product images
+
+In the V3 SDK, `media.main.image` is a **string**, including Wix image URIs. The raw REST
+response can show an image object instead: `media.main.image.url` from that response is not
+the SDK access path. Pass the whole SDK image value to `toBrowserImageUrl` from
+[IMAGE_RENDERING.md](dashboard-page/IMAGE_RENDERING.md), then choose a fallback:
+
+```typescript
+import { productsV3 } from '@wix/stores';
+
+export function productImageUrl(product: productsV3.V3Product): string | undefined {
+  const main = product.media?.main;
+  return toBrowserImageUrl(main?.image)
+    || (main?.mediaType === 'IMAGE' ? toBrowserImageUrl(main.url) : undefined)
+    || toBrowserImageUrl(main?.thumbnail?.url);
+}
+```
+
+Use this mapping in both views. Collection thumbnails may prefer normalized `main.thumbnail.url`.
+A video's thumbnail is an image; its own `url` is not. Request
+`'THUMBNAIL'` in **both** list and detail calls; it is not returned by default.
+
 ## Webhooks
 
 **Subscribe to BOTH V1 and V3 webhooks** so your app handles every site.
@@ -130,4 +152,4 @@ Payload changes: V1 `changedFields` → V3 `modifiedFields`. Top-level `entityId
 - [stores/INVENTORY.md](stores/INVENTORY.md) — inventory read and write operations
 - [stores/CATEGORIES.md](stores/CATEGORIES.md) — collections (V1) ↔ categories (V3)
 
-For methods not listed here, use `SearchWixSDKDocumentation` then `ReadFullDocsMethodSchema` (use `ReadFullDocsArticle` only for prose). Always return the required permission scopes to the user.
+For methods not listed here, run the [SDK lookup](../SKILL.md#sdk-lookup-one-call-for-every-vertical-entity) for `products` (it prints both namespaces and their methods), then `ReadFullDocsMethodSchema` for its permission scope (and the filter list if the lookup printed none). Always return the required permission scopes to the user.

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

@@ -1,8 +1,9 @@
 # Finding the real SDK shape behind a dashboard page
 
 > **Scope.** [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md) gives you the page; this file finds the method
-> and *field names* for its data. Read it before Step 3's MCP discovery. The installed package is
-> the version your code compiles against.
+> and *field names* for its data. The [SDK lookup](../../SKILL.md#sdk-lookup-one-call-for-every-vertical-entity)
+> gives the namespace, the method and the entity's `file:line`; this file checks the fields there.
+> The installed package is the version your code compiles against.
 
 ## Where the types actually live
 
@@ -18,12 +19,10 @@ node_modules/@wix/auto_sdk_ecom_orders/build/es/
   ecom-v1-order-orders.universal-<hash>.d.mts        # the domain entities
 ```
 
-Three consequences worth knowing before you start grepping:
+Three consequences:
 
-1. **The directory name is not the namespace name.** Namespaces are camelCase, package directories
-   are kebab-case — `extendedBookings` lives in `auto_sdk_bookings_extended-bookings`, not
-   `auto_sdk_bookings_extendedBookings`. Don't derive one from the other; list them:
-   `ls node_modules/@wix | grep <vertical>`.
+1. **The directory name is not the namespace name.** `extendedBookings` lives in
+   `auto_sdk_bookings_extended-bookings`. Don't derive one from the other; the SDK lookup maps them.
 2. **The entity is not always in `index.typings.d.mts`.** `Order`, `Refund`, `Service` live in the
    hashed `*.universal-*.d.mts` when the package has one. The hash changes between versions, so glob
    for it, never hard-code it, and fall back to `index.typings.d.mts` when no universal file exists.
@@ -34,12 +33,8 @@ Three consequences worth knowing before you start grepping:
 
 ## Confirming a method
 
-```bash
-E=node_modules/@wix/auto_sdk_ecom_order-transactions/build/es
-grep -oE "^declare function [a-zA-Z]+" $E/index.d.mts
-```
-
-Prefer this to recall: `listTransactionsForMultipleOrders(orderIds: string[])` and
+The SDK lookup lists every method of the namespace (`other methods:` outside the intent). Prefer
+its list to recall: `listTransactionsForMultipleOrders(orderIds: string[])` and
 `listTransactionsForSingleOrder` differ by exactly the shape a collection page needs, and only one
 of them avoids an N+1 across the visible page.
 
@@ -50,6 +45,7 @@ the uncertain ones, **in one pass**. List the types and fields first, then print
 per file. A grep per question is a round trip each:
 
 ```bash
+E=node_modules/@wix/auto_sdk_ecom_order-transactions/build/es
 awk '/^(interface|type) (Payment|RegularPaymentDetails)[ <{=]/,/^}/' $E/index.typings.d.mts
 ```
 

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

@@ -0,0 +1,61 @@
+# Images in collection and detail pages
+
+This applies to every data source: CMS, Stores, Bookings, and other SDK or custom collections.
+An image value is not necessarily a browser URL. A `wix:image://` URI passed directly to WDS
+`Image` or a native `<img>` produces a broken image even when the page builds and its data loads.
+
+## Use the field renderer when the schema supplies one
+
+Keep the source's image field type and original value when using schema-driven Patterns
+collections or entity fields. Their image renderers handle the supported URI and structured
+image formats. Do not replace them with a custom WDS renderer just to show an image.
+
+## Custom image rendering
+
+Read the source's image field declaration before mapping it. Select the image value, not the
+whole media container: a media item can also be a video or document. Check its media type before
+using a generic `url` as an image, or use its documented image thumbnail field.
+
+Use the installed SDK's return type, not the raw REST response shape. SDK decoding can turn a
+REST image object into a `wix:image://` string. Reading `.url` from that string returns
+`undefined`, so the page shows its empty state without ever rendering an image. Do not copy
+REST field access into an SDK mapper or hide this mismatch with a type assertion.
+
+For custom WDS or native image rendering, extract a string from the image value and convert Wix
+URIs with the documented SDK helper. Preserve ordinary HTTP(S) URLs and missing values:
+
+```typescript
+import { media } from '@wix/sdk';
+
+type ImageValue = string | { uri?: string; url?: string } | null | undefined;
+
+export function toBrowserImageUrl(value: ImageValue): string | undefined {
+  const source = typeof value === 'string' ? value : value?.uri || value?.url;
+  return source?.startsWith('wix:image://')
+    ? media.getImageUrl(source).url
+    : source;
+}
+```
+
+This accepts image URI strings and structured image values with `uri` or `url`. Extract nested
+image fields according to their own types before calling it. Do not stringify a media object,
+hand-build a CDN URL, or send a video URI to an image renderer.
+
+Use the derived URL in collection thumbnails, grid cards, and detail previews. Show an empty
+state when it is absent. Keep it separate from the original entity and form value: saves must
+retain the source's image format, alt text, dimensions, and other metadata.
+
+Normalize the source image value before choosing a fallback or an empty state, in both the
+list and the detail fetch paths. A working thumbnail does not establish that the detail query
+returns the same fields. Request any fields required by the fallback too. Stores' mapping is
+shown in [STORES_VERSIONING.md](../STORES_VERSIONING.md#display-sdk-product-images).
+
+Verify a Wix-hosted image in both the collection and detail views, an external image URL, and
+an item without an image. When browser access is available, open a row and check that its image
+actually loads (`complete` and `naturalWidth > 0`), rather than only checking that an `<img>`
+exists. If a known image shows an empty state, trace the SDK value through its mapper before
+reporting completion. A successful build or a raw REST response does not verify the rendered
+SDK result. If browser access is unavailable, report image rendering as unverified.
+
+See [Work with Wix Media](https://dev.wix.com/docs/api-reference/articles/sdk-setup-and-usage/work-with-wix-media)
+for the SDK URI format and conversion API.