@wix/agent-skills 1.0.0

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

@@ -0,0 +1,451 @@
+
+# Wix Data Collection Builder
+
+Creates CMS data collections for Wix CLI apps. The data collections extension allows your app to automatically create CMS collections when it's installed on a site. Collections store structured data that can be accessed from dashboard pages, site pages, backend code, and external applications.
+
+**Important:** This extension automatically enables the site's code editor, which is required for the Wix Data APIs to work. Without this extension, apps using Data APIs would need the Wix user to manually enable the code editor on their site, which isn't guaranteed. With the data collections extension, your app can reliably use Data APIs to read and write data in the collections.
+
+
+## App Namespace Handling
+
+**App namespace is REQUIRED** for data collections to work. The namespace scopes your collection IDs to prevent conflicts between apps.
+
+### Implementation Behavior
+
+**If app namespace is provided in the prompt:**
+- Use it in all code examples: `<actual-namespace>/collection-suffix`
+
+**If app namespace is NOT provided:**
+- Use the placeholder `<app-namespace>` in all code examples: `<app-namespace>/collection-suffix`
+- Add to Manual Action Items: "Replace `<app-namespace>` with your actual app namespace from Wix Dev Center"
+
+### Collection ID Format
+
+- **In extension definition (`idSuffix`):** Use just the suffix, e.g., `"products"`
+- **In API calls:** Use the full scoped ID: `"<app-namespace>/products"` — MUST match `idSuffix` exactly (case-sensitive, no camelCase/PascalCase transformation)
+- **In `referencedCollectionId`:** Use the `idSuffix` only (not the full scoped ID) — the system resolves it automatically
+- Example: If `idSuffix` is `"product-recommendations"`, API calls use `"<app-namespace>/product-recommendations"` NOT `"<app-namespace>/productRecommendations"`
+
+
+## File Structure
+
+In Wix CLI apps, all CMS collections are defined in a single file:
+
+**File:** `src/extensions/data/extensions.ts`
+
+This file uses the `extensions.genericExtension()` pattern from `@wix/astro/builders` to register all collections:
+
+```typescript
+import { extensions } from "@wix/astro/builders";
+
+export const dataExtension = extensions.genericExtension({
+  compId: "{{GENERATE_UUID}}",
+  compName: "data-extension",
+  compType: "DATA_COMPONENT",
+  compData: {
+    dataComponent: {
+      collections: [
+        // All collections defined here
+      ],
+    },
+  },
+});
+```
+
+**CRITICAL:** The `compId` must be a unique, static UUID string. Generate a fresh UUID v4 for each app - do NOT use `randomUUID()` or copy UUIDs from examples. After creating or modifying this file, follow [Extension Registration reference](EXTENSION_REGISTRATION.md) for UUID generation and to register the extension in `src/extensions.ts` (required for collections to work).
+
+**Key points:**
+
+- Single file contains all collections
+- Uses `extensions.genericExtension()` from `@wix/astro/builders`
+- Each collection includes: `idSuffix`, `displayName`, `displayField`, `fields`, `dataPermissions`, and optionally `initialData`
+- `displayField` specifies which field the CMS displays when referencing items in this collection from other collections
+- Collections are generated by merging operations (INSERT, UPDATE, DELETE) with existing collections
+- See [extension template](data-collection/extension-template.ts) for complete structure
+
+## Field Types
+
+| Type              | Description                      | Use Case               |
+| ----------------- | -------------------------------- | ---------------------- |
+| `TEXT`            | Single-line text                 | Names, titles          |
+| `RICH_TEXT`       | Formatted HTML text              | Blog content           |
+| `RICH_CONTENT`    | Rich content with embedded media | Complex blog posts     |
+| `NUMBER`          | Decimal numbers                  | Prices, quantities     |
+| `BOOLEAN`         | True/false                       | Toggles, flags         |
+| `DATE`            | Date only                        | Birthdays              |
+| `DATETIME`        | Date with time                   | Timestamps             |
+| `TIME`            | Time only                        | Schedules              |
+| `IMAGE`           | Single image                     | Thumbnails             |
+| `DOCUMENT`        | File attachment                  | PDFs                   |
+| `VIDEO`           | Video file                       | Media                  |
+| `AUDIO`           | Audio file                       | Podcasts               |
+| `MEDIA_GALLERY`   | Multiple media                   | Galleries              |
+| `REFERENCE`       | Link to one item                 | Author → User          |
+| `MULTI_REFERENCE` | Link to many items               | Post → Tags            |
+| `ADDRESS`         | Structured address               | Locations              |
+| `URL`             | URL validation                   | Links                  |
+| `PAGE_LINK`       | Link to Wix page                 | Internal navigation    |
+| `LANGUAGE`        | Language code                    | Multi-language content |
+| `OBJECT`          | JSON object                      | Flexible data          |
+| `ARRAY`           | Array of values                  | Generic arrays         |
+| `ARRAY_STRING`    | Array of strings                 | Tags list              |
+| `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:
+
+```json
+{
+  "key": "settings",
+  "displayName": "Settings",
+  "type": "OBJECT",
+  "objectOptions": {}
+}
+```
+
+For structured objects, define nested fields inside `objectOptions.fields`:
+
+```json
+{
+  "key": "triggerRules",
+  "displayName": "Trigger Rules",
+  "type": "OBJECT",
+  "objectOptions": {
+    "fields": [
+      { "key": "url", "displayName": "URL Condition", "type": "TEXT" },
+      {
+        "key": "scrollDepth",
+        "displayName": "Scroll Depth %",
+        "type": "NUMBER"
+      },
+      { "key": "dateStart", "displayName": "Start Date", "type": "DATE" }
+    ]
+  }
+}
+```
+
+## Field Properties
+
+```json
+{
+  "key": "email",
+  "displayName": "Email Address",
+  "type": "TEXT",
+  "required": true,
+  "unique": true,
+  "defaultValue": null,
+  "description": "User's primary email"
+}
+```
+
+| Property       | Description                  |
+| -------------- | ---------------------------- |
+| `key`          | Field identifier (camelCase) |
+| `displayName`  | Label shown in CMS           |
+| `type`         | Field data type              |
+| `required`     | Must have value              |
+| `unique`       | No duplicates allowed        |
+| `defaultValue` | Initial value                |
+| `description`  | Help text                    |
+
+## Naming Conventions
+
+- **Field keys:** `lowerCamelCase`, ASCII only (e.g., `productName`, `isActive`, `createdAt`)
+- **Collection IDs (`idSuffix`):** `lower-kebab-case` or `lower_underscore` (e.g., `product-categories`, `blog_posts`)
+- **Display names:** Human-readable, can contain spaces (e.g., `"Product Name"`, `"Is Active"`)
+
+## System Fields (Automatic)
+
+Every collection includes: `_id`, `_createdDate`, `_updatedDate`, `_owner`
+
+## Permissions
+
+Access levels control who can read, create, update, and delete items in collections.
+
+| Level                | Description                                        |
+| -------------------- | -------------------------------------------------- |
+| `UNDEFINED`          | Not set (inherits defaults)                        |
+| `ANYONE`             | Public access (including visitors)                 |
+| `SITE_MEMBER`        | Any signed-in user (members and collaborators)     |
+| `SITE_MEMBER_AUTHOR` | Signed-in users, but members only access own items |
+| `CMS_EDITOR`         | Site collaborators with CMS Access permission      |
+| `PRIVILEGED`         | CMS administrators and privileged users            |
+
+**Common patterns:**
+
+- Public content (default, recommended): `read: ANYONE, write: PRIVILEGED`
+- User-generated content: `read: SITE_MEMBER, write: SITE_MEMBER_AUTHOR`
+- Editorial workflow: `read: ANYONE, write: CMS_EDITOR`
+- Private/admin: `read: PRIVILEGED, write: PRIVILEGED`
+
+**Permission hierarchy** (most to least restrictive): `PRIVILEGED` > `CMS_EDITOR` > `SITE_MEMBER_AUTHOR` > `SITE_MEMBER` > `ANYONE` > `UNDEFINED`
+
+### Context-Based Permission Rules
+
+**CRITICAL: Permissions must match where and how the data is accessed.** The consumer of the data determines the minimum permission level — setting permissions more restrictive than the access context will cause runtime failures (empty results or permission-denied errors).
+
+**Determine permissions by asking: "Who interacts with this data, and from where?"**
+
+| Access Context | Who Sees / Uses It | Implication |
+|---|---|---|
+| **Custom element widget** (`CUSTOM_ELEMENT_WIDGET`) | Any site visitor (public) | Reads must be `ANYONE`. If the widget accepts input (e.g., reviews, submissions), inserts must also be `ANYONE` or `SITE_MEMBER`. |
+| **Embedded Script** | Any site visitor (public) | Same as custom element widget — reads must be `ANYONE`. Writes depend on whether visitors can submit data. |
+| **Dashboard Page** (`DASHBOARD_PAGE`) | Site owner / collaborators only | Can use `CMS_EDITOR` or `PRIVILEGED` for all operations since only authorized users access the dashboard. |
+| **Backend code (site-side)** | Runs in visitor context | If called from page code or site-side modules, the caller has visitor-level permissions — data must be readable/writable at the appropriate public level. |
+| **Backend code (elevated)** | Runs with `auth.elevate()` from `@wix/essentials` | Can bypass permissions, but the collection still needs correct defaults for any non-elevated callers. |
+
+**How to apply this:**
+
+1. **Identify every place the collection is read or written** — custom element widgets, dashboard pages, embedded scripts, backend APIs.
+2. **Use the least restrictive context as the floor.** If a custom element widget reads the data AND a dashboard page also reads it, `itemRead` must be `ANYONE` (because the widget is public).
+3. **Apply per-operation.** A collection can have `itemRead: ANYONE` (widget displays it) but `itemInsert: CMS_EDITOR` (only dashboard users add items). Each operation is independent.
+
+**Examples by blueprint type:**
+
+- **Dashboard manages data, custom element widget displays it:** `itemRead: ANYONE`, `itemInsert: CMS_EDITOR`, `itemUpdate: CMS_EDITOR`, `itemRemove: CMS_EDITOR`
+- **Custom element widget collects user submissions (e.g., reviews), dashboard moderates:** `itemRead: ANYONE`, `itemInsert: ANYONE`, `itemUpdate: CMS_EDITOR`, `itemRemove: CMS_EDITOR`
+- **Members-only widget reads data, members can submit:** `itemRead: SITE_MEMBER`, `itemInsert: SITE_MEMBER`, `itemUpdate: SITE_MEMBER_AUTHOR`, `itemRemove: CMS_EDITOR`
+- **Dashboard-only (no public surface):** `itemRead: CMS_EDITOR`, `itemInsert: CMS_EDITOR`, `itemUpdate: CMS_EDITOR`, `itemRemove: CMS_EDITOR`
+
+**Anti-pattern:** Setting `itemRead: PRIVILEGED` on a collection that a custom element widget queries — the widget will return empty results for all visitors because they lack privileged access.
+
+## Relationships
+
+**One-to-One / Many-to-One (REFERENCE):**
+
+```json
+{
+  "key": "category",
+  "displayName": "Category",
+  "type": "REFERENCE",
+  "referenceOptions": {
+    "referencedCollectionId": "categories"
+  }
+}
+```
+
+**Many-to-Many (MULTI_REFERENCE):**
+
+```json
+{
+  "key": "tags",
+  "displayName": "Tags",
+  "type": "MULTI_REFERENCE",
+  "multiReferenceOptions": {
+    "referencedCollectionId": "tags"
+  }
+}
+```
+
+**CRITICAL Constraints:**
+
+- REFERENCE/MULTI_REFERENCE fields can ONLY link to other custom CMS collections defined in your app
+- The `referencedCollectionId` MUST be the `idSuffix` of another collection in the same plan
+- **NEVER use REFERENCE fields to link to Wix business entities** (Products, Orders, Contacts, Members, etc.)
+- Use Wix SDK APIs to access Wix business entities instead
+
+## Collection Operations
+
+Collections support three operation types for modifying collections:
+
+### INSERT
+
+Creates a new collection or replaces an existing one with the same `idSuffix`.
+
+**Use when:** Creating a new collection or completely replacing an existing collection.
+
+### UPDATE
+
+Modifies an existing collection by merging new data with existing fields.
+
+**Use when:** Adding fields, updating permissions, or modifying collection properties.
+
+**Behavior:**
+
+- If collection exists: Merges new data with existing collection
+- If collection doesn't exist: Treats update as insert (creates new collection)
+
+### DELETE
+
+Removes a collection from the app.
+
+**Use when:** Removing a collection that is no longer needed.
+
+**Behavior:**
+
+- Removes the collection from `src/extensions/data/extensions.ts`
+- If all collections are deleted, the entire file is deleted
+
+**Merge logic:** Operations are applied using a Map keyed by `idSuffix`. Existing collections are loaded into the Map first, then each operation modifies it: INSERT sets/replaces, UPDATE merges with existing (or creates if missing), DELETE removes. The final Map values become the output collections.
+
+## App Version Updates
+
+Changes to your data collections extension require releasing a new major version of your app. When a user updates to the new major version, their collections are updated as follows:
+
+- **Adding a new collection:** The new collection is created on the site.
+- **Removing a collection:** If the old app version defined a collection and the new version doesn't, the collection is removed from the site.
+- **Modifying a collection schema:** Field additions, removals, and type changes are applied to the collection. Existing data is preserved.
+
+**Important notes:**
+
+- Collection changes only affect users who update to the new major version. Users who don't update retain their current collections.
+- Collection changes take up to 5 minutes to propagate after an update.
+- **Initial data is only imported when a collection is first created.** If a collection already contains data, `initialData` is ignored during updates.
+
+## Wix CLI-Specific Constraints
+
+### Embedded Script Parameters vs Collections
+
+**CRITICAL: NEVER create CMS collections to store configuration for embedded scripts.**
+
+All embedded script configuration must go through embedded script parameters (`embeddedScriptParameters`), not CMS collections.
+
+**DO NOT create collections for:**
+
+- Colors, messages, headlines, text content
+- Coupon codes, display settings
+- UI customization (positions, sizes, styles)
+- Timing settings, feature toggles
+- Display frequencies, thresholds
+- Minimums/maximums
+- **ANY configuration that controls how an embedded script behaves or appears**
+
+**Examples of configuration (use parameters, NOT collections):**
+
+- Popup headline → embedded script parameter
+- Coupon code → embedded script parameter
+- Background color → embedded script parameter
+- Display position → embedded script parameter
+- Show/hide toggles → embedded script parameter
+
+**CMS collections should ONLY be created for:**
+
+- Business data (products, orders, inventory, etc.)
+- User-generated content (reviews, comments, submissions)
+- Event logs (if explicitly requested for analytics/tracking)
+- Multi-record relational data that is NOT configuration
+
+**Decision Rule:**
+
+- If it controls HOW the embedded script works or looks → it's configuration → use embedded script parameters
+- If it's business data or user-generated content → it's data → use CMS collections
+
+### Custom Element Widget Settings vs Collections
+
+**CRITICAL: custom element widgets have a built-in settings panel (`panel.tsx`) that handles ALL widget configuration.**
+
+**For CUSTOM_ELEMENT_WIDGET-only blueprints (no DASHBOARD_PAGE or other extensions):**
+
+- **ALWAYS return `collections: []` (empty array)**
+- The widget panel handles everything
+- **NEVER create collections to store widget configuration data**
+
+**Configuration handled by widget panel (NOT collections):**
+
+- Target date/time for countdown → widget panel
+- Display colors, fonts, sizes → widget panel
+- Headlines, labels, messages → widget panel
+- Feature toggles, show/hide options → widget panel
+- Numeric settings (delays, intervals, thresholds) → widget panel
+
+**Only create collections for CUSTOM_ELEMENT_WIDGET when ALL of these conditions are met:**
+
+1. The blueprint ALSO includes a DASHBOARD_PAGE extension that needs to manage data the widget displays
+2. OR the widget explicitly needs to display MULTIPLE records of user-generated/business data (not configuration)
+3. AND the data is NOT configuration (dates, colors, settings, display options are ALWAYS configuration)
+
+### Anti-Patterns
+
+**Don't create aggregated fields.** If you have individual `rating` fields, calculate averages dynamically — don't store computed values like `averageRating`.
+
+**Don't duplicate configuration.** If embedded script parameters already hold `{ headline, color }`, don't also create a CMS collection with the same data.
+
+**Don't create single-value collections.** A collection with one field like `{ theme: "dark" }` should be an embedded script parameter or widget setting instead.
+
+### Initial Data Rules
+
+Each item in `initialData` must match the collection schema exactly:
+
+- Field keys must be `lowerCamelCase` and match the schema
+- `TEXT` → string, `NUMBER` → number, `BOOLEAN` → boolean
+- `DATE`/`DATETIME` → use `{ "$date": "2024-01-15T10:30:00.000Z" }` format
+- `REFERENCE` → provide the `idSuffix` of the referenced collection
+- Required fields must always have values
+
+## Examples
+
+### Simple Collection with Initial Data
+
+**Request:** "Create a collection for handling fees with example data"
+
+**Generated file:** `src/extensions/data/extensions.ts`
+
+```typescript
+import { extensions } from "@wix/astro/builders";
+
+export const dataExtension = extensions.genericExtension({
+  compId: "{{GENERATE_UUID}}",
+  compName: "data-extension",
+  compType: "DATA_COMPONENT",
+  compData: {
+    dataComponent: {
+      collections: [
+        {
+          schemaUrl: "https://www.wix.com/",
+          idSuffix: "additional-fees",
+          displayName: "Additional Fees",
+          displayField: "title",
+          fields: [
+            { key: "title", displayName: "Fee Title", type: "TEXT" },
+            { key: "amount", displayName: "Fee Amount", type: "NUMBER" },
+          ],
+          dataPermissions: {
+            itemRead: "ANYONE",
+            itemInsert: "PRIVILEGED",
+            itemUpdate: "PRIVILEGED",
+            itemRemove: "PRIVILEGED",
+          },
+          initialData: [
+            { title: "Handling Fee", amount: 5 },
+            { title: "Gift Wrapping", amount: 3.5 },
+          ],
+        },
+      ],
+    },
+  },
+});
+```
+
+### Collection with Reference Relationship
+
+**Request:** "Create collections for products and categories with relationships"
+
+**Collections:**
+
+- `categories` - Category definitions
+- `products` - Products that reference categories
+
+Both collections are defined in the same `src/extensions/data/extensions.ts` file, with the `products` collection using a REFERENCE field to link to `categories`. See the [extension template](data-collection/extension-template.ts) for a complete multi-collection example.
+
+## Common Patterns
+
+**Soft Delete:** Add `isDeleted` (BOOLEAN, default: false)
+
+**Status/Workflow:** Add `status` (TEXT) with values like draft/pending/published
+
+**URL Slug:** Add `slug` (TEXT, unique) for SEO-friendly URLs
+
+**Owner Tracking:** Add `createdBy` (REFERENCE → custom collection, not Members)
+
+**Note:** For owner tracking, create a custom collection for users rather than referencing Wix Members directly.
+
+## Reference Documentation
+
+- [Wix Data SDK Reference](data-collection/WIX_DATA.md) - Complete reference for reading and writing data using `@wix/data`
+- [extension-template.ts](data-collection/extension-template.ts) - Template for `src/extensions/data/extensions.ts`
+
+### Public Documentation
+
+- [About Data Collections Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/data-collections/about-data-collections-extensions) - When to use the extension, implementation options, and app version update behavior
+- [Add a Data Collections Extension in the App Dashboard](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/data-collections/add-a-data-collections-extension-in-the-app-dashboard) - Step-by-step guide to configuring collections via the app dashboard JSON editor, with example configuration
+- [Data Collections Extension JSON Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections-extension/introduction) - Complete JSON schema and field definitions for the data collections extension

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

@@ -0,0 +1,42 @@
+# Wix CLI Extension Documentation
+
+All information in the wix-app skill is based on official Wix CLI documentation. This file contains links to detailed documentation for each extension type.
+
+## Main Documentation
+
+- [About Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/about-extensions) - Overview of extensions in the Wix CLI
+- [About the extensions.ts File](https://dev.wix.com/docs/wix-cli/guides/extensions/about-the-extensions-ts-file) - How to register extensions
+
+## Dashboard Extensions
+
+- [About Dashboard Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/dashboard-extensions/about-dashboard-extensions) - Overview of dashboard extension types
+- [Add Dashboard Page Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/dashboard-extensions/dashboard-pages/add-dashboard-page-extensions) - How to create dashboard pages
+- [Dashboard Page Extension Files and Code](https://dev.wix.com/docs/wix-cli/guides/extensions/dashboard-extensions/dashboard-pages/dashboard-page-extension-files-and-code) - File structure and code examples
+- [Add Dashboard Modal Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/dashboard-extensions/dashboard-modals/add-dashboard-modal-extensions) - How to create dashboard modals
+- [Dashboard Modal Extension Files and Code](https://dev.wix.com/docs/wix-cli/guides/extensions/dashboard-extensions/dashboard-modals/dashboard-modal-extensions-files-and-code) - File structure and code examples
+- [Add Dashboard Plugin Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/dashboard-extensions/dashboard-plugins/add-dashboard-plugin-extensions) - How to create dashboard plugins
+- [Dashboard Plugin Extension Files and Code](https://dev.wix.com/docs/wix-cli/guides/extensions/dashboard-extensions/dashboard-plugins/dashboard-plugin-extension-files-and-code) - File structure and code examples
+- [Add Dashboard Menu Plugin Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/dashboard-extensions/dashboard-menu-plugins/add-dashboard-menu-plugin-extensions) - How to create dashboard menu plugins
+- [Dashboard Menu Plugin Extension Files and Code](https://dev.wix.com/docs/wix-cli/guides/extensions/dashboard-extensions/dashboard-menu-plugins/dashboard-menu-plugin-extension-files-and-code) - File structure and code examples
+
+## Backend Extensions
+
+- [About Backend Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/about-backend-extensions) - Overview of backend extension types and limits
+- [Add Service Plugin Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/service-plugins/add-service-plugin-extensions) - How to create service plugins
+- [Service Plugin Extension Files and Code](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/service-plugins/service-plugin-extension-files-and-code) - File structure and code examples
+- [Add Event Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/events/add-event-extensions) - How to create event extensions
+- [Event Extension Files and Code](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/events/event-extension-files-and-code) - File structure and code examples
+- [About HTTP Endpoints](https://dev.wix.com/docs/wix-cli/guides/development/http-endpoints/about-http-endpoints) - Overview of Astro endpoints
+- [Add HTTP Endpoints to Your Project](https://dev.wix.com/docs/wix-cli/guides/development/http-endpoints/add-http-endpoints-to-your-project) - How to create backend endpoints
+
+## Site Extensions
+
+- [About Site Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/about-site-extensions) - Overview of site extension types
+- [Add Custom Element Widget Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/site-widgets/add-a-site-widget-extension) - How to create custom element widgets
+- [Custom Element Widget Extension Files and Code](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/site-widgets/site-widget-extension-files-and-code) - File structure and code examples
+- [Identify the App Instance in a Custom Element Widget](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/site-widgets/identify-the-app-instance-in-a-site-widget) - How to identify app instances
+- [Add Site Plugin Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/site-plugins/add-a-site-plugin-extension) - How to create site plugins
+- [Site Plugin Extension Files and Code](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/site-plugins/site-plugin-extension-files-and-code) - File structure and code examples
+- [About Embedded Scripts](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/embedded-scripts/about-embedded-scripts) - Overview of embedded scripts
+- [Add Embedded Script Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/embedded-scripts/add-an-embedded-script-extension) - How to create embedded scripts
+- [Embedded Script Extension Files and Code](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/embedded-scripts/embedded-script-extension-files-and-code) - File structure and code examples

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

@@ -0,0 +1,65 @@
+# Wix Editor React Component Builder
+
+Creates production-quality Editor React components that would be used in Harmony Editor for Wix CLI applications. Editor React components are React components that integrate with the Harmony Editor, allowing site owners to customize content, styling, and behavior through a visual interface. **Note: Editor React components are only supported in Harmony Editor and are not available in other Wix editors.**
+
+## Architecture
+
+Editor React components consist of the following template files (replace `<componentName>` with the actual component name in kebab-case):
+
+### `<componentName>.tsx`
+
+The React component file. Contains the component's UI logic, JSX structure, and TypeScript props interface.
+
+### `<componentName>.module.css`
+
+CSS Module file for the component. Contains all styles scoped to the component.
+
+### `component.tsx`
+
+Entry point for the component. Imports the default prop values defined in `<componentName>.tsx` and wires them up so the component renders correctly when first added to the stage.
+
+### `<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:
+
+```
+npx wix build && npx wix generate manifest
+```
+
+### `<componentName>.extension.ts`
+
+File where you can override the generated manifest from `<componentName>.generated.ts`. Only include overrides that appear in the boilerplate component — do not add extra overrides beyond what the boilerplate provides.
+
+## Workflow
+
+1. If `src/site/components/component-name/` does not yet exist, run
+   `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. 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" ]] || ([ -f 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/site/components/ComponentName/`.
+4. 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.
+5. Update `Component.extensions.ts` file according to [`editor-react-component/COMPONENT-CONFIGURATION.md`](editor-react-component/COMPONENT-CONFIGURATION.md)
+
+Reference: when modifying an _existing_ component, follow
+[`editor-react-component/EDIT-FLOW.md`](editor-react-component/EDIT-FLOW.md).
+
+## React guidelines
+
+Core rules and workflow: [`editor-react-component/REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md).
+
+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/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/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).