@wix/agent-skills 1.20.1 → 1.21.0

package/package.json

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

@@ -28,13 +28,7 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 
     A filtered table with neither of the two is what gets built when nobody states the requirement — it is the most common way a generated dashboard disappoints.
   - [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md), then **probe** `dist/docs/index.json` with `grep`/`python3` — never a whole-file `Read`, which truncates it silently. It is the one file that says, per symbol, where to import it from (`importPath`), whether its props live in the doc or in a `.d.ts` (`bundle`), and which worked examples exist (`examples`). Upgrade `@wix/patterns` if that file is missing. Patterns API facts come only from the published `dist/docs/` (pages), `dist/examples/` (worked calls) and `dist/dts-bundle/` (types) trees — never from `src/`, `dist/esm/`, or any other path inside the package, with one named exception: `dist/types/` when a bundle has stubbed the prop you need (WIX_PATTERNS_DOCS.md step 5).
-  - [ ] **🛑 Component Docs Gate (MANDATORY, dashboard UI only):** For each patterns symbol you are about to write, decided **from the index** which single artifact answers the question you actually have, and read that one — not all three:
-    - **Where do I import it from?** → the entry's `importPath`. No file read at all.
-    - **How do I call it?** (generics, what a callback receives and returns, how the pieces nest) → the **example** named in `examples`. One worked example beats reconstructing a call from a chain of type files; a hook's example is often filed under the component it pairs with.
-    - **What props, and which are optional?** → **the example first** — it shows the props in use, correctly typed. For what an example cannot show (optionality, union members, an exact callback signature): entry has `bundle` ⇒ read that `.d.ts`; entry has no `bundle` ⇒ the doc's own table is complete and marks `Required`, so read the doc. The two are mutually exclusive — reading both is always one hop too many. **Two thirds of bundles stub the parent that holds the props** (`propsTotal` far above what the file declares is the tell); when that happens, read the parent the index names — one hop — batch any `readWith` files you still need into a single call, and fall back to `dist/types/` for the declaration `tsc` enforces. WIX_PATTERNS_DOCS.md step 5 has the procedure.
-    - **Any setup requirement or gotcha?** → the doc's prose. Rare, but load-bearing where present (routers, providers).
-
-    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 `importPath` the index already gave you, is the failure this gate exists to prevent.
+  - [ ] **🛑 Component Docs Gate (MANDATORY, dashboard UI only):** For each patterns symbol you are about to write, decided **from the index** which single artifact answers the question you actually have — `importPath`, `examples`, or `bundle` — 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 `importPath` the index already gave you, is the failure this gate exists to prevent.
 - [ ] **Step 3:** Checked API references; used MCP discovery only for gaps
   - [ ] Site/editor extensions only: kept SDK calls in the extension by default, routing out only business-wide methods a visitor genuinely cannot call (see [Identity and Elevation Requirement](#identity-and-elevation-requirement))
 - [ ] **Step 4a:** Scaffolded each CLI-supported extension via `wix generate --params`
@@ -53,25 +47,6 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 
 ---
 
-## ❌ ANTI-PATTERNS (DO NOT DO)
-
-| ❌ WRONG                                    | ✅ CORRECT                                     |
-| ------------------------------------------- | ---------------------------------------------- |
-| Creating a CMS Data Collection for data an existing Wix app already owns (orders, products, bookings, contacts…), or deciding "no SDK exists" without a single MCP search | Use the domain's SDK module per the [SDK-First Rule](#sdk-first-rule-existing-wix-app-data-is-never-cms) |
-| Hand-writing builder files, folders, UUIDs, or extension registration | Run `wix generate --params` — it owns scaffolding |
-| Implementing without reading the extension reference | Always read the relevant reference file first |
-| Using MCP discovery without checking refs   | Check reference files first                    |
-| Reporting done without validation           | Always run validation at the end               |
-| Letting manual action items get buried      | Aggregate all manual steps at the very end     |
-| Building a dashboard page's collection UI (table, grid, filters, sort, bulk actions, page header) out of raw WDS or hand-written React | Use the `@wix/patterns` equivalent — it exists (see [Component Selection Order](#component-selection-order)) |
-| Guessing a `@wix/patterns` or WDS component/prop name from memory | Look it up: patterns via `dist/docs/index.json` + `dist/dts-bundle/index.json` (see [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md)), WDS via the `wix-design-system` skill |
-| Hand-rolling a component (empty state, badge, tooltip, pagination) that one of the two libraries already ships | Search patterns first, then WDS; only build custom when both genuinely lack it |
-| Calling `auth.elevate` from a site or editor extension, or calling an admin-only method there | Put the call in a backend extension and elevate there — elevation only works in backend code |
-| Elevating a session-resolved `current*`/`my*` method (`currentCartV2.*`, `members.getMyMember`) to "be safe" | Call it directly — elevating replaces the caller's session identity and retargets the operation |
-| Elevating a read the platform filters by caller (`members.getMember`/`queryMembers`, `items.*`, catalog) to "make it return more" | Call it directly — elevating removes the filter and returns data the visitor was never entitled to |
-
----
-
 ## Quick Decision Helper
 
 1. **What are you trying to build?**
@@ -87,22 +62,18 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 
 3. **Where will it appear?**
    - Dashboard sidebar/page →
-     - Full admin screen: Dashboard Page — UI built with `@wix/patterns` + `@wix/design-system` (see [Component Selection Order](#component-selection-order))
+     - Full admin screen: Dashboard Page — UI built with `@wix/patterns` + `@wix/design-system` (see [Component Selection Order](#component-selection-order)). **Cannot use `<Modal />`** — use a separate Dashboard Modal extension and `dashboard.openModal()` instead.
      - Popup/form: Dashboard Modal
    - Existing Wix app dashboard (widget) → Dashboard Plugin
-   - Existing Wix app dashboard (menu item) → Dashboard Menu Plugin
-   - Anywhere on site → custom element widget
-   - 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:** Admin screen in the site owner's dashboard? → Dashboard Page — build its UI with `@wix/patterns` first, `@wix/design-system` for whatever patterns does not cover (see [Component Selection Order](#component-selection-order)). Need popup/form? → Dashboard Modal. Extending Wix app dashboard with a visual widget? → Dashboard Plugin. Adding a menu item to a Wix app dashboard's more-actions or bulk-actions menu? → Dashboard Menu Plugin. **Modal constraint:** Dashboard Pages cannot use `<Modal />`; use a separate Dashboard Modal extension and `dashboard.openModal()`.
-- **Backend:** During business flow (checkout/shipping/tax)? → Service Plugin. Exposing tools to the Wix AI assistant? → App Tools (requires both `APP_TOOLS` declaration + `TOOLS_PROVIDER_CONFIG` handler — see [APP_TOOLS.md](references/APP_TOOLS.md)). After event (webhooks/sync)? → Backend Event Extension. Custom HTTP endpoints? → Backend API. Need CMS collections for app-owned data? → Data Collection (see [SDK-First Rule](#sdk-first-rule-existing-wix-app-data-is-never-cms)).
-- **Site:** User places anywhere (standalone)? → custom element widget. Editor React component with editor manifest (styling, content, elements)? → Editor React component. Fixed slot on Wix app page? → Site Plugin. Scripts/analytics only? → Embedded Script.
+   - Existing Wix app dashboard (menu item, more-actions/bulk-actions menu) → Dashboard Menu Plugin
+   - Anywhere on site, standalone → custom element widget
+   - Anywhere on site, with editor manifest (styling/content/elements) → Editor React component
+   - Fixed slot on a Wix business solution page → Site Plugin
+   - Scripts/analytics only, no UI → Embedded Script
+   - 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 occurs (webhooks/sync) → Backend Event Extension
+   - Custom HTTP endpoint → Backend API
 
 ---
 
@@ -199,14 +170,6 @@ Use a Dashboard Modal for dialogs that neither write nor display a listed record
 
 > **HTTP endpoints:** Generate with `extensionType: "HTTP_ENDPOINT"` (not `BACKEND_API`). See [BACKEND_API.md](references/BACKEND_API.md) for project-specific directories, handler types, and frontend URLs.
 
-## Extension Comparison
-
-| Custom element widget vs Editor React component vs Site Plugin | Dashboard Page vs Modal | Service Plugin vs Event |
-| -------------------------------------------------------------- | ----------------------- | ----------------------- |
-| Custom element widget: standalone interactive component. Editor React component: React with editor manifest (CSS/data/elements). Plugin: fixed slot in Wix app page. | Page: full page. Modal: overlay; use for popups. | Service: during flow. Event: after event. |
-
----
-
 ## Cross-Cutting References
 
 | Topic | Reference |
@@ -227,46 +190,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).
 
-**Entity → SDK module map** (find the entity the user mentioned, use that package):
-
-| Entity | SDK package |
-| --- | --- |
-| orders / carts / checkout / refund records / fulfillments | `@wix/ecom` — orders live here regardless of vertical |
-| products / inventory / catalog | `@wix/stores` — ⚠️ V1/V3 check, see [STORES_VERSIONING.md](references/STORES_VERSIONING.md) |
-| payments / refunds / disputes | `@wix/payments` |
-| invoices / payment links / receipts | `@wix/get-paid` |
-| gift cards | `@wix/gift-vouchers` |
-| coupons | `@wix/marketing` |
-| pricing plans / subscriptions | `@wix/pricing-plans` |
-| bookings / services / staff / time slots | `@wix/bookings` |
-| calendar events / schedules | `@wix/calendar` |
-| table reservations | `@wix/table-reservations` |
-| restaurant menus / online orders | `@wix/restaurants` |
-| blog posts | `@wix/blog` |
-| site events / tickets / RSVPs | `@wix/events` |
-| reviews | `@wix/reviews` |
-| comments | `@wix/comments` |
-| groups | `@wix/groups` |
-| online programs | `@wix/online-programs` |
-| donations | `@wix/donations` |
-| portfolio | `@wix/portfolio` |
-| media files | `@wix/media` |
-| contacts / labels / tasks | `@wix/crm` |
-| members | `@wix/members` |
-| inbox conversations | `@wix/inbox` |
-| forms / form submissions | `@wix/forms` |
-| loyalty points / rewards | `@wix/loyalty` |
-| email marketing | `@wix/email-marketing` |
-| notifications | `@wix/notifications` |
-| analytics | `@wix/analytics-data` |
-| automations | `@wix/automations` |
-| SEO tags / redirects | `@wix/seo` |
-| site search | `@wix/search` |
-| secrets | `@wix/secrets` |
-| locations / site properties | `@wix/business-tools` |
-| app instances | `@wix/app-management` |
-
-If the entity isn't listed or you're unsure, run `SearchWixSDKDocumentation` for it — **never conclude CMS with zero MCP calls**. CMS is only for data your app itself introduces (configuration, rules, app-specific records) that no Wix app manages.
+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.
 
 ---
 
@@ -349,7 +273,7 @@ Two signals never settle it: the scope name — `locations.queryLocations` is `S
 
 Routing out means a Backend API endpoint that elevates and is reached with `httpClient.fetchWithAuth()`. Elevation bypasses Wix's permission check, so the endpoint must re-check the caller itself — see [Identity and Authorization](references/BACKEND_API.md#identity-and-authorization) for what each host can actually verify, and why an owner-only operation belongs in a dashboard extension instead.
 
-Add the scope in Dev Center → **Permissions** (it isn't declared in a repo file) and report it under [Manual Steps Required](#-manual-steps-required).
+**Some extensions or SDK calls require a permission scope that `wix generate` doesn't add automatically.** Adding one is a Dev Center account change, not something the agent does — tell the user which scope to add: open their app at `https://manage.wix.com/apps/<appId>/home`, select **Develop > Permissions** in the left menu, then **Add Permissions**, then report it under [Manual Steps Required](#-manual-steps-required). If the app is already installed on a site, the owner must also re-approve it via the install/update flow — revisit that same app page's "Test App" flow (or the release output's install links) and accept "Agree & Update" — before the scope takes effect there.
 
 ---
 
@@ -437,21 +361,11 @@ If the command fails because of unknown or invalid params, run `npx wix schema g
 Open every path returned in `newFiles` and replace stubbed handler bodies / UI / queries with the user's actual logic, guided by the extension reference file's API and configuration sections.
 
 - ⚠️ MANDATORY when using WDS: Invoke the `wix-design-system` skill **before editing your first `.tsx`/`.jsx` file that imports `@wix/design-system`**. Do NOT invoke it preemptively for backend-only or data-only jobs — it adds large content to context that you won't use.
-- ⚠️ MANDATORY when using WDS: Add `import "@wix/design-system/styles.global.css";` in the **main component** entry file (`page.tsx`, modal `.tsx`, etc.) — not in child/tab/helper files.
 - ⚠️ MANDATORY when using Data Collections: Use the EXACT collection ID from `idSuffix` (case-sensitive). If `idSuffix` is `"product-recommendations"`, use `<app-namespace>/product-recommendations` NOT `productRecommendations`.
 
 ### Step 5: Run Validation
 
-After all implementation is complete, you MUST run validation. See [APP_VALIDATION.md](references/APP_VALIDATION.md) for the complete validation workflow:
-
-1. Package installation (detect package manager, run install)
-2. TypeScript compilation check (`npx tsc --noEmit -p .`)
-3. Build validation (`npx wix build`)
-4. Preview deployment (`npx wix preview`)
-
-**Do NOT report completion to the user until validation passes.**
-
-If validation fails, fix the errors and re-validate until it passes.
+Run the four steps in [Validation](#validation) below. **Do NOT report completion to the user until validation passes** — if it fails, fix the errors and re-validate until it does.
 
 ### Step 6: Report Completion
 
@@ -516,18 +430,6 @@ Stop and report errors if any step fails. Check `.wix/debug.log` on failures.
 
 ---
 
-## Cost Optimization
-
-- **Let the CLI scaffold** — don't burn tokens describing folder layouts or builder boilerplate
-- **Only run `wix schema generate --type <extensionType>`** when `wix generate --params` fails — don't pre-fetch it
-- **Read extension reference first** — always read the relevant extension reference file before implementing
-- **Check API references first** — read relevant API reference files before using MCP discovery
-- **Skip discovery** when all required APIs are in reference files
-- **maxResults: 5** for all MCP SDK searches
-- **ReadFullDocsMethodSchema** for SDK method schemas; **ReadFullDocsArticle** for prose guides only
-- **Invoke wix-design-system** first when using WDS (prevents import errors)
-- **Patterns before WDS** for dashboard page UI — check `@wix/patterns` docs before building anything collection- or page-shaped (see [Component Selection Order](#component-selection-order))
-
 ## Documentation
 
 For links to official Wix CLI documentation for all extension types, see [DOCUMENTATION.md](references/DOCUMENTATION.md).

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

@@ -51,6 +51,7 @@ export default extensions.appTools({
   tools: [
     {
       methodName: 'get-order-status',
+      displayName: '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',
@@ -120,7 +121,7 @@ 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)
+- [ ] Set `activated: true` on every tool you want the AI assistant to invoke (`activated` is optional and **defaults to `false`** if omitted — an omitted or `false` tool is declared but never called, with no build error to warn you)
 - [ ] `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`

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

@@ -44,7 +44,7 @@ export default contacts.onContactCreated(async (event) => {
 ## Key Constraints
 
 - **One handler per event** – You cannot have two event extensions for the same event in the app (local or dashboard).
-- **Permissions** – Each event may require specific permission scopes; configure them in the app dashboard (Permissions page).
+- **Adding the first event to an app forces a major release** – The very first event extension in an app requests a brand-new permission scope, so `wix release --version-type minor` fails with `Minor version release is not allowed` / `Release major version.`; use `--version-type major` for that release. Once the required scope already exists on the app, later changes to event handler code can release as `minor`.
 - **Testing** – Release a version with your changes, then perform the action that triggers the event. Some events are not fully testable in local dev.
 - **Backend limits** – Event handlers run under backend extension limits (e.g. 1000 CPU ms per request, 20 sub-requests). See [About Backend Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/about-backend-extensions).
 
@@ -57,5 +57,5 @@ export default contacts.onContactCreated(async (event) => {
 
 ## Testing Event Extensions
 
-1. **Release** a version with your changes.
-2. **Trigger** the event by taking an action.
+1. **Release** a version with your changes (see the major-vs-minor note above — the first event extension needs `--version-type major`).
+2. **Trigger** the event by taking the real action on the site (e.g., create a Contact via the dashboard or REST API). Ask the user to confirm the subscription and delivery in Dev Center, since it isn't reachable through the CLI or API: the app's Webhooks page (Dev Center → your app → Webhooks → Subscriptions) should show the subscription, and the **Logs** tab there after triggering should show a `SUCCESS` row with the expected `entityId`/payload — that's what confirms the event reached the handler's deployed endpoint.

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

@@ -5,7 +5,7 @@ Custom element widgets are native web components (HTML custom elements) that app
 
 ## Scaffold
 
-Use `wix generate --params` with `extensionType: CUSTOM_ELEMENT`. `folder` must be a valid custom-element tag name (lowercase, starts with a letter, contains at least one hyphen). The CLI generates 4 files plus the `src/extensions.ts` registration:
+Use `wix generate --params '{"extensionType":"CUSTOM_ELEMENT","name":"<Display Name>"}'` — `name` is the required param (a human-readable name, e.g. `"Countdown Timer"`), **not `folder`**: the CLI derives the folder/tag name from it (kebab-cased, `-element` suffix added if needed for the hyphen requirement). The CLI generates 4 files plus the `src/extensions.ts` registration:
 
 | File | Purpose |
 |------|---------|
@@ -14,13 +14,13 @@ Use `wix generate --params` with `extensionType: CUSTOM_ELEMENT`. `folder` must
 | `<name>.module.css` | CSS Modules stylesheet pre-wired with a `.root` class and CSS custom-property tokens |
 | `<name>.extension.ts` | Builder file (UUID, name, sizing defaults, auto-add, presets, tagName, file paths) |
 
-After scaffolding, edit `<name>.tsx` for the widget logic, `<name>.panel.tsx` for the settings UI, `<name>.module.css` for the visual design, and the builder file only for non-default sizing, auto-add, or preset behavior.
+Edit `<name>.tsx`/`.panel.tsx`/`.module.css` for logic/settings-UI/styling; touch the builder file only for non-default sizing, auto-add, or presets.
 
 ## Widget Component (`<name>.tsx`)
 
 Wix calls `customElements.define()` for you using the builder's `tagName`; do NOT call it in your code.
 
-Two valid patterns exist: the **native class** component (CLI default) and the **React function component** via `react-to-webcomponent`.
+Two patterns: **native class** (CLI default) and **React function component** via `react-to-webcomponent`.
 
 ### Native class component (CLI default)
 
@@ -29,9 +29,6 @@ import styles from './<name>.module.css';
 
 class MyWidget extends HTMLElement {
   static get observedAttributes() { return ['display-name']; }
-
-  constructor() { super(); }
-
   connectedCallback() { this.render(); }
   disconnectedCallback() { /* tear down timers, listeners */ }
   attributeChangedCallback() { this.render(); }
@@ -45,14 +42,14 @@ class MyWidget extends HTMLElement {
 export default MyWidget;
 ```
 
-Key authoring rules:
+Key rules:
 
 - Extend `HTMLElement`; export the class as the default export.
 - `observedAttributes` must return **kebab-case** strings — HTML attributes don't preserve camelCase.
 - Start side effects in `connectedCallback`, tear them down in `disconnectedCallback`.
 - Call `this.render()` from `attributeChangedCallback`; always provide defaults via `getAttribute` — attributes may be `null` on first paint.
 - Render via `this.innerHTML` (template strings) or imperative DOM, not JSX.
-- Apply the `.root` class from `<name>.module.css` rather than hard-coding colors inline.
+- Apply the `.root` class from `<name>.module.css` rather than hard-coding colors inline — don't import other global CSS.
 
 ### React function component alternative (react-to-webcomponent)
 
@@ -77,9 +74,9 @@ export default reactToWebComponent(MyWidget, React, ReactDOM as any, {
 });
 ```
 
-Key authoring rules for the function component pattern:
+Key rules for this pattern:
 
-- Define props in the `props` option of `reactToWebComponent` using **camelCase** keys. The library automatically maps kebab-case HTML attributes (e.g., `display-name`) to camelCase React props — you do not need `observedAttributes` or `attributeChangedCallback`.
+- Define props in camelCase (see [Props Naming Convention](#props-naming-convention) below) — you do not need `observedAttributes` or `attributeChangedCallback`.
 - Use React hooks (`useState`, `useEffect`) for state and side effects.
 - Render with JSX; use `<name>.module.css` for styles via `className`.
 
@@ -92,8 +89,8 @@ React component shown in the Wix Editor sidebar.
 - Loads initial values with `widget.getProp('kebab-case-name')`.
 - Updates properties with `widget.setProp('kebab-case-name', value)`. Always update both local React state AND the widget prop in onChange handlers.
 - Wrapped in `WixDesignSystemProvider > SidePanel > SidePanel.Content`.
-- For color pickers, use `inputs.selectColor()` from `@wix/editor` with `FillPreview` — NOT `<Input type="color">`.
-- For font pickers, use `inputs.selectFont()` from `@wix/editor` with a `Button` — NOT a text Input.
+- For color/font fields, see [Color & Font Pickers](#color--font-pickers) below — never a plain `<Input>`.
+- For date/time fields, see [Date & Time Fields](custom-element-widget/SETTINGS_PANEL.md#date--time-fields) — `DatePicker`/`TimeInput` `onChange` shapes differ.
 
 ## Builder file (`<name>.extension.ts`)
 
@@ -102,106 +99,57 @@ 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. **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. |
+| `name` | string | from scaffold param | Display name, **max 30 chars** — longer fails platform validation on deploy. |
+| `tagName` | kebab-case | derived from `folder` | Custom-element tag used by the Editor and `customElements.define()`. |
+| `width.defaultWidth` | number (px) | `450` | Initial width when added to a page. |
+| `width.allowStretch` | boolean | `true` | Whether the site owner can stretch the widget's width. |
 | `height.defaultHeight` | number (px) | `250` | Initial height. |
-| `installation.autoAdd` | boolean | `true` | If true, the widget is auto-added to the site when the app is installed. Set to `false` for opt-in widgets. |
-| `presets` | array | one default preset | Editor presets (saved configurations) the site owner can pick from. Each preset has its own `id`, `name`, and `thumbnailUrl`. |
-| `presets[].thumbnailUrl` | string | `{{BASE_URL}}/<name>-thumbnail.png` | Path to a preview image. `{{BASE_URL}}` is resolved at build time. Replace the placeholder image at the same relative path with your actual asset. |
-| `element` | path | `./extensions/site/widgets/<name>/<name>.tsx` | Path to the widget custom element file. Don't change unless renaming files. |
-| `settings` | path | `./extensions/site/widgets/<name>/<name>.panel.tsx` | Path to the settings panel file. Don't change unless renaming files. |
+| `installation.autoAdd` | boolean | `true` | Auto-added on app install if true; set `false` for opt-in widgets. |
+| `presets` | array | one default preset | Editor presets the site owner can pick, each with its own `id`/`name`/`thumbnailUrl`. |
+| `presets[].thumbnailUrl` | string | `{{BASE_URL}}/<name>-thumbnail.png` | Preview image path; `{{BASE_URL}}` resolves at build time — replace the placeholder asset there. |
+| `element` / `settings` | path | generated paths | Widget/panel file paths. Don't change unless renaming files. |
 
 - Import `@wix/design-system/styles.global.css` for styles
-- For colors, use `ColorPickerField` with `inputs.selectColor()` from `@wix/editor` — NOT `<Input type="color">`
-- For fonts, use `FontPickerField` with `inputs.selectFont()` from `@wix/editor` — NOT a text Input
-- Font values are stored as JSON strings via `JSON.stringify()` / `JSON.parse()`
 
 ## Props Naming Convention
 
-The convention differs by pattern, but the settings panel side is always kebab-case.
-
-**Native class component:**
-
-| Side | Convention | Example |
-| ---- | ---------- | ------- |
-| `<name>.tsx` — `observedAttributes`, `getAttribute` | kebab-case | `"display-name"`, `"bg-color"` |
-| `<name>.panel.tsx` — `widget.getProp` / `widget.setProp` | kebab-case | `"display-name"`, `"bg-color"` |
-| Local TypeScript variables | camelCase | `displayName`, `bgColor` |
-
-**React function component (react-to-webcomponent):** Define props with camelCase keys in the `props` option. The library handles the kebab-case ↔ camelCase mapping at the HTML attribute boundary automatically.
+The convention differs by pattern, but the settings panel side is always kebab-case:
 
-| Side | Convention | Example |
-| ---- | ---------- | ------- |
-| `reactToWebComponent` `props` option | camelCase | `{ displayName: 'string' }` |
-| React component props interface | camelCase | `displayName?: string` |
-| `<name>.panel.tsx` — `widget.getProp` / `widget.setProp` | kebab-case | `"display-name"`, `"bg-color"` |
+| Pattern | Side | Convention | Example |
+| --- | --- | --- | --- |
+| Native class | `<name>.tsx` (`observedAttributes`, `getAttribute`) | kebab-case | `"display-name"`, `"bg-color"` |
+| Native class | Local TypeScript variables | camelCase | `displayName`, `bgColor` |
+| React FC | `reactToWebComponent` `props` option | camelCase | `{ displayName: 'string' }` |
+| React FC | Component props interface | camelCase | `displayName?: string` |
+| Both | `<name>.panel.tsx` (`widget.getProp`/`setProp`) | kebab-case | `"display-name"`, `"bg-color"` |
 
 ## Identity and SDK Calls
 
-A widget runs on the live site as the **site visitor or member**, never as the app — see [Identity and Elevation Requirement](../SKILL.md#identity-and-elevation-requirement) before routing any SDK call out to a backend endpoint.
+A widget runs as the **site visitor or member**, never as the app — see [Identity and Elevation Requirement](../SKILL.md#identity-and-elevation-requirement) before routing any SDK call out to a backend endpoint.
 
-A widget's collection reads also need permissions that admit an anonymous visitor — see [Permissions](DATA_COLLECTION.md#permissions), since the scaffolded default allows `ANYONE` to read but only `PRIVILEGED` to write.
+A widget's collection reads need permissions admitting an anonymous visitor — see [Permissions](DATA_COLLECTION.md#permissions); the scaffolded default is `ANYONE` read, `PRIVILEGED` write.
 
 ## Wix Data API Integration
 
 When using the Wix Data API in widgets, you **must** handle the Wix Editor environment gracefully — fetching data inside the Editor produces empty results and noisy errors.
 
-**Requirements (both patterns):**
+**Requirements (both patterns):** install `@wix/site-window` first (not part of the CLI's base scaffold), check `await wixWindow.viewMode()` before fetching, render a placeholder if `'Editor'`, as below.
 
-- Import `{ window as wixWindow }` from `'@wix/site-window'`.
-- Check `await wixWindow.viewMode()` before fetching data.
-- If `viewMode === 'Editor'`, render a placeholder instead of fetching.
-- Only query and render real data when NOT in Editor mode.
-
-**Native class component:**
+**Native class component** — same class shape as [above](#native-class-component-cli-default), `observedAttributes` returning `['collection-id']`, with this `render()`:
 
 ```typescript
 import { items } from '@wix/data';
 import { window as wixWindow } from '@wix/site-window';
 
-class MyWidget extends HTMLElement {
-  static get observedAttributes() {
-    return ['collection-id'];
-  }
-
-  constructor() {
-    super();
-  }
-
-  connectedCallback() {
-    this.render();
-  }
-
-  attributeChangedCallback() {
-    this.render();
-  }
-
-  async render() {
-    const collectionId = this.getAttribute('collection-id') || '';
-    const viewMode = await wixWindow.viewMode();
-
-    if (viewMode === 'Editor') {
-      this.innerHTML = `
-        <div style="padding: 20px; border: 2px dashed #ccc">
-          <p>Widget will display data on the live site</p>
-          <p>Collection: ${collectionId}</p>
-        </div>
-      `;
-      return;
-    }
-
-    try {
-      const { items: results } = await items.query(collectionId).limit(10).find();
-      this.innerHTML = results.map((item) => `<div>${item.title}</div>`).join('');
-    } catch (error) {
-      console.error('Failed to load data:', error);
-    }
+async render() {
+  const collectionId = this.getAttribute('collection-id') || '';
+  if ((await wixWindow.viewMode()) === 'Editor') {
+    this.innerHTML = `<div style="padding: 20px; border: 2px dashed #ccc"><p>Widget will display data on the live site</p></div>`;
+    return;
   }
+  const { items: results } = await items.query(collectionId).limit(10).find();
+  this.innerHTML = results.map((item) => `<div>${item.title}</div>`).join('');
 }
-
-export default MyWidget;
 ```
 
 **React function component** — use `useEffect` for the viewMode check and data fetch:
@@ -224,74 +172,15 @@ useEffect(() => {
 
 ## Color & Font Pickers
 
-Use native Wix pickers — never `<Input type="color">` or a plain text input.
-
-| Picker | API | Preview component | Value type |
-|--------|-----|-------------------|------------|
-| Color | `inputs.selectColor(value, { onChange })` from `@wix/editor` | `<FillPreview fill={value} onClick={...} />` | `string` |
-| Font | `inputs.selectFont(value, { onChange })` from `@wix/editor` | `<Button onClick={...}>Change Font</Button>` | `{ font: string; textDecoration: string }` — store as `JSON.stringify()` |
-
-```typescript
-// Color — inside a SidePanel.Field > FormField
-<FillPreview
-  fill={bgColor}
-  onClick={() => inputs.selectColor(bgColor, {
-    onChange: (val) => { if (val) { setBgColor(val); widget.setProp('bg-color', val); } }
-  })}
-/>
-
-// Font — inside a SidePanel.Field > FormField
-<Button onClick={() => inputs.selectFont(font, {
-  onChange: (val) => {
-    const next = { font: val.font, textDecoration: val.textDecoration || '' };
-    setFont(next);
-    widget.setProp('font', JSON.stringify(next));
-  }
-})}>Change Font</Button>
-```
+See [SETTINGS_PANEL.md § Color & Font Picker Fields](custom-element-widget/SETTINGS_PANEL.md#color--font-picker-fields) for the API, value types, and wiring — never `<Input type="color">` or a plain text input. Call `widget.setProp('bg-color', val)` / `widget.setProp('font', JSON.stringify(val))` from the `onChange` shown there to persist the value.
 
 ## Examples
 
-### Countdown Timer Widget
-
-**Request:** "Create a countdown timer widget"
-
-**Output:**
-
-- Widget with configurable title, target date/time, colors, and font
-- Settings panel with date picker, time input, color pickers, font picker
-- Real-time countdown display with days, hours, minutes, seconds
-
-### Product Showcase Widget
-
-**Request:** "Create a widget that displays products from a collection"
-
-**Output:**
-
-- Widget that queries Wix Data collection
-- Editor environment handling (shows placeholder in editor)
-- Settings panel for collection selection, display options, styling
-- Responsive grid layout with product cards
-
-### Interactive Calculator Widget
-
-**Request:** "Create a calculator widget with customizable colors"
-
-**Output:**
-
-- Functional calculator component
-- Settings panel for color customization (background, buttons, text)
-- Inline styles for all styling
-- No external dependencies
+- **"Create a countdown timer widget"** → title/date/colors/font settings (see [Date & Time Fields](custom-element-widget/SETTINGS_PANEL.md#date--time-fields)), a live days/hours/minutes/seconds display.
+- **"Create a widget that displays products from a collection"** → Wix Data query with [Editor-mode handling](#wix-data-api-integration), a responsive product-card grid.
+- **"Create a calculator widget with customizable colors"** → a functional calculator, color-customization settings, inline styles, no external dependencies.
 
 ## Frontend Aesthetics
 
-Avoid generic aesthetics. Create distinctive designs with unique fonts (avoid Inter, Roboto, Arial), cohesive color palettes, CSS animations for micro-interactions, and context-specific choices. Don't use clichéd color schemes or predictable layouts.
-
-## Custom-element-specific Conventions
+Avoid generic aesthetics — distinctive fonts (not Inter, Roboto, Arial), a cohesive color palette, and CSS micro-interactions, not a predictable clichéd layout.
 
-- **Native class (CLI default):** Widget extends `HTMLElement` and renders via `this.innerHTML`. Use kebab-case throughout (`observedAttributes`, `getAttribute`, `getProp`, `setProp`).
-- **React function component alternative:** Widget uses a React FC converted via `react-to-webcomponent`. Use camelCase in the `props` option; the library handles kebab-case HTML attributes automatically. The settings panel side still uses kebab-case with `getProp`/`setProp`.
-- The settings panel (`<name>.panel.tsx`) is always a functional React component with hooks, regardless of which widget pattern is used.
-- Style via the generated `<name>.module.css` (preferred) or inline styles. Don't import other global CSS.
-- Handle the Wix Editor environment when using the Wix Data API.

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

@@ -67,12 +67,12 @@ const result = await modalClosed; // Resolves with data from closeModal()
 
 ## Receiving Data in Modal
 
-Inside the modal, subscribe via `dashboard.observeState()` to access whatever was passed in `openModal({ params })`. The callback receives the params object as `state`:
+Inside the modal, subscribe via `dashboard.observeState()` to access whatever was passed in `openModal({ params })`. The callback receives the params object as `state`. `observeState` is generic (`state`'s type defaults to `{}`), so **pass the params shape explicitly as a type argument** — without it, `tsc` fails every property access on `state` with "Property 'x' does not exist on type '{}'":
 
 ```typescript
 import { dashboard } from "@wix/dashboard";
 
-dashboard.observeState((state) => {
+dashboard.observeState<{ userId: string; itemData: unknown }>((state) => {
   // state contains the keys you passed in `openModal({ params: { ... } })`
   console.log(state.userId, state.itemData);
 });
@@ -109,7 +109,7 @@ export default {
 
 | Mistake | Fix |
 |---------|-----|
-| Can't find modal ID | Check the modal's generated builder file (`extensions.ts`) `id` field |
+| Can't find modal ID | Check the modal's generated builder file's `id` field (not `src/extensions.ts`, which only registers the extension) |
 | Using `extensionId` instead of `modalId` | Use `modalId` in `openModal()` |
 | Can't access params in modal | Use `dashboard.observeState()` to read passed data |
 | Modal won't close | Use `dashboard.closeModal()` from `@wix/dashboard` |
@@ -137,7 +137,7 @@ const handleDelete = async (item: Item) => {
 const [itemName, setItemName] = useState<string | null>(null);
 
 useEffect(() => {
-  dashboard.observeState((state) => {
+  dashboard.observeState<{ itemName?: string }>((state) => {
     if (state.itemName) setItemName(state.itemName);
   });
 }, []);

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

@@ -0,0 +1,44 @@
+# Entity → SDK Module Map
+
+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 (see the [SDK-First Rule](../SKILL.md#sdk-first-rule-existing-wix-app-data-is-never-cms) in `SKILL.md`). A custom collection for such data starts empty and stays disconnected from the real records (e.g., a "refunds dashboard" built on CMS shows an empty state while refunded orders exist in Wix eCommerce).
+
+**Entity → SDK module map** (find the entity the user mentioned, use that package):
+
+| Entity | SDK package |
+| --- | --- |
+| orders / carts / checkout / refund records / fulfillments | `@wix/ecom` — orders live here regardless of vertical |
+| products / inventory / catalog | `@wix/stores` — ⚠️ V1/V3 check, see [STORES_VERSIONING.md](STORES_VERSIONING.md) |
+| payments / refunds / disputes | `@wix/payments` |
+| invoices / payment links / receipts | `@wix/get-paid` |
+| gift cards | `@wix/gift-vouchers` |
+| coupons | `@wix/marketing` |
+| pricing plans / subscriptions | `@wix/pricing-plans` |
+| bookings / services / staff / time slots | `@wix/bookings` |
+| calendar events / schedules | `@wix/calendar` |
+| table reservations | `@wix/table-reservations` |
+| restaurant menus / online orders | `@wix/restaurants` |
+| blog posts | `@wix/blog` |
+| site events / tickets / RSVPs | `@wix/events` |
+| reviews | `@wix/reviews` |
+| comments | `@wix/comments` |
+| groups | `@wix/groups` |
+| online programs | `@wix/online-programs` |
+| donations | `@wix/donations` |
+| portfolio | `@wix/portfolio` |
+| media files | `@wix/media` |
+| contacts / labels / tasks | `@wix/crm` |
+| members | `@wix/members` |
+| inbox conversations | `@wix/inbox` |
+| forms / form submissions | `@wix/forms` |
+| loyalty points / rewards | `@wix/loyalty` |
+| email marketing | `@wix/email-marketing` |
+| notifications | `@wix/notifications` |
+| analytics | `@wix/analytics-data` |
+| automations | `@wix/automations` |
+| SEO tags / redirects | `@wix/seo` |
+| site search | `@wix/search` |
+| secrets | `@wix/secrets` |
+| locations / site properties | `@wix/business-tools` |
+| app instances | `@wix/app-management` |
+
+If the entity isn't listed or you're unsure, run `SearchWixSDKDocumentation` for it — **never conclude CMS with zero MCP calls**. CMS is only for data your app itself introduces (configuration, rules, app-specific records) that no Wix app manages.