@wix/agent-skills 1.21.0 → 1.22.0

package/package.json

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

@@ -23,19 +23,28 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
   - [ ] Explained recommendation with reasoning
 - [ ] **Step 2:** Read extension reference file(s) for the chosen type(s) and the project-wide [CODE_QUALITY.md](references/CODE_QUALITY.md)
   - [ ] **Dashboard page UI:** Translated the prompt into a workflow before choosing components — what the user must understand, focus on, investigate, act on, and see confirmed. See [UX Success Model](references/dashboard-page/UX_SUCCESS_MODEL.md), and the installed package's own `Collection Toolkit.md` guide for which component serves each need ([The Discovery Chain](references/WIX_PATTERNS_DOCS.md#the-discovery-chain)).
-    - [ ] **A row the user can open** — WDS `SidePanel` to inspect without losing the filtered list, or `EntityPage` for deep or shareable detail — unless the prompt is explicitly a report or an export.
+    - [ ] **No `SummaryBar` unless the request asked for one** — a named total, count, or "how many / how much" figure in the prompt. Not "the page seems like it wants one": an uninvited bar pushes the rows down and puts a number on screen nobody asked to be right about. When the request did ask, the number has to come from something that counts ([QUERY_AND_PAGING.md](references/dashboard-page/QUERY_AND_PAGING.md#what-fetchtotal-is-allowed-to-call)) and be read through `useSelector`, because the state is MobX ([TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md#reading-state-outside-the-table-it-is-mobx)).
+    - [ ] **A row the user can open, as a page** — `navigateToEntityPage` to an `EntityPage` when the record is editable, or to a read-only detail route when it isn't ([DRAFT_TEMPLATE_ROUTER.md § 4](references/dashboard-page/DRAFT_TEMPLATE_ROUTER.md#4-read-only-detail-route--case-a)) — unless the prompt is explicitly a report or an export. **Never a `SidePanel`**: in Cairo that hosts a page's own panels, and no `example-bm` collection opens a row into one. The read-only route is a WDS `Page`, because `EntityPage` has no view mode — verified at 1.471.0, where `fetch` and `onSave` are both required and `ActionsBarConfig` can retext Save but not remove it.
     - [ ] **Every filter reaches the query**: declared in the collection hook's `filters` and read inside `fetchData`. Filter UI that never narrows the rows is a defect that looks like a feature.
 
-    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.
+    A filtered table with no drill-in and no working filters is what gets built when nobody states the requirement — the most common way a generated dashboard disappoints. The aggregate is the judgment call; the drill-in and the filters are not.
+  - [ ] **🛑 Template-First Gate (MANDATORY, dashboard UI only, comes before writing any shell/provider/router):** Identified which case in [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md#which-case-matches-the-request) — A (collection only), B (collection + entity), C (settings only), or D (all three) — matches what Step 2's workflow analysis above just established — then copied and adapted that case's files. Composing the page shell, provider nesting, or router wiring from scratch when a case already shows it is the failure mode this gate exists to prevent — the Patterns/Component Docs gates below are for what the matching case's files don't cover, not a replacement for starting there.
   - [ ] **🛑 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 — `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.
+
+    For the object `useTableCollection()` returns, read [TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md) — a state object you receive rather than construct, whose members are unobvious and several plausible ones absent.
 - [ ] **Step 3:** Checked API references; used MCP discovery only for gaps
+  - [ ] **Dashboard page over Wix data:** located the method and verified every mapped field against the installed SDK's own declaration first — see [DATA_SOURCES.md](references/dashboard-page/DATA_SOURCES.md), and [QUERY_AND_PAGING.md](references/dashboard-page/QUERY_AND_PAGING.md) before writing `fetchData`. A field marked `@deprecated` still compiles and renders something plausible and wrong.
+  - [ ] **Vertical SDK prerequisites — for every `@wix/*` vertical the page touches, including one added later:** confirmed the package is actually a dependency (installed it if not), and noted the Dev Center permission scope the read needs — a missing scope produces a page that builds, mounts and shows nothing. Both in [DATA_SOURCES.md](references/dashboard-page/DATA_SOURCES.md#two-things-to-settle-before-you-write-the-page); the scope goes under [Manual Steps Required](#-manual-steps-required). **A second vertical added during Step 4b needs this check too, and its failure must not take down the page** — see [A second vertical is a second scope](references/dashboard-page/DATA_SOURCES.md#a-second-vertical-is-a-second-scope).
+  - [ ] **Modelled the call on the SDK, not the REST page:** namespace name, `_id` vs `id`, no `ReturnType` on overloaded methods, no `hasNext` on `PagingMetadataV2` — see [The SDK is not the REST API](references/dashboard-page/DATA_SOURCES.md#the-sdk-is-not-the-rest-api).
   - [ ] 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`
 - [ ] **Step 4b:** Filled in business logic in the generated files
+  - [ ] **Compile as you go:** ran `npx tsc --noEmit` after the first file that imports `@wix/patterns`, not only at Step 5. Patterns' state and filter APIs are the most common source of errors, and finding twenty of them in one batch after the page is written costs far more than finding two early.
   - [ ] **🛑 Component Selection Gate (MANDATORY, dashboard UI only):** For every UI element on a Dashboard Page, resolved it against `@wix/patterns` BEFORE reaching for `@wix/design-system` — and never hand-rolled a component either library already provides. See [Component Selection Order](#component-selection-order).
   - [ ] Invoked `wix-design-system` skill ONLY before editing the first `.tsx`/`.jsx` file that imports `@wix/design-system`. Skip for backend-only or data-only extensions.
   - [ ] WDS: imported `@wix/design-system/styles.global.css` in the main component entry file (`page.tsx`, modal `.tsx`, etc.) — not child/tab/helper files.
+- [ ] **Step 4c (dashboard page UI only):** Re-opened and read the page file(s) just written — not recalled intent — and confirmed against the actual code: no `SummaryBar` unless the request asked for one, a routed drill-in (`navigateToEntityPage`) for every row and no `SidePanel` used as one, every declared filter name also appearing inside `fetchData`, and — for Cases A/B/D — the entry file both passes and guards `location`. See [UX Completeness Self-Audit](#step-4c-ux-completeness-self-audit).
 - [ ] **Step 5:** Ran validation (see [Validation](#validation))
   - [ ] Dependencies installed
   - [ ] TypeScript compiled
@@ -79,7 +88,9 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 
 ## Component Selection Order
 
-Dashboard pages at Wix are built from two libraries. For **every** UI element, resolve in this order and stop at the first hit. Never skip a step, and never decide a component is missing from memory — check.
+**For the page shell, provider nesting, and routing — the part every dashboard page needs — start from [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md), not this section.** It has four verified cases (collection only, collection+entity, settings only, all three); pick the one the request matches and adapt it. What follows here is for individual UI elements the matching case's files don't already show — a filter type, a column renderer, a component the request needs that isn't in the skeleton.
+
+Dashboard pages at Wix are built from two libraries. For **every** UI element not already covered by the template, resolve in this order and stop at the first hit. Never skip a step, and never decide a component is missing from memory — check.
 
 ### 1. `@wix/patterns` — page structure and data collections
 
@@ -94,6 +105,9 @@ up rather than assembling it from WDS parts.
 that answer as guides inside the installed package, with every component name in them checked
 against the real package at build time. Walk them: [The Discovery Chain](references/WIX_PATTERNS_DOCS.md#the-discovery-chain).
 
+One thing this skill owns rather than the guides: a **worked router skeleton** for multi-page
+extensions (Cases B/D), in [DRAFT_TEMPLATE_ROUTER.md](references/dashboard-page/DRAFT_TEMPLATE_ROUTER.md).
+
 The short version — probe `<pkgRoot>/dist/docs/index.json` first (`grep`/`python3`, not a
 whole-file `Read`), then the guides it lists. From
 there the index answers per symbol: `importPath` is the import line (no read needed), `examples`
@@ -118,6 +132,19 @@ node <wix-design-system-skill-dir>/scripts/wds.cjs search <keyword>
 node <wix-design-system-skill-dir>/scripts/wds.cjs component <Name>
 ```
 
+**If that skill is not installed** — it is a separate skill, and some hosts ship `wix-app` without
+it — do **not** fall through to writing WDS from memory, and do not treat the missing skill as
+permission to hand-roll the component. Read the installed package instead, which is where the skill
+would have read from anyway:
+
+```bash
+ls node_modules/@wix/design-system/dist/types/            # the component inventory
+cat node_modules/@wix/design-system/dist/types/<Name>/<Name>.d.ts   # its real props
+```
+
+Name the file you read before using the component, exactly as the Component Docs Gate requires for
+patterns. A missing skill lowers the convenience, not the bar.
+
 ### 3. Custom React — only after both came back empty
 
 Compose from WDS layout primitives (`Box`, `Card`, `Text`). Do not add a third UI dependency, and do not restyle patterns or WDS internals.
@@ -183,6 +210,13 @@ Use a Dashboard Modal for dialogs that neither write nor display a listed record
 | Official Documentation Links | [DOCUMENTATION.md](references/DOCUMENTATION.md) |
 | Wix Patterns Dashboard Pages | [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md) |
 | Dashboard UX Success Model (what a good dashboard contains) | [UX_SUCCESS_MODEL.md](references/dashboard-page/UX_SUCCESS_MODEL.md) |
+| Draft template — start here for any dashboard page (Cases A/B/C/D) | [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md) |
+| Draft template — collection page for Cases A/B/D | [DRAFT_TEMPLATE_COLLECTION.md](references/dashboard-page/DRAFT_TEMPLATE_COLLECTION.md) |
+| Draft template — router wiring for Cases A/B/D, incl. the read-only detail route | [DRAFT_TEMPLATE_ROUTER.md](references/dashboard-page/DRAFT_TEMPLATE_ROUTER.md) |
+| Draft template — settings page for Cases C/D | [DRAFT_TEMPLATE_SETTINGS.md](references/dashboard-page/DRAFT_TEMPLATE_SETTINGS.md) |
+| The state object `useTableCollection()` returns | [TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md) |
+| Finding the SDK method and field names behind a page | [DATA_SOURCES.md](references/dashboard-page/DATA_SOURCES.md) |
+| Filter paths, WQL operators and cursor paging | [QUERY_AND_PAGING.md](references/dashboard-page/QUERY_AND_PAGING.md) |
 
 ---
 
@@ -363,6 +397,28 @@ Open every path returned in `newFiles` and replace stubbed handler bodies / UI /
 - ⚠️ 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 Data Collections: Use the EXACT collection ID from `idSuffix` (case-sensitive). If `idSuffix` is `"product-recommendations"`, use `<app-namespace>/product-recommendations` NOT `productRecommendations`.
 
+### Step 4c: UX Completeness Self-Audit
+
+**Dashboard page UI only.** `tsc`, `wix build`, and `wix preview` all check that the code compiles and runs — none of them check that it's the dashboard the [UX Success Model](references/dashboard-page/UX_SUCCESS_MODEL.md) describes. A page with a bare, un-summarized, un-openable table compiles cleanly and still fails the requirement — that gap is exactly how a generated dashboard passes every technical check and still disappoints. Measured runs confirm it: a page can compile clean and still ship with none of the three items below, because the earlier checklist entries were a stated intention rather than something re-checked against the code that actually landed.
+
+Before moving to Step 5, re-open every page file you just wrote and check the actual code — not what you intended to include:
+
+- [ ] **The page has a `SummaryBar` only if the request asked for one.** Grep for it: an uninvited bar is a defect, not a bonus, and deleting it is the fix. If the request *did* ask, every metric earns its place and the headline counts what **matches the filters** (`state.collection.total`, fed by `fetchTotal`), not what has been paged in — any metric derived from `keyedItems` is labelled as such.
+- [ ] **If a `SummaryBar` number is fed by `fetchTotal`, follow that function to the call it makes and confirm the call counts.** A `fetchTotal` that resolves `undefined` — the usual cause being `pagingMetadata.total`, which a cursor-paged response does not carry — makes the bar report `0` beside a table full of rows, and it compiles, runs and passes every other check on this list. It must resolve a number from a count endpoint (`items.query(id)…count()`, a vertical's own count, or offset paging with `returnTotalCount: true`); if the API has none, delete `fetchTotal` and label the metric as loaded rows. See [TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md#a-fetchtotal-that-resolves-undefined-shows-0-not-the-rows).
+- [ ] **Every row opens a page**: a `navigateToEntityPage` call literally appears in `onRowClick` — unless the prompt is explicitly a report or export-only view. A `SidePanel` in a collection page file is the defect this replaces; a display-only page routes to a read-only detail page, it does not fall back to a panel. `grep -n "<SidePanel" <page files>` should return nothing — match the JSX tag, not the bare word, or the templates' own "never a SidePanel" comments fail the check and invite someone to "fix" correct code.
+- [ ] Every filter name declared in the toolbar also appears inside `fetchData`'s query construction — grep for the name in both places if unsure.
+- [ ] The table wires `errorState` — without it a failed query is indistinguishable from a slow one, and the page you just shipped cannot tell you which it is.
+- [ ] **Case B/D only — the entry file both passes and guards `location`.** `PatternsReactRouter` throws at open when `location` is missing *or* still `undefined` on the first render, and `tsc`, `wix build` and even a green build all pass regardless. Both halves are required — the `location={location}` prop **and** the `location ? … : null` guard around it, since `observeState` has not fired yet on the first render. Grep the entry file rather than trusting recall:
+
+  ```bash
+  grep -n "observeState\|location={location}\|location ?" src/extensions/dashboard/pages/<page>/<page>.tsx
+  ```
+
+  Three hits is correct. A missing guard is the failure mode that has actually shipped: a measured run produced a page whose plumbing looked present and still crashed on open, while a re-run of the same prompt produced a working one — so this is intermittent, and re-running is not a check.
+- [ ] Every `@wix/*` vertical imported by the page's api module is a declared dependency, and each one's scope is listed under Manual Steps. Any call to a **secondary** vertical (an enrichment lookup, a filter's options, a search term resolved to ids) is wrapped so its failure degrades that feature instead of failing the page.
+
+If a box fails and no exception applies, add the missing piece now. Do not let "it compiles" stand in for "it satisfies the checklist" — Step 5 checks the former, this step checks the latter, and they are independent.
+
 ### Step 5: Run Validation
 
 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.
@@ -419,7 +475,7 @@ The following actions need to be done manually by you:
 
 ## Validation
 
-Execute these steps sequentially after all implementation is complete. See [APP_VALIDATION.md](references/APP_VALIDATION.md) for the complete guide.
+Execute these steps sequentially after all implementation is complete. See [APP_VALIDATION.md](references/APP_VALIDATION.md) for the complete guide. Dashboard page UI: run [Step 4c's UX Completeness Self-Audit](#step-4c-ux-completeness-self-audit) first — the checks below verify the code runs, not that it's the dashboard the prompt asked for.
 
 1. **Package Installation** — Detect package manager, run install
 2. **TypeScript Compilation** — `npx tsc --noEmit -p .`

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