@wix/agent-skills 1.20.1 → 1.22.0

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/DASHBOARD_PAGE.md

@@ -31,7 +31,9 @@ The CLI generates the folder, `page.tsx`, the builder file, the UUID, and the `s
 
 **Never reuse `<route>` as a path prefix inside this page's `PatternsReactRouter`** — its location is already page-scoped, so a page scaffolded `route: "shifts"` still routes from `path="/"`, and `path="/shifts"` silently never matches. Page-relative paths: `<pkgRoot>/dist/docs/Collection to Entity Flow.md`.
 
-**Then, before writing UI:** resolve the package root and probe `<pkgRoot>/dist/docs/index.json` once with `grep`/`python3` — not a whole-file `Read`, which truncates it silently — per [Prerequisites](WIX_PATTERNS_DOCS.md#prerequisites). That index carries each symbol's `importPath`, `examples` and `bundle`, which is what decides whether you need to open anything else at all. Each Bash call is a fresh shell — re-set the path variable in every call.
+**Before writing that UI:** pick the matching case in [DRAFT_TEMPLATE.md](dashboard-page/DRAFT_TEMPLATE.md#which-case-matches-the-request) and copy its files in over the generated stub — don't compose the shell from scratch.
+
+**Then, for whatever the template case doesn't already cover:** resolve the package root and probe `<pkgRoot>/dist/docs/index.json` once with `grep`/`python3` — not a whole-file `Read`, which truncates it silently — per [Prerequisites](WIX_PATTERNS_DOCS.md#prerequisites). That index carries each symbol's `importPath`, `examples` and `bundle`, which is what decides whether you need to open anything else at all. Each Bash call is a fresh shell — re-set the path variable in every call.
 
 ## Capabilities
 
@@ -86,31 +88,15 @@ When building a dashboard page to configure an embedded script, see [Dynamic Par
 
 ## Examples
 
-Each output below names the library that owns each part. Confirm every patterns component and prop by reading its doc from `dist/docs/index.json` before use — these examples name the shape, not a verified API.
-
-### Data Management Table
-
-**Request:** "Create a dashboard page to manage blog posts"
-
-**Output:** A `@wix/patterns` `CollectionPage` wrapping a `Table` driven by `useTableCollection`, with search, row actions, and empty state from the collection's own APIs. Add and edit navigate to an `EntityPage`. WDS only for leaf UI inside cells and entity-page cards; the provider sits in a parent component, in its own file.
-
-### Settings Form
-
-**Request:** "Build a settings page for notification preferences"
-
-**Output:** A `@wix/patterns` `SettingsPage` shell. WDS form fields inside it (`FormField`, `Input`, `ToggleSwitch`), save button with `dashboard.showToast()` confirmation, and `dashboard.onBeforeUnload()` for the unsaved-changes warning. No collection here, so no table hook.
-
-### Order Management
-
-**Request:** "Create an admin panel for customer orders"
-
-**Output:** A `@wix/patterns` `CollectionPage` + `Table`, with filters, sorting, and row actions from the collection APIs — **not** a hand-built WDS filter bar. Status badges are WDS leaf UI in a cell. Viewing or editing an order opens an `EntityPage` via `navigateToEntityPage`, not a modal; a Dashboard Modal appears only for the delete confirmation.
-
-### Embedded Script Configuration
-
-**Request:** "Create a settings page for the coupon popup embedded script"
+Each starts from a case in [DRAFT_TEMPLATE.md](dashboard-page/DRAFT_TEMPLATE.md) — copy that case's files, then adapt. Only what differs per request is listed below; the wiring lives solely in the template.
 
-**Output:** A `@wix/patterns` `SettingsPage` with WDS form fields (popup headline, coupon code, minimum cart value, enable toggle). `embeddedScripts.getEmbeddedScript()` loads the parameters on mount, `embeddedScripts.embedScript()` saves them back — both sides string-converted, per [Dynamic Parameters](dashboard-page/DYNAMIC_PARAMETERS.md).
+| Request | Case | Adapt |
+| --- | --- | --- |
+| "Dashboard page to manage blog posts" | B | Columns for the post fields named; search, row actions and empty state from the collection's own APIs; add/edit navigate to the `EntityPage`; `{feature}-api.ts` calls `@wix/blog` |
+| "Settings page for notification preferences" | C | `SettingsPage` shell with a WDS field per preference (`FormField`, `Input`, `ToggleSwitch`); save confirms with `dashboard.showToast()`, and `dashboard.onBeforeUnload()` warns on unsaved changes — no collection, no table hook, no router |
+| "Admin panel for customer orders" | B | Filters, sorting and row actions from the collection APIs — **not** a hand-built WDS filter bar; status `Badge` is leaf UI in a cell; data source is `@wix/ecom`, never CMS (see [SDK-First Rule](../SKILL.md#sdk-first-rule-existing-wix-app-data-is-never-cms)); viewing or editing opens the `EntityPage`, and a Dashboard Modal appears only for the delete confirmation (see [Entity create and edit](../SKILL.md#entity-create-and-edit)) |
+| "Settings page for the coupon popup embedded script" | C | Fields for headline, coupon code, min cart value, enable toggle; swap `fetch`/`onSave` for `embeddedScripts.getEmbeddedScript()`/`embedScript()`, string-converted both ways (see [Dynamic Parameters](dashboard-page/DYNAMIC_PARAMETERS.md)); use `withProviders` in place of the template's plain provider |
+| "Admin page to manage fees, with an app settings section" | D | One extension, not several — fee fields/calls into all four route components. Skipping the router's `location` plumbing here passes `tsc`/`wix build` silently and fails only in a browser |
 
 
 ## API Spec Support

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

@@ -33,10 +33,15 @@ The CLI manages a shared aggregator file (`data-collections.extension.ts`) that
 
 ## Collection File Shape
 
-The CLI scaffolds `<CollectionName>.ts` as a `satisfies DataCollection` default export. The scaffolded `fields` and `dataPermissions` are placeholders — replace them with your real schema, and set permissions per the [Context-Based Permission Rules](#context-based-permission-rules) before shipping.
+The CLI scaffolds `<CollectionName>.ts` as a `satisfies DataCollection` default export. The scaffolded `fields` and `dataPermissions` are placeholders — replace them with your real schema, and set permissions per [Permissions](data-collection/PERMISSIONS.md) before shipping.
+
+**Import `DataCollection` from the package this project actually uses.** A standalone
+`@wix/custom-extensions` project — what `wix generate` scaffolds today — emits
+`from '@wix/custom-extensions'`; only an Astro project uses `'@wix/astro/builders'`. The scaffolded
+file already has the right one: keep the import the CLI wrote and replace the body around it.
 
 ```typescript
-import type { DataCollection } from '@wix/astro/builders';
+import type { DataCollection } from '@wix/custom-extensions'; // or '@wix/astro/builders' in an Astro project
 
 export const collectionIdSuffix = '<CollectionName>';
 
@@ -51,227 +56,19 @@ export default {
 } satisfies DataCollection;
 ```
 
-## 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` with a `fields` array.** When using `type: "OBJECT"`, you MUST include `objectOptions: { fields: [] }` — the API will reject OBJECT fields without it. Use an empty `fields` array if you don't need a fixed schema (the object will still accept arbitrary JSON):
-
-```json
-{
-  "key": "settings",
-  "displayName": "Settings",
-  "type": "OBJECT",
-  "objectOptions": { "fields": [] }
-}
-```
-
-> ⚠️ `objectOptions: {}` (without the `fields` key) is **not valid** and will cause a runtime error. Always include `fields`, even as an empty array.
-
-For structured objects with a defined schema, list the nested fields inside `objectOptions.fields`:
-
-```json
-{
-  "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
-
-```ts
-{
-  key: 'email',                         // required, lowerCamelCase ASCII
-  type: 'TEXT',                         // required, see Field Types above
-  displayName: 'Email Address',         // optional, CMS label
-  description: "User's primary email",  // optional, help text
-  encrypted: false,                     // optional, encrypt value at rest
-  // arrayOptions / objectOptions / referenceOptions / multiReferenceOptions
-  // only when type is ARRAY / OBJECT / REFERENCE / MULTI_REFERENCE
-}
-```
-
-| Property      | Required | Description                          |
-| ------------- | -------- | ------------------------------------ |
-| `key`         | yes      | Field identifier (lowerCamelCase)    |
-| `type`        | yes      | Field data type (see Field Types)    |
-| `displayName` | no       | Label shown in CMS                   |
-| `description` | no       | Help text                            |
-| `encrypted`   | no       | Encrypt value at rest                |
-
-**There is no field-level `required`, `defaultValue`, or `unique`.** The `DevCenterDataCollectionField` type does not accept them and TypeScript will reject the build. Use these alternatives instead:
+## The rest of this extension
 
-- **Required values:** Validate in the dashboard form and/or service-plugin handler before inserting. Do not rely on the collection schema to enforce presence.
-- **Defaults:** Set defaults in the insert path (dashboard handler, service plugin) or via the collection's `initialData` for seeded rows.
-- **Uniqueness:** Declare a unique index in the collection's `indexes` array (see [Indexes](#indexes)). Uniqueness is an index-level concern, not a field-level one.
-
-## Indexes
-
-The `indexes` array on the collection accepts entries shaped like:
-
-```ts
-indexes: [
-  {
-    fields: [{ path: 'email', order: 'ASC' }],  // order is optional: 'ASC' | 'DESC'
-    unique: true,                                // optional, enforces uniqueness across items
-  },
-  {
-    fields: [
-      { path: 'category' },
-      { path: '_createdDate', order: 'DESC' },
-    ],
-  },
-],
-```
-
-| Property        | Required | Description                                            |
-| --------------- | -------- | ------------------------------------------------------ |
-| `fields`        | yes      | One or more `{ path, order? }` entries (composite index when more than one) |
-| `fields[].path` | yes      | Field key to index                                     |
-| `fields[].order`| no       | `'ASC'` (default) or `'DESC'`                          |
-| `unique`        | no       | Enforce uniqueness on the indexed field(s)             |
-
-Leave `indexes: []` when no custom indexing is needed; the `_id` index is created automatically.
-
-## 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`
+| Topic | File |
+| --- | --- |
+| Field types, field properties, indexes, naming, system fields, relationships | [data-collection/SCHEMA.md](data-collection/SCHEMA.md) |
+| Releasing, updating the site, the CMS prerequisite, item vs. management access | [data-collection/LIFECYCLE.md](data-collection/LIFECYCLE.md) |
+| Reading and writing items at runtime (Wix Data SDK) | [data-collection/WIX_DATA.md](data-collection/WIX_DATA.md) |
 
 ## 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. |
-
-Use `SITE_MEMBER_AUTHOR` on `itemUpdate` / `itemRemove` when members should only modify their **own** items (e.g., a member can edit only their own reviews).
-
-**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.
-
-## 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
-
-## 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.
+The four contexts, what each admits, and the `SITE_MEMBER_AUTHOR` rule are in
+[data-collection/PERMISSIONS.md](data-collection/PERMISSIONS.md). The scaffolded `dataPermissions`
+are placeholders — `ANYONE` to read, `PRIVILEGED` to write — so set them before shipping.
 
 ## Wix CLI-Specific Constraints