@wix/agent-skills 1.15.0 → 1.16.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
@@ -91,6 +91,10 @@ When a major bump is required (a breaking change in the underlying `wix-cli`), t
 
 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.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding new skills.

package/package.json

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

@@ -77,12 +77,13 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
    - Anywhere on site (with editor manifest) → Editor React component
    - Wix business solution page → Site Plugin
    - During business flow → Service Plugin
+   - Exposing tools to the Wix AI assistant → App Tools
    - After event occurs → Backend Event Extension
 
 ## Decision Flow (Not sure?)
 
 - **Admin:** Single-collection CRUD admin page? → **Auto Patterns Dashboard (DEFAULT)**. Custom React page (multi-collection / custom logic / embedded scripts / external APIs / explicit user request)? → Dashboard Page. Need popup/form? → Dashboard Modal. Extending Wix app dashboard with a visual widget? → Dashboard Plugin. Adding a menu item to a Wix app dashboard's more-actions or bulk-actions menu? → Dashboard Menu Plugin. **Modal constraint:** Dashboard Pages cannot use `<Modal />`; use a separate Dashboard Modal extension and `dashboard.openModal()`.
-- **Backend:** During business flow (checkout/shipping/tax)? → Service Plugin. 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 data? → Data Collection.
 - **Site:** User places anywhere (standalone)? → custom element widget. Editor React component with editor manifest (styling, content, elements)? → Editor React component. Fixed slot on Wix app page? → Site Plugin. Scripts/analytics only? → Embedded Script.
 
 ---
@@ -96,6 +97,7 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 | Dashboard Plugin | Dashboard | `DASHBOARD_PLUGIN` | [DASHBOARD_PLUGIN.md](references/DASHBOARD_PLUGIN.md) |
 | Dashboard Menu Plugin | Dashboard | `DASHBOARD_MENU_PLUGIN` | [DASHBOARD_MENU_PLUGIN.md](references/DASHBOARD_MENU_PLUGIN.md) |
 | Service Plugin | Backend | `SERVICE_PLUGIN` | [SERVICE_PLUGIN.md](references/SERVICE_PLUGIN.md) |
+| App Tools (AI assistant tools) | Backend | `APP_TOOLS`, then `SERVICE_PLUGIN` with `pluginType: TOOLS_PROVIDER_CONFIG` | [APP_TOOLS.md](references/APP_TOOLS.md) |
 | Backend Event Extension | Backend | `EVENT` | [BACKEND_EVENT.md](references/BACKEND_EVENT.md) |
 | Backend API | Backend | — (manual, see banner below) | [BACKEND_API.md](references/BACKEND_API.md) |
 | Data Collection | Backend | `DATA_COLLECTION` | [DATA_COLLECTION.md](references/DATA_COLLECTION.md) |
@@ -215,6 +217,7 @@ Use the Extension Types Reference Table and decision content above. State extens
    - Wix Data → `references/data-collection/WIX_DATA.md`
    - Dashboard SDK → `references/dashboard-page/DASHBOARD_API.md`
    - 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
 

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

@@ -0,0 +1,134 @@
+# App Tools — Overview
+
+App Tools lets your app expose custom tools that the Wix AI assistant can discover and invoke on behalf of site collaborators. It requires **two extensions working together**:
+
+| Extension | What it does | Reference |
+| --- | --- | --- |
+| `APP_TOOLS` | Declares your tools (names, descriptions, schemas) so the AI assistant knows they exist | [app-tools/TOOLS.md](app-tools/TOOLS.md) |
+| `TOOLS_PROVIDER_CONFIG` | The service plugin handler Wix calls at runtime when the AI assistant invokes a tool | [service-plugin/TOOLS_PROVIDER.md](service-plugin/TOOLS_PROVIDER.md) |
+
+## How they connect
+
+```
+Developer declares tools in APP_TOOLS
+        ↓
+AI assistant reads declarations to understand available tools
+        ↓
+User interacts with Wix AI assistant
+        ↓
+AI assistant invokes your toolsProvider service plugin (runTool handler)
+        ↓
+Your handler routes on methodName, runs business logic, returns response
+        ↓
+AI assistant uses the response to answer the user
+```
+
+The `methodName` field is the **linking key**: it must match exactly between the `APP_TOOLS` declaration and the `switch` (or routing map) in your `runTool` handler.
+
+## Quick Start
+
+### Step 1: Scaffold both extensions via the CLI
+
+> **Adding another tool to an existing setup?** Skip this step. Add the new tool entry to your existing `APP_TOOLS` `.extension.ts` file and add a matching `case` to your existing `runTool` handler — no new extensions needed.
+
+Run these two commands once — the CLI generates all files and updates `src/extensions.ts` automatically:
+
+```bash
+wix generate --params '{"extensionType":"APP_TOOLS","name":"my-tools"}'
+wix generate --params '{"extensionType":"SERVICE_PLUGIN","pluginType":"TOOLS_PROVIDER_CONFIG","name":"my-tools-provider"}'
+```
+
+### Step 2: Declare your tools (`APP_TOOLS`)
+
+Open the generated `src/extensions/backend/app-tools/my-tools/my-tools.extension.ts` and replace the stub tool with your own. Read [app-tools/TOOLS.md](app-tools/TOOLS.md) for the full field reference and constraints.
+
+```typescript
+import { extensions } from '@wix/astro/builders';
+
+export default extensions.appTools({
+  id: '<generated-uuid>',
+  name: 'my-tools',
+  tools: [
+    {
+      methodName: 'get-order-status',
+      description: 'Returns the current fulfillment status, shipping carrier, and tracking number for a customer order. Use this tool when a collaborator or customer asks where their order is, whether it has shipped, when it will arrive, or needs a tracking number. Requires a valid orderId.',
+      requestSchema: {
+        type: 'object',
+        properties: {
+          orderId: { type: 'string' }
+        },
+        required: ['orderId']
+      },
+      responseSchema: {
+        type: 'object',
+        properties: {
+          status: { type: 'string' }
+        }
+      },
+      activated: true
+    }
+  ]
+});
+```
+
+### Step 3: Implement the runtime handler (`TOOLS_PROVIDER_CONFIG`)
+
+Open the generated `src/extensions/backend/service-plugins/my-tools-provider/my-tools-provider.ts` and implement the `runTool` logic. Read [service-plugin/TOOLS_PROVIDER.md](service-plugin/TOOLS_PROVIDER.md) for the full implementation guide.
+
+```typescript
+import { toolsProvider } from '@wix/app-tools/service-plugins';
+
+toolsProvider.provideHandlers({
+  runTool: async ({ request, metadata }) => {
+    const { methodName, payload } = request;
+
+    switch (methodName) {
+      case 'get-order-status': {
+        const orderId = payload?.['orderId'];
+        if (typeof orderId !== 'string' || !orderId) {
+          throw new Error('orderId is required');
+        }
+        // your logic here
+        return { response: { status: 'shipped' } };
+      }
+      default:
+        throw new Error(`Unknown tool: ${methodName}`);
+    }
+  }
+});
+```
+
+## Writing Good Descriptions
+
+The `description` field is the primary signal the AI assistant uses to decide whether your tool is relevant to a user's request. A one-liner like `"Returns order status"` works technically but limits relevance matching.
+
+Write descriptions as a short prompt — 2–4 sentences covering:
+1. **What it does** — the action and data it returns.
+2. **When to use it** — the user intents or phrases that should trigger it (e.g. "where is my order", "has this shipped", "tracking number").
+3. **Key inputs** — mention required parameters so the AI knows what to ask for.
+
+```
+// narrow — easy to miss
+'Returns order status.'
+
+// wide — reliably matched
+'Returns the current fulfillment status, shipping carrier, and tracking number for a customer order.
+Use this tool when a collaborator or customer asks where their order is, whether it has shipped,
+when it will arrive, or needs a tracking number. Requires a valid orderId.'
+```
+
+## Checklist
+
+- [ ] Tool declarations filled in the generated `.extension.ts` (replace the stub `myMethod`)
+- [ ] Set `activated: true` on every tool you want the AI assistant to invoke (`activated: false` tools are declared but never called)
+- [ ] `runTool` handler covers every `methodName` that has `activated: true`
+- [ ] Inputs validated defensively (schemas are advisory, not enforced by Wix)
+- [ ] Wix API calls wrapped with `auth.elevate` from `@wix/essentials`
+- [ ] App built (`wix build`) and released (`wix release`) — changes don't take effect until released
+
+## Important Notes
+
+- The `requestSchema` and `responseSchema` in `APP_TOOLS` are **advisory** — the AI assistant uses them for context. Wix does NOT validate the `payload` against the schema before calling your handler.
+- Only tools with `activated: true` are invoked by the AI assistant.
+- Both extensions must be registered and the app must be released before the feature is live.
+- The `methodName` must be unique within an `APP_TOOLS` extension (1–30 characters).

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

@@ -102,7 +102,7 @@ The CLI scaffolds the builder file with sensible defaults — edit it only to cu
 | Field | Type | Default | Purpose |
 |---|---|---|---|
 | `id` | UUID | generated | Extension ID. Don't change after scaffolding. |
-| `name` | string | from scaffold param | Display name. |
+| `name` | string | from scaffold param | Display name. **Maximum 30 characters** — longer names cause a platform validation error on deployment. |
 | `tagName` | kebab-case | derived from `folder` | Custom-element tag the widget is registered under. Used by the Editor and by `customElements.define()`. |
 | `width.defaultWidth` | number (px) | `450` | Initial width when the widget is added to a page. |
 | `width.allowStretch` | boolean | `true` | Whether the site owner can stretch the widget to the page width. |

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

@@ -75,16 +75,6 @@ When building a dashboard page to configure an embedded script, see [Dynamic Par
 - All parameters must be saved as strings (convert booleans/numbers to strings)
 - Use `withProviders` wrapper when dynamic parameters are present
 
-## Optional builder fields
-
-The CLI scaffolds the builder with `id`, `title`, `routePath`, and `component`. To customize sidebar placement and routing, edit the generated builder file to set:
-
-- `additionalRoutes` (string[]): extra routes leading to this page.
-- `sidebar.disabled` (boolean, default false): hide page from sidebar.
-- `sidebar.priority` (number): sidebar ordering; lower is higher priority.
-- `sidebar.whenActive.selectedPageId` (string): which page appears selected when this page is active.
-- `sidebar.whenActive.hideSidebar` (boolean): hide sidebar when this page is active.
-
 ## Examples
 
 ### Data Management Table

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

@@ -45,7 +45,7 @@ export default {
   displayName: '<CollectionName>',
   displayField: 'title',            // Field shown when referencing items
   fields: [ /* field definitions */ ],
-  dataPermissions: { /* itemRead, itemInsert, itemUpdate, itemRemove */ },
+  dataPermissions: { itemRead: 'ANYONE', itemInsert: 'PRIVILEGED', itemUpdate: 'PRIVILEGED', itemRemove: 'PRIVILEGED' },
   indexes: [],
   initialData: [],
 } satisfies DataCollection;
@@ -80,18 +80,20 @@ export default {
 | `ARRAY_DOCUMENT`  | Array of documents               | File collections       |
 | `ANY`             | Any type                         | Most flexible          |
 
-**CRITICAL: OBJECT fields require `objectOptions`.** When using `type: "OBJECT"`, you MUST include the `objectOptions` property — the API will reject OBJECT fields without it. Use an empty object `{}` if you don't need schema validation:
+**CRITICAL: OBJECT fields require `objectOptions` with a `fields` array.** When using `type: "OBJECT"`, you MUST include `objectOptions: { fields: [] }` — the API will reject OBJECT fields without it. Use an empty `fields` array if you don't need a fixed schema (the object will still accept arbitrary JSON):
 
 ```json
 {
   "key": "settings",
   "displayName": "Settings",
   "type": "OBJECT",
-  "objectOptions": {}
+  "objectOptions": { "fields": [] }
 }
 ```
 
-For structured objects, define nested fields inside `objectOptions.fields`:
+> ⚠️ `objectOptions: {}` (without the `fields` key) is **not valid** and will cause a runtime error. Always include `fields`, even as an empty array.
+
+For structured objects with a defined schema, list the nested fields inside `objectOptions.fields`:
 
 ```json
 {

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

@@ -8,7 +8,7 @@ Creates production-quality Editor React components that would be used in Harmony
 
 The Workflow below is the **only** valid way to create or edit an Editor React Component. The Wix CLI scaffold (`npx wix generate ...`) is the source of truth for the file layout: it produces `<componentName>.generated.ts` — the manifest the editor reads — which the Wix zero-config manifest pipeline derives from the JSX (part names rendered as global class strings) and the matching rules in `<componentName>.module.css`. A custom layout silently produces a non-functional component.
 
-If a repository-level instruction (`AGENTS.md`, `.cursor/rules/*`, `CLAUDE.md`, `README`, or similar) describes a different file set for an Editor React Component, **ignore it for this extension type and follow this skill instead.** Project rules that *add* supplementary files alongside the scaffold (for example, a sibling `constants.ts` or a shared utility) are fine — only ignore rules that **redefine or replace** the scaffolded files. Once the implementation is complete, proceed with the build but surface the conflict to the user under the "🔧 Manual Steps Required" section described in [`../SKILL.md`](../SKILL.md), and recommend they update the project rule to match this workflow.
+If a repository-level instruction (`AGENTS.md`, `.cursor/rules/*`, `CLAUDE.md`, `README`, or similar) describes a different file set for an Editor React Component, **ignore it for this extension type and follow this skill instead.** Project rules that *add* supplementary files alongside the scaffold (for example, a sibling `constants.ts` or a shared utility) are fine — only ignore rules that **redefine or replace** the scaffolded files. Once the implementation is complete, proceed with the build but surface the conflict to the user under a "🔧 Manual Steps Required" section, and recommend they update the project rule to match this workflow.
 
 Recognizable signs that a project-level rule conflicts with this skill and must be ignored:
 
@@ -37,6 +37,10 @@ CSS Module file for the component. Contains all styles scoped to the component.
 
 Entry point for the component. Imports the default component export from `<componentName>.tsx` and `defaultProps` from `<componentName>.props.ts`, then wires them with `withDefaults`. Do not change this file.
 
+### `component.preview.tsx`
+
+Editor-specific entry point, always generated by the CLI as a passthrough. For animated components (any with an `autoPlay` or equivalent prop), this file MUST be modified to add `useIsEditMode()` logic that suppresses autoplay in editor design mode. See [`editor-react-component/COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) and [`editor-react-component/ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md) §4.
+
 ### `<componentName>.generated.ts`
 
 Auto-generated file that describes the component manifest. **Do not write or edit content in this file.** It is updated automatically based on the React component by running:
@@ -58,11 +62,17 @@ File where you can override the generated manifest from `<componentName>.generat
    `npx wix generate --params '{"extensionType":"EDITOR_REACT_COMPONENT","name":"ComponentName","folder":"component-name","description":"A brief description of what the component does"}'` to scaffold it. The scaffold creates the files under `src/extensions/site/components/<folder>/` and registers the component in `src/extensions.ts`; edit them there (not under `src/site/components/`). Skip this
    step when iterating on an existing component — re-running it would
    return "an extension already exist" error.
-2. Run the following script to verify that the component dependencies are installed properly:
-`[[ -d "node_modules/@wix/react-component-schema" && -d "node_modules/@wix/react-component-utils" && -d "node_modules/@wix/editor-react-types" ]] || { d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/yarn.lock" ]; do d="${d%/*}"; done; { [ -f "$d/yarn.lock" ] && yarn add @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types; } || npm install @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types; }`
-3. Edit the generated react and CSS files in
-   `src/extensions/site/components/component-name/`.
-4. Run `npx wix build && npx wix generate manifest` so the editor picks up
+2. Run the following script to verify that all component creation and review dependencies are installed properly:
+`node -e "const fs=require('fs'),path=require('path'),ps=['@wix/react-component-schema','@wix/react-component-utils','@wix/editor-react-types','@babel/parser','@babel/traverse','@babel/types','eslint','eslint-plugin-jsx-a11y','@typescript-eslint/parser','@types/eslint-plugin-jsx-a11y'];const missing=ps.filter(p=>!(require.resolve.paths(p)||[]).some(d=>fs.existsSync(path.join(d,p,'package.json'))));if(missing.length){console.error('Missing dependencies: '+missing.join(', '));process.exit(1)}" || { d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/yarn.lock" ]; do d="${d%/*}"; done; if [ -f "$d/yarn.lock" ]; then yarn add @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && yarn add -D @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser @types/eslint-plugin-jsx-a11y; else npm install @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && npm install --save-dev @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser @types/eslint-plugin-jsx-a11y; fi; }`
+3. Edit the generated React and CSS files in
+   `src/extensions/site/components/component-name/`. Apply
+   [`editor-react-component/DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) while
+   authoring: every interactive named part must use interactive markup and
+   pair each native state selector with its prefixed global modifier (for
+   example, `.cta:global(.component-name-cta--hover), .cta:hover`). A
+   pseudo-class without the matching global modifier is incomplete.
+4. **MANDATORY** — execute the full A11y Review on the edited component per [`editor-react-component/A11Y-REVIEW.md`](editor-react-component/A11Y-REVIEW.md). Run both scanners over the component's `.tsx`/`.jsx` files, complete the Phase 3 manual semantic review, fix confirmed findings, and re-run the scanners after fixes. Reading the reference without executing these steps is not a review. Do not proceed to the build or report completion until the review is complete.
+5. Run `npx wix build && npx wix generate manifest` so the editor picks up
    the new/updated prop schema. This command regenerates manifest
    parts for all components. Design-states emission requires
    `@wix/cli` ≥ 1.1.215 (native and class-triggered states work from
@@ -70,7 +80,13 @@ File where you can override the generated manifest from `<componentName>.generat
    design state is missing from `<componentName>.generated.ts`, the installed
    CLI is older than required — tell the user, and let them decide whether to
    upgrade.
-5. Update `Component.extensions.ts` file according to [`editor-react-component/COMPONENT-CONFIGURATION.md`](editor-react-component/COMPONENT-CONFIGURATION.md)
+6. Update `Component.extensions.ts` file according to [`editor-react-component/COMPONENT-CONFIGURATION.md`](editor-react-component/COMPONENT-CONFIGURATION.md)
+
+If the component's primary content is a **playable animation** (Lottie/JSON,
+animated GIF/SVG, canvas/WebGL loop, video-like surface), or has an `autoPlay`
+(or equivalent) prop, it MUST include an on-stage play/pause control **and** the
+generated `component.preview.tsx` MUST be modified to suppress autoplay in the
+editor — follow [`editor-react-component/ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md).
 
 Reference: when modifying an _existing_ component, follow
 [`editor-react-component/EDIT-FLOW.md`](editor-react-component/EDIT-FLOW.md).
@@ -82,13 +98,18 @@ Core rules and workflow: [`editor-react-component/REACT-GUIDELINES.md`](editor-r
 Topic-focused references (rules + patterns + common mistakes in one place):
 
 - [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) — ARIA/a11y rules and patterns
+- [`editor-react-component/A11Y-REVIEW.md`](editor-react-component/A11Y-REVIEW.md) — Automated a11y scan + triage workflow to run after editing
 - [`editor-react-component/DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) — Which design states a part supports (heuristic) and how to author them
 - [`editor-react-component/DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) — RTL/LTR rules and patterns
 - [`editor-react-component/PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) — What should be a React prop vs CSS
 - [`editor-react-component/COMPONENT-API.md`](editor-react-component/COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props
+- [`editor-react-component/ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md) — Play/pause control and autoplay for animated/playable components
+- [`editor-react-component/COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) — Editor-specific entry point (`component.preview.tsx`), `useIsEditMode()`, when to modify
 - [`editor-react-component/REACT-PATTERNS.md`](editor-react-component/REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, remaining common mistakes
 
 ## CSS guidelines
 
 Reference: [`editor-react-component/CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md).
 
+For branded or themed components, also apply: [`editor-react-component/BRANDED-COMPONENTS.md`](editor-react-component/BRANDED-COMPONENTS.md).
+

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

@@ -7,16 +7,18 @@ Service plugins are a set of APIs defined by Wix that let you inject custom logi
 
 Use `wix generate --params` with `extensionType: SERVICE_PLUGIN`. `pluginType` is one of:
 
-| Value | SPI |
-| --- | --- |
-| `ECOM_ADDITIONAL_FEES` | Additional Fees |
-| `ECOM_SHIPPING_RATES` | Shipping Rates |
-| `ECOM_DISCOUNTS_TRIGGER` | Discount Triggers |
-| `ECOM_VALIDATIONS` | Validations |
-| `ECOM_PAYMENT_SETTINGS` | Payment Settings |
-| `GIFT_CARDS_PROVIDER` | Gift Cards Provider |
-| `STAFF_SORTING_PROVIDER` | Bookings Staff Sorting |
-| `REALTIME_PERMISSIONS_PROVIDER` | Realtime Permissions Provider |
+| Value | SPI | Singular |
+| --- | --- | --- |
+| `ECOM_ADDITIONAL_FEES` | Additional Fees | No |
+| `ECOM_SHIPPING_RATES` | Shipping Rates | **Yes** |
+| `ECOM_DISCOUNTS_TRIGGER` | Discount Triggers | **Yes** |
+| `ECOM_VALIDATIONS` | Validations | No |
+| `ECOM_PAYMENT_SETTINGS` | Payment Settings | No |
+| `GIFT_CARDS_PROVIDER` | Gift Cards Provider | **Yes** |
+| `STAFF_SORTING_PROVIDER` | Bookings Staff Sorting | No |
+| `REALTIME_PERMISSIONS_PROVIDER` | Realtime Permissions Provider | No |
+
+> **Singular types** — `ECOM_SHIPPING_RATES`, `ECOM_DISCOUNTS_TRIGGER`, and `GIFT_CARDS_PROVIDER` are **singular**: only one component of each type is allowed per app. Never scaffold or include two components of the same singular type in the same app payload.
 
 `name` must be lowercase alphanumeric + hyphens, max 19 characters. The CLI generates the folder, `plugin.ts`, the builder file, the UUID, and the `src/extensions.ts` registration with the appropriate builder method for the SPI type. Some SPI types (e.g., `ECOM_SHIPPING_RATES`) get a `description` placeholder field in the generated builder — replace it with your real copy.
 

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

@@ -1,4 +1,3 @@
-
 # Wix Stores Catalog Versioning (V1 / V3)
 
 Wix Stores has two catalog versions that are **NOT backwards compatible**. Apps **must support both** — single-version apps cannot list in the App Market and break on new sites.
@@ -82,214 +81,6 @@ Handle `STORES_NOT_INSTALLED` gracefully — return empty results, do not throw.
 
 ---
 
-## Copy-Paste Recipes
-
-Each recipe handles both versions. `V3Product` and V1 `Product` types are **not** re-exported from `@wix/stores` top-level — let TS infer or use structural types.
-
-### List products with pagination
-
-Both versions expose a fluent query builder, but the paging method differs:
-
-| Aspect | V1 (`products.queryProducts()`) | V3 (`productsV3.queryProducts()`) |
-|--------|--------------------------------|----------------------------------|
-| API style | Fluent builder: `.skip().limit().find()` | Fluent builder: `.skipTo(cursor).limit().find()` |
-| Pagination | Offset (`.skip(n)`) | Cursor (`.skipTo(cursor)`) |
-| Result `items` | `res.items` (V1 `Product[]`) | `res.items` (V3 `Product[]`) |
-| Total count | `res.totalCount` | **None** — V3 only has `cursors.next` + `hasNext()` |
-| `hasNext` | `res.hasNext()` (method) | `res.hasNext()` (method) |
-| Next cursor | n/a | `res.cursors.next` (string) |
-
-```typescript
-import { catalogVersioning, products, productsV3 } from '@wix/stores';
-
-export interface ProductsPage {
-  products: unknown[];        // narrow at call site
-  nextCursor: string | null;  // V3 only
-  hasNext: boolean;
-  totalCount: number | null;  // V1 only
-}
-
-export async function listProductsPage(
-  limit: number,
-  cursorOrSkip: string | number | undefined,
-): Promise<ProductsPage> {
-  const v = await getVersion();
-  if (v === 'STORES_NOT_INSTALLED') {
-    return { products: [], nextCursor: null, hasNext: false, totalCount: 0 };
-  }
-
-  if (v === 'V3_CATALOG') {
-    let builder = productsV3.queryProducts().limit(limit);
-    if (typeof cursorOrSkip === 'string') builder = builder.skipTo(cursorOrSkip);
-    // Do NOT chain a sort — see gotcha #10.
-    const res = await builder.find();
-    return {
-      products: res.items,
-      nextCursor: res.cursors.next ?? null,
-      hasNext: res.hasNext(),
-      totalCount: null,
-    };
-  }
-
-  const skip = typeof cursorOrSkip === 'number' ? cursorOrSkip : 0;
-  const res = await products.queryProducts().skip(skip).limit(limit).find();
-  return {
-    products: res.items,
-    nextCursor: null,
-    hasNext: res.hasNext(),
-    totalCount: res.totalCount ?? null,
-  };
-}
-```
-
-> **Two ways to call V3 `queryProducts`:** the canonical builder shown above, and a direct-call form `productsV3.queryProducts({ cursorPaging: { limit, cursor } })` returning a `Promise<{ products, pagingMetadata }>`. Both compile and run, but the builder is more idiomatic and matches V1's shape.
-
-### Display price/stock without fetching variants
-
-V3 `queryProducts` does not return variants. Read product-level rollup fields instead:
-
-```typescript
-function displayPrice(p: { actualPriceRange?: { minValue?: { amount?: string }; maxValue?: { amount?: string } } }): string {
-  const min = p.actualPriceRange?.minValue?.amount;
-  const max = p.actualPriceRange?.maxValue?.amount;
-  if (!min) return '—';
-  return max && max !== min ? `${min} – ${max}` : min;
-}
-
-function stockLabel(status: string | undefined): string {
-  switch (status) {
-    case 'IN_STOCK': return 'In Stock';
-    case 'OUT_OF_STOCK': return 'Out of Stock';
-    case 'PARTIALLY_OUT_OF_STOCK': return 'Limited';
-    case 'PREORDER': return 'Pre-order';
-    default: return '—';
-  }
-}
-// V1 path: product.stock.inventoryStatus  (same UPPER_SNAKE_CASE values)
-// V3 path: product.inventory.availabilityStatus (adds PREORDER)
-// SKU lives on the variant — show "—" in lists, or use Read-Only Variants API.
-```
-
-### Get a single product
-
-```typescript
-if (v === 'V3_CATALOG') {
-  const product = await productsV3.getProduct(id);  // returns Product directly
-  return product;
-}
-const { product } = await products.getProduct(id);  // V1 wraps in { product }
-return product;
-```
-
-### Create a product (single-variant, with price)
-
-```typescript
-if (v === 'V3_CATALOG') {
-  const product = await productsV3.createProduct({
-    name: 'My Product',
-    productType: 'PHYSICAL',                            // UPPER_CASE
-    variantsInfo: {
-      variants: [{
-        price: { actualPrice: { amount: '19.99' } },    // string, on the variant
-        sku: 'SKU-001',
-      }],
-    },
-  });
-  return product;
-}
-
-const { product } = await products.createProduct({
-  name: 'My Product',
-  productType: 'physical',                              // lower-case
-  priceData: { price: 19.99 },                          // number, on the product
-  sku: 'SKU-001',
-});
-return product;
-```
-
-### Update a product (V3 needs `revision`)
-
-```typescript
-if (v === 'V3_CATALOG') {
-  // Signature: updateProduct(_id, productFields). Returns Product directly.
-  const current = await productsV3.getProduct(id);
-  if (current.revision == null) throw new Error(`Product ${id} has no revision`);
-  return await productsV3.updateProduct(id, {
-    revision: current.revision,  // narrowed — required under exactOptionalPropertyTypes
-    name: 'New name',
-  });
-}
-// V1: updateProduct(id, productFields). Returns { product }.
-const { product } = await products.updateProduct(id, { name: 'New name' });
-return product;
-```
-
-### Delete a product
-
-```typescript
-if (v === 'V3_CATALOG') await productsV3.deleteProduct(id);
-else await products.deleteProduct(id);
-```
-
-### Inventory: increment stock
-
-```typescript
-import { inventory, inventoryItemsV3 } from '@wix/stores';
-
-if (v === 'V3_CATALOG') {
-  // Per-variant; flat shape.
-  await inventoryItemsV3.bulkIncrementInventoryItems([
-    { inventoryItemId, incrementBy: 5 },
-  ]);
-} else {
-  // Per-product (variant optional).
-  await inventory.incrementInventory([
-    { productId, variantId, incrementBy: 5 },
-  ]);
-}
-```
-
-To find a V3 inventory item ID, use `inventoryItemsV3.searchInventoryItems` filtered by `productId` / `variantId`.
-
-### Query inventory
-
-```typescript
-if (v === 'V3_CATALOG') {
-  const res = await inventoryItemsV3.queryInventoryItems().eq('productId', productId).find();
-  return res.items;
-}
-// V1: filter is a JSON-stringified expression.
-const res = await inventory.queryInventory({
-  query: { filter: JSON.stringify({ productId }) },
-});
-return res.inventoryItems;
-```
-
-### Collections (V1) ↔ Categories (V3)
-
-```typescript
-// V1 write ops (createCollection, updateCollection, addProductsToCollection, …)
-// live on the `products` namespace, NOT `collections`. The `collections` namespace is read-only.
-import { products } from '@wix/stores';
-import { categories } from '@wix/categories';
-
-if (v === 'V3_CATALOG') {
-  // V3 createCategory(category, options). treeReference is REQUIRED and goes in `options`.
-  // For Wix Stores categories: appNamespace MUST be the literal "@wix/stores", treeKey is null.
-  const category = await categories.createCategory(
-    { name: 'Sale' },
-    { treeReference: { appNamespace: '@wix/stores', treeKey: null } },
-  );
-  return category;
-}
-const { collection } = await products.createCollection({ name: 'Sale' });  // V1 returns { collection }
-return collection;
-```
-
-V3 categories are tree-structured. Reference them on a product via `directCategories[]`, not `collectionIds[]`. **All Stores category API calls must pass `treeReference: { appNamespace: '@wix/stores', treeKey: null }` in `options`** — applies to `createCategory`, `updateCategory`, `queryCategories`, etc.
-
----
-
 ## V1 → V3 Field Mapping (most common)
 
 For the full table see the [Catalog V1 to V3 Migration Guide](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/catalog-v1-to-v3-migration-guide?apiView=SDK).
@@ -311,6 +102,7 @@ For the full table see the [Catalog V1 to V3 Migration Guide](https://dev.wix.co
 | `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 |
+| `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.
 
@@ -330,6 +122,12 @@ Payload changes: V1 `changedFields` → V3 `modifiedFields`. Top-level `entityId
 
 ---
 
-## Falling back to MCP
+## Detailed references
+
+- [stores/QUERY.md](stores/QUERY.md) — list/query products, pagination, price and stock display
+- [stores/GET_PRODUCT.md](stores/GET_PRODUCT.md) — getProduct, options/choices, modifiers, variant choices
+- [stores/WRITE.md](stores/WRITE.md) — create, update, delete products
+- [stores/INVENTORY.md](stores/INVENTORY.md) — inventory read and write operations
+- [stores/CATEGORIES.md](stores/CATEGORIES.md) — collections (V1) ↔ categories (V3)
 
-This file covers the common 80%. For methods not listed (subscriptions, brands, ribbons, etc.) or full request schemas, use `SearchWixSDKDocumentation` then `ReadFullDocsArticle`. Always return the required permission scopes to the user.
+For methods not listed here, use `SearchWixSDKDocumentation` then `ReadFullDocsArticle`. Always return the required permission scopes to the user.