@wix/agent-skills 1.15.1 → 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,13 +91,9 @@ 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 & caching (`www.wix.com/skills`)
+## 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`). That registry is **not** in this repo — it's an Express service in [`wix-private/docs`](https://github.com/wix-private/docs) (`docs-web-app`) that serves this repo's `main` branch directly, with no build step.
-
-Responses are cached at the Wix edge (Pepyaka, tag `skills`) plus a ~5-min per-pod tarball cache. A push to `main` touching `skills/**` **auto-invalidates** the edge tag (via `md-resolver`'s GitHub-push consumer), so a merge reflects within a few minutes. To force it immediately, hit the manual flush (`POST /api/v1/invalidate-ssr-cache/skills`, BO staff) or the Fire Console `invalidateCache` call.
-
-Full details — endpoints, `wix-` prefix stripping, host-relative links, invalidation — are in the [docs-web-app skills README](https://github.com/wix-private/docs/blob/main/packages/docs-web-app/express/skills/README.md).
+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
 

package/package.json

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

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,15 +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
-- [`editor-react-component/ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md) — Play/pause controls for animated components (Lottie, GIF, autoPlay props)
-- [`editor-react-component/COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) — `component.preview.tsx` patterns and `useIsEditMode()` usage
 
 ## 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/app-tools/TOOLS.md

@@ -0,0 +1,75 @@
+# App Tools Extension Reference
+
+## Overview
+
+The `APP_TOOLS` extension declares the tools your app exposes to the Wix AI assistant. Each tool entry tells the AI assistant what the tool does, what it accepts, and what it returns — so the assistant can discover and invoke it at runtime.
+
+The AI assistant does NOT call these tools directly. It uses the declarations here to understand the tool's purpose and invoke your **Tools Provider service plugin** at runtime. See [TOOLS_PROVIDER.md](../service-plugin/TOOLS_PROVIDER.md) for the runtime handler.
+
+## Registration
+
+Scaffold the extension with the CLI — it creates the `.extension.ts` file and registers it in `src/extensions.ts` automatically:
+
+```bash
+wix generate --params '{"extensionType":"APP_TOOLS","name":"my-tools"}'
+```
+
+The generated file lives at `src/extensions/backend/app-tools/my-tools/my-tools.extension.ts`. Replace the stub tool with your own:
+
+```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', description: 'The order ID to look up.' }
+        },
+        required: ['orderId']
+      },
+      responseSchema: {
+        type: 'object',
+        properties: {
+          status: { type: 'string' },
+          trackingNumber: { type: 'string' }
+        }
+      },
+      activated: true
+    }
+  ]
+});
+```
+
+## `AppToolConfig` Fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `methodName` | `string` | Yes | Unique word identifying the tool. Used to route calls in the service plugin handler. 1–30 characters. |
+| `description` | `string` | Yes | Natural-language description the AI assistant uses to decide when to invoke this tool. Write it like a prompt: state what the tool does, list the user intents or trigger phrases that should activate it, and describe what it returns. A narrow one-liner reduces relevance matching — prefer 2–4 sentences covering intent, triggers, and output. 10–1000 characters. |
+| `requestSchema` | `Record<string, any>` | No | JSON Schema describing the tool's request payload. The AI assistant uses this for context — it is NOT validated by Wix at call time. |
+| `responseSchema` | `Record<string, any>` | No | JSON Schema describing the tool's response payload. |
+| `activated` | `boolean` | Yes | Only tools with `activated: true` are called by the AI assistant. |
+
+## Important Constraints
+
+- `tools` array: min 1, max 100 tools per extension.
+- `methodName` must be unique across all tools in the extension — it is the routing key in the service plugin handler.
+- Schemas are advisory for the AI assistant; your handler must still validate inputs defensively.
+- Only `activated: true` tools are invoked. Use `activated: false` to temporarily disable a tool without removing it.
+
+## Relationship to the Tools Provider
+
+The `APP_TOOLS` extension is the **declaration** side. The **execution** side is the Tools Provider service plugin registered with `toolsProviderConfig`:
+
+```
+APP_TOOLS (declaration)  →  AI assistant discovers & selects a tool
+toolsProviderConfig (SPI) →  Wix calls your runTool handler at runtime
+```
+
+Both extensions must be registered for the feature to work end-to-end. See [APP_TOOLS.md](../APP_TOOLS.md) for the full picture and [TOOLS_PROVIDER.md](../service-plugin/TOOLS_PROVIDER.md) for the handler implementation.

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

@@ -23,8 +23,8 @@ Host Module '@wix/dashboard' 'navigate()' method for navigating between dashboar
 import { dashboard } from '@wix/dashboard';
 // Navigate to your own app's page with some internal state
 dashboard.navigate({pageId: <your-page-id>, relativeUrl: "/an/internal/state?param=value"})
-// Navigate to a relative route of the current page
-dashboard.navigate({ relativeUrl: "/some/internal/route" });
+// Navigate to a relative URL within a page (pageId required even for relative paths)
+dashboard.navigate({ pageId: '<your-page-id>', relativeUrl: "/some/internal/route" });
 // Navigate to the Products List page
 dashboard.navigate({ pageId: "0845ada2-467f-4cab-ba40-2f07c812343d" });
 // Add a button that navigates to the Products List page (React/TSX)

package/skills/wix-app/references/editor-react-component/A11Y-REVIEW-REFERENCE.md

@@ -0,0 +1,172 @@
+# Editor React Component A11y Review Reference
+
+Use this reference for decisions that require code inspection after running the scanners in [`A11Y-REVIEW.md`](A11Y-REVIEW.md). The scanner output owns rule-specific context: rule ID, location, message, resolution path, evidence, and confidence. Do not maintain a separate rule catalog here.
+
+## Scanner Result Handling
+
+Treat every scanner finding as a lead until the component implementation confirms how the flagged behavior reaches the rendered element.
+
+1. Read the full finding, including evidence and confidence when present.
+2. Trace the component topology through local wrappers, shared primitives, and package implementations.
+3. Deduplicate findings that identify the same issue at the same location.
+4. Assign a verdict: `confirmed`, `false-positive`, or `not-relevant`.
+5. Fix confirmed issues inline, then re-run both scanners on changed JSX files.
+
+When both scanners flag the same issue, keep the finding with the strongest semantic evidence. The scanners complement each other; a finding from one scanner is not automatically stronger because of its tier.
+
+## Confidence Model
+
+### High
+
+Use high confidence when the code and scanner evidence unambiguously show the violation, for example:
+
+- the flagged rendered element and static props establish the behavior directly
+- the component implementation resolves to the flagged semantic element
+- an explicit polymorphic prop establishes the rendered element
+
+Fix high-confidence findings immediately.
+
+### Medium
+
+Use medium confidence when:
+
+- props strongly imply the rendered semantics
+- the implementation only partially resolves but preserves likely semantics
+- the component name, props, and surrounding evidence strongly agree
+
+Read the surrounding code. If it confirms the inference, fix the issue. If it contradicts the inference, discard the finding. If the implementation remains unresolved, treat it as low confidence.
+
+### Low
+
+Use low confidence when:
+
+- only weak heuristics support the semantic guess
+- the implementation cannot be resolved
+- runtime props or spreads can materially change the rendered semantics
+
+Continue tracing the code. Fix only after the issue is confirmed; otherwise leave the code unchanged.
+
+### Confidence vs. Actionability
+
+Confidence answers whether the issue is real. It does not decide whether a confirmed fix is safe.
+
+- Confirmed + safe/local fix: fix now.
+- Confirmed + risky behavior change or non-local refactor: leave unchanged.
+- Unconfirmed or ambiguous: leave unchanged.
+
+If the violation is visible in the code and has a localized, behavior-preserving fix, treat it as confirmed and apply the fix.
+
+Valid reasons to leave code unchanged:
+
+- semantics remain ambiguous after reading the available code
+- product intent cannot be derived from the code
+- the fix requires a risky behavior change or a non-local refactor
+
+Do not leave a confirmed safe/local issue unchanged because it is low severity, secondary, shared, or outside the first file in scope.
+
+## Semantic Resolution
+
+Resolve the rendered behavior in this order:
+
+1. The flagged JSX element and its static props
+2. Explicit polymorphic props such as `as="a"` or `component="button"`
+3. The local component implementation
+4. Installed package source or declarations in `node_modules`
+5. Prop evidence such as `href`, `to`, `src`, `alt`, and `role`
+6. Component-name heuristics
+
+For local imports, follow the exported component's rendered root. Continue through local or package components until the semantics resolve or the evidence becomes too weak.
+
+For package imports, resolve the import from `node_modules` and inspect its exported entry point. If the package hides its rendered semantics, use prop and naming evidence without assigning more confidence than the evidence supports.
+
+## Tier 2 Manual Review Checklist
+
+Run this checklist after scanner findings are triaged. Tier 2 is required even when both scanners return zero findings.
+
+### Semantic Targeting
+
+- Do ARIA attributes land on the semantically correct element instead of a layout wrapper?
+- Do labels, descriptions, and roles reach the actual interactive or landmark element?
+- Do wrappers preserve the semantics exposed by their API?
+
+### Icon-Only and Visual-Only States
+
+- Do icon-only buttons, links, or controls have an accessible name?
+- If visible text is hidden, is it visually hidden in an accessibility-safe way instead of removed from the accessibility tree?
+- Do meaningful icons or images expose accessible text when needed?
+
+### CSS and Hidden Content
+
+- Does `display: none` remove content that should remain available to assistive technology?
+- Are hidden or collapsed states consistent across visuals, focusability, and the accessibility tree?
+- Do conditional classes or CSS variables create states where labels or instructions disappear from assistive technology?
+
+### Decorative vs. Meaningful Content
+
+- Are decorative separators, ornaments, and repeated icons hidden from assistive technology?
+- Are meaningful visuals, status icons, or graphics named appropriately?
+
+### Focus and Interaction Consistency
+
+- Can hidden or collapsed items still receive focus?
+- Do interactive-looking elements expose the correct role and keyboard behavior?
+- Do disabled, inert, or collapsed states behave consistently for keyboard users and assistive technology?
+- Search all in-scope files for `onClick` on elements without built-in interaction (`div`, `span`, `section`, `header`, `footer`, `li`, `td`, and similar tags). Include conditional patterns such as `{...(condition && { onClick: handler })}`. Verify that each match also has the required `role`, `tabIndex`, and keyboard handler (`onKeyDown` or `onKeyUp`). A missing combination is a high-confidence finding.
+- Before fixing missing keyboard semantics, check for nested interactive children, existing focus management, and the condition that enables interaction. Use the [pre-fix checks](#pre-fix-checks-for-adding-button-semantics-to-a-non-interactive-element).
+
+### Structural Semantics
+
+- Are landmarks, headings, and list semantics preserved through wrappers and layout components?
+- When the component implements breadcrumbs, tabs, menus, dialogs, or similar patterns, do the expected semantics reach the rendered structure?
+
+### Editor React Component Contracts
+
+- Are ARIA attributes routed through the typed `a11y` prop and converted at the correct element?
+- Do icon-only labels come from `constants.ts` or user-configurable `a11y` instead of hardcoded strings?
+- Does the component preserve direction support and isolate each `ReactNode` content prop with `dir="ltr"`?
+- Do extension overrides preserve a11y-relevant manifest fields generated from JSX?
+
+## Fix Principles
+
+- Use the rule ID, message, and evidence emitted by the scanner as the rule-specific fix context.
+- Read the surrounding code before editing.
+- Preserve visual and runtime behavior.
+- Prefer the smallest correct change and avoid unrelated refactors.
+- Fix the semantic owner: the component root, the correct inner element, a shared base, or the call site that supplies the value.
+- When a wrapper already accepts and forwards a required prop, fix the call site. When it does not, update the wrapper contract and forwarding before fixing the call site.
+- Do not hardcode reusable accessibility values such as alternative text. Accept them through the component API when they depend on consumer content.
+- Route Editor React Component ARIA through `a11y` and `convertA11yKeysToHtmlFormat(a11y)` according to [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
+
+## Pre-Fix Checks for Adding Button Semantics to a Non-Interactive Element
+
+Before adding `role="button"`, `tabIndex`, and keyboard handlers to an element such as `<div>`, verify all four conditions below.
+
+### 1. Interactive Children
+
+Check whether the element conditionally or unconditionally contains `<a>`, `<button>`, `<input>`, `<Link>`, or a component that resolves to an interactive element. Button semantics on the parent would create nested interaction.
+
+If interactive children are possible, either exclude that branch from the parent's interaction condition or use a separate control element.
+
+### 2. Existing Focus Management
+
+Check whether the element already receives `tabIndex` from another source, such as `getTabIndexAttribute`, an a11y prop spread, or an interactions framework. Determine the prop merge order and keep one source authoritative.
+
+When an existing a11y spread should win, place the conditional interaction spread before it so `tabIndex: 0` only acts as a fallback.
+
+### 3. Interaction Condition
+
+Read the full boolean expression that enables interaction. Verify that it:
+
+- excludes states that already render an interactive child
+- excludes editor preview, externally controlled, disabled, or reduced-motion states when required
+- uses explicit comparisons such as `=== undefined` or `=== true` when `true`, `false`, and `undefined` have different meanings
+
+Fix a fragile condition as part of the accessibility change. Correct semantics attached to the wrong state are still incorrect behavior.
+
+### 4. Accessible Name Scope
+
+Decide whether an accessible label names the interaction or the component as a whole. Keep a component-level label outside the interaction condition so it persists in non-interactive states. Apply an action-specific label only while that action is available.
+
+## After Fixing
+
+Re-run both scanners on changed `.tsx` / `.jsx` files. Continue with `npx wix build`, `npx wix generate manifest`, and the project's TypeScript check as required by [`A11Y-REVIEW.md`](A11Y-REVIEW.md#phase-5-verify).