@wix/agent-skills 1.25.0 → 1.26.0

package/package.json

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

@@ -24,12 +24,12 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 - [ ] **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)).
     - [ ] **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.
+    - [ ] **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 (the package's `Collection and Read-Only Detail Template`, reached from [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md)) — unless the prompt is explicitly a report or an export. **Never a `SidePanel`**: in Cairo that hosts a page's own panels. The template's page says why the read-only route is a WDS `Page` rather than an `EntityPage`.
     - [ ] **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 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. The reverse holds too: a case replaces composing the shell, never the discovery chain, so every symbol the case doesn't show still goes through the next gate.
-  - [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md) **before the first command that touches `node_modules/@wix/patterns`** — its discovery chain (`pkg-root.cjs`, the index, `Composition and Providers.md` once, `Collection Toolkit.md` for which component serves a need) lives only in that file, and this line is a summary of its step 1, not a substitute for opening it. 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).
+  - [ ] **🛑 Template-First Gate (MANDATORY, dashboard UI only, comes before writing any shell/provider/router):** Followed [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md): found the page templates the installed `@wix/patterns` ships, chose one with its `Page Templates.md` guide — which pages the workflow above needs, **and where the rows come from** (your own fetch, or a CMS collection) — read that template's page, and copied every file in its `templateFiles`. Composing the page shell, provider nesting, or router wiring from scratch when a template already shows it is the failure mode this gate exists to prevent — the Patterns/Component Docs gates below are for what the template doesn't cover, not a replacement for starting there. The reverse holds too: a template replaces composing the shell, never the discovery chain, so every symbol it doesn't show still goes through the next gate.
+  - [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md) **before the first command that touches `node_modules/@wix/patterns`** — its discovery chain (`pkg-root.cjs`, the index, `Composition and Providers.md` once, `Collection Toolkit.md` for which component serves a need) lives only in that file, and this line is a summary of its step 1, not a substitute for opening it. 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), `dist/dts-bundle/` (types) and `dist/templates/` (whole pages) 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.
@@ -45,7 +45,7 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
   - [ ] 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: the design-system stylesheets are imported in exactly one place per app — `BusinessManagerTheme.tsx` for a dashboard surface (see the next item), or the main component entry file for a site/editor extension. Never in child, tab or helper files, and never twice.
   - [ ] **🛑 Business Manager theme (every dashboard surface — page, modal AND plugin):** wrote `BusinessManagerTheme.tsx` once (both stylesheets, including `themes/odeditor.global.css`, plus `WixDesignSystemProvider` → `WixDesignSystemIconThemeProvider` → `IconThemeProvider theme="odeditor"` → `WixDesignSystemDefaultPropsProvider`), and wrapped **each** extension's root in it — above `WixPatternsProvider` and above `CustomModalLayout`. Every extension is a separate iframe that inherits none of the redesign, so theming the page does nothing for a modal it opens or a plugin in a slot; each one needs its own wrapper. Also: every icon from `@wix/wix-ui-icons-common/lazy`, and `--wds-*` tokens or `skin`/`size` props rather than hardcoded colours, font sizes or inline `style` ([BUSINESS_MANAGER_TOKENS.md](references/BUSINESS_MANAGER_TOKENS.md) — note the theme rebases the `SP*` spacing unit from 6px to 4px). `tsc`, `wix build` and `wix preview` all pass on an unthemed surface — only looking at it catches this. See [BUSINESS_MANAGER_THEME.md](references/BUSINESS_MANAGER_THEME.md).
-- [ ] **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 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 every template with a router — 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
@@ -89,7 +89,7 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 
 ## Component Selection Order
 
-**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.
+**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 finds the page templates the installed `@wix/patterns` ships (read-only list, list with create/edit, settings only, and a CMS collection on its schema); copy the one the request matches and adapt it. What follows here is for individual UI elements the template doesn't already show — a filter type, a column renderer, a component the request needs that isn't in it.
 
 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.
 
@@ -106,8 +106,10 @@ 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).
+Whole pages are the package's too: the router wiring for a multi-page extension, and a
+**collection whose fields the CMS owns** — `useCmsSchemaSource` from `@wix/patterns-cms`, with
+`@wix/patterns/schema`, where the schema supplies fetch, filters, columns and the form — both ship
+as page templates. See [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md).
 
 The short version — probe `<pkgRoot>/dist/docs/index.json` first (`grep`/`python3`, not a
 whole-file `Read`), then the guides it lists. From
@@ -213,10 +215,7 @@ Use a Dashboard Modal for dialogs that neither write nor display a listed record
 | Business Manager theme — the wrapper every dashboard page, modal and plugin needs | [BUSINESS_MANAGER_THEME.md](references/BUSINESS_MANAGER_THEME.md) |
 | Business Manager tokens — `--wds-*` replacements, the rebased spacing unit, per-component adjustments | [BUSINESS_MANAGER_TOKENS.md](references/BUSINESS_MANAGER_TOKENS.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) |
+| Draft template — start here for any dashboard page: finding, copying and adapting the package's page templates | [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.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) |
@@ -419,10 +418,10 @@ Before moving to Step 5, re-open every page file you just wrote and check the ac
 - [ ] **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:
+- [ ] **Routed templates only (all but the settings one) — 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
+  grep -n "observeState\|location={location}\|location ?" src/extensions/dashboard/pages/<page>/<page>.tsx  # the file the builder's `component` points at
   ```
 
   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.

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

@@ -71,8 +71,7 @@ A prop on a component still wins over the provider, so a one-off `size="medium"`
 
 | Surface | File | Section |
 | --- | --- | --- |
-| Page, Cases A/B/D (router-wired) | `{feature}.tsx` | [DRAFT_TEMPLATE_ROUTER.md § 1](dashboard-page/DRAFT_TEMPLATE_ROUTER.md#1-entry--location-is-manual-in-a-wix-cli-app-and-only-because-the-router-needs-it) |
-| Page, Case C (settings only) | `{feature}.tsx` | [DRAFT_TEMPLATE.md § 1](dashboard-page/DRAFT_TEMPLATE.md#1-entry--case-c-only-router-free-no-location-plumbing) |
+| Page, from any `@wix/patterns` page template | `{feature}.tsx`, holding the template's `page.tsx` | [DRAFT_TEMPLATE.md § 3](dashboard-page/DRAFT_TEMPLATE.md#3-copy-it-into-the-extension) |
 | Page with dynamic parameters | `withProviders.tsx` | [DYNAMIC_PARAMETERS.md](dashboard-page/DYNAMIC_PARAMETERS.md#provider-wrapper-implementation) |
 | Modal | the generated `<modal>.tsx` | [DASHBOARD_MODAL.md](DASHBOARD_MODAL.md#theme) |
 | Plugin | the generated plugin component | [DASHBOARD_PLUGIN.md](DASHBOARD_PLUGIN.md#theme) |

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

@@ -77,5 +77,5 @@ Two rows from the design-side migration note have **no API to land on at 1.330.0
 
 **Several adjustments the providers already make for you** — don't redo them by hand: a nested icon button is Dark / Tertiary from the wrapper's `IconButton` default, and `WixDesignSystemIconThemeProvider` already supplies the Accordion caret. `Accordion`, `CloseButton`, `Tooltip`, `Popover`, `Thumbnail`, `SidePanel` and ~20 more are all legal keys of `WixDesignSystemDefaultProps`, so anything you find yourself repeating per call site probably belongs in `BUSINESS_MANAGER_DEFAULTS` instead.
 
-Two genuine author decisions remain: a **standalone** text button uses the standard (blue) skin while one beside a primary or secondary button uses Dark; and empty states are **typography only**, no legacy illustrations (on a collection page the empty state comes from the patterns shell — [DRAFT_TEMPLATE_COLLECTION.md](dashboard-page/DRAFT_TEMPLATE_COLLECTION.md)).
+Two genuine author decisions remain: a **standalone** text button uses the standard (blue) skin while one beside a primary or secondary button uses Dark; and empty states are **typography only**, no legacy illustrations (on a collection page the empty state comes from the patterns shell — the page template's, [DRAFT_TEMPLATE.md](dashboard-page/DRAFT_TEMPLATE.md)).
 

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

@@ -29,13 +29,13 @@ wix generate --params '{"extensionType":"DASHBOARD_PAGE","title":"<title>","rout
 | `title` | Display name shown in the dashboard sidebar. |
 | `route` | URL path segment (lowercase alphanumeric + hyphens). The page is served at `/dashboard/<route>`. The scaffold param is `route`; the builder file's runtime field is `routePath`. |
 
-The CLI generates the folder, `page.tsx`, the builder file, the UUID, and the `src/extensions.ts` registration. After scaffolding, implement the page UI in the generated `page.tsx`.
+The CLI generates the folder, the page's component file (`<page>.tsx`, the builder's `component`), the builder file, the UUID and the `src/extensions.ts` registration.
 
-**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`.
+**After scaffolding, check `routePath`:** use `support-tickets`, not `/support-tickets`; a leading slash fails registration even if the build passes. Internal router paths stay `/`, `/:id`, `/new`, never prefixed with `<route>` — see `<pkgRoot>/dist/docs/Collection to Entity Flow.md`.
 
-**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.
+**Before writing that UI:** copy in the installed `@wix/patterns` page template that matches, per [DRAFT_TEMPLATE.md](dashboard-page/DRAFT_TEMPLATE.md) — 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.
+**Then, for whatever the template doesn't cover:** probe `<pkgRoot>/dist/docs/index.json` once with `grep`/`python3` — never a whole-file `Read`, which truncates silently ([Prerequisites](WIX_PATTERNS_DOCS.md#prerequisites)). Its `importPath`, `examples` and `bundle` decide whether you open anything else. Each Bash call is a fresh shell — re-set the path variable every time.
 
 ## Capabilities
 
@@ -90,15 +90,15 @@ When building a dashboard page to configure an embedded script, see [Dynamic Par
 
 ## Examples
 
-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.
+Each starts from one of the package's page templates, found through [DRAFT_TEMPLATE.md](dashboard-page/DRAFT_TEMPLATE.md) — copy its files, then adapt. Only what differs per request is listed below; the wiring lives solely in the template.
 
-| Request | Case | Adapt |
+| Request | Template | 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 |
+| "Dashboard page to manage blog posts" | Collection and Entity | 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" | Settings Page | `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" | Collection and Entity | 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" | Settings Page | 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" | Collection and Entity, plus the Settings Page's settings page as one more route | One extension, not several — fee fields/calls into every route component. 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/WIX_PATTERNS_DOCS.md

@@ -12,7 +12,7 @@ Then check the install, two ways: `ls <pkgRoot>/dist/dts-bundle/index.json`, and
 
 **If either fails, stop and upgrade `@wix/patterns`.** "Which component serves this need" now lives in the package, so proceeding means guessing names; do not hunt elsewhere in `node_modules` for a substitute. Everything below degrades by version rather than breaking, so probe rather than version-check.
 
-**Patterns API facts come from three published trees only:** `dist/docs/` (pages), `dist/dts-bundle/` (types), `dist/examples/` (worked calls). Never take a component, prop or type from `src/`, `dist/esm/` or `dist/cjs/`, or a deep path a bundle mentions — internals change without notice. `dist/types/` is one narrow exception, used only where step 5 says: `package.json` points `types` at it, so it is what `tsc` enforces. Within those trees, `grep`/`sed` for one declaration usually beats a whole-file read.
+**Patterns API facts come from four published trees only:** `dist/docs/` (pages), `dist/dts-bundle/` (types), `dist/examples/` (worked calls), `dist/templates/` (whole pages). Never take a component, prop or type from `src/`, `dist/esm/` or `dist/cjs/`, or a deep path a bundle mentions — internals change without notice. `dist/types/` is one narrow exception, used only where step 5 says: `package.json` points `types` at it, so it is what `tsc` enforces.
 
 ## The Discovery Chain
 
@@ -38,6 +38,7 @@ Start here rather than the bundle index: it carries every documented name *and*
 
 | Building | Guide |
 | --- | --- |
+| A whole page | `dist/docs/Page Templates.md`, via [DRAFT_TEMPLATE.md](dashboard-page/DRAFT_TEMPLATE.md) |
 | Anything collection-shaped — tables, filters, search, aggregates, row and bulk actions, empty states | `dist/docs/Collection Toolkit.md` |
 | The path from a listed row to one record, and its form | `dist/docs/Collection to Entity Flow.md` |
 
@@ -53,7 +54,7 @@ Each guide's index entry carries `relatedComponents`; every name in it resolves,
 | What props, and which are optional? | the **example** first; then the **`.d.ts`** *or* the doc — never both | `bundle` present: `dist/dts-bundle/<bundle>` · absent: `dist/docs/<file>` |
 | A setup requirement or gotcha? | the **doc's** prose | `dist/docs/<file>` |
 
-Prefix the index's bare values with their tree — `file` → `dist/docs/`, `examples` → `dist/examples/`, `bundle` → `dist/dts-bundle/` — and never rebuild a path from a symbol name.
+Prefix the index's bare values with their tree — `file` → `dist/docs/`, `examples` → `dist/examples/`, `bundle` → `dist/dts-bundle/`, `templateFiles` → `dist/templates/` — and never rebuild a path from a symbol name.
 
 **Those two middle rows are one question in practice.** You ask how to call it, start writing, and the question turns prop-shaped mid-call — where the second row sends you to a `.d.ts` that may be stubbed (step 5). Take the props off the example first; go to the `.d.ts` only for what it cannot show — optionality, union members, an exact callback signature.
 

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

@@ -1,98 +1,95 @@
 # Draft Template — the starting point for every dashboard page
 
-**Start here for any Dashboard Page request, before writing a shell, provider, or router from scratch.** Pick the case below, copy its files, rename, and adapt fields/API calls/data source. Only leave this file when the request needs something no case shows, and then go to [WIX_PATTERNS_DOCS.md](../WIX_PATTERNS_DOCS.md) first — before any lookup inside `node_modules/@wix/patterns`, `index.json` included. It routes you to the package's own `Collection Toolkit.md` guide, a component doc or an example; [TABLE_STATE.md](TABLE_STATE.md) and MCP lookups come after it.
+**Start here for any Dashboard Page request, before writing a shell, provider, or router from scratch.** The templates themselves ship inside the installed `@wix/patterns`: whole, working pages that the package type-checks against its own release, so they never drift from the version your code compiles against. This file says how to find one, where its files go in a Wix CLI app, and what this skill adds on top. Which template fits, and the wiring each one must keep, is the package's answer — read it there.
 
-Every snippet below was copied from the installed `dist/docs/*.md` and `dist/dts-bundle/*.d.ts`, not from memory — confirm props against your own installed version before deviating.
+Go through [WIX_PATTERNS_DOCS.md § Prerequisites](../WIX_PATTERNS_DOCS.md#prerequisites) first for `<pkgRoot>`; every path below is relative to it.
 
-## Which case matches the request?
+## 1. Find the templates
 
-| The request needs… | Case | Router? |
-| --- | --- | --- |
-| A list/report whose rows are read-only — no create/edit form | **A — Collection + read-only detail** | Yes |
-| A list **and** create/edit for each record (no separate app-settings area) | **B — Collection + Entity** | Yes |
-| Only app-wide settings/config — no list at all | **C — Settings only** | No |
-| A list, create/edit, **and** an app-settings area, all in one extension | **D — Collection + Entity + Settings** | Yes |
+Templates are docs-index entries with `category: "Templates"`, and each lists every file of its page in `templateFiles` (relative to `dist/templates/`). One probe lists them all with the guide that chooses between them:
 
-Don't default to D because it's the most complete — [Step 4c's checklist](../../SKILL.md#step-4c-ux-completeness-self-audit) doesn't ask for a settings or entity page unless the request needs one. If unsure between B and D, re-read the prompt for "settings," "configure," "preferences" — their absence means B.
-
-## Then: what `fetchData` calls
-
-Case tells you how many pages. This tells you only what `fetchData` calls — the page itself is
-[DRAFT_TEMPLATE_COLLECTION.md](DRAFT_TEMPLATE_COLLECTION.md) either way:
+```bash
+python3 -c "
+import json; i = json.load(open('<pkgRoot>/dist/docs/index.json'))
+for k, e in i.items():
+    if e.get('category') == 'Templates' or e.get('relatedTemplates'):
+        print(k, '|', e.get('templateFiles') or e.get('relatedTemplates'), '|', e.get('summary', '')[:200])
+"
+```
 
-| The rows come from | `fetchData` calls |
-| --- | --- |
-| A vertical SDK (`@wix/bookings`, `@wix/ecom`, …) or any API you call yourself | that SDK's own query method — [DATA_SOURCES.md](DATA_SOURCES.md) |
-| A **CMS collection** — one your Data Collection extension ships, or an existing site collection | `@wix/data` `items.query()` — [WIX_DATA.md](../data-collection/WIX_DATA.md) |
+**No `Templates` entries means the install predates them — upgrade `@wix/patterns`.** Do not rebuild a page from memory or from an older copy of this skill instead: the templates exist so the shell, provider nesting and router wiring come from the package.
 
-A CMS collection is not a different template, just a different call inside the same one: you write
-`fetchData`, the filters and the columns for both.
+## 2. Choose, then read the chosen template's page
 
-**Cases B and D both need a router** — their entry file, app shell, and entity page are in [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md). The collection and settings files are shared by every case that uses them, B and D included; the router file links back rather than repeating them.
+1. `Read <pkgRoot>/dist/docs/Page Templates.md` — which pages the request needs (read-only list, list with create/edit, settings only, or list with create/edit and settings) and where the rows come from (your own fetch, or a CMS collection).
+2. `Read` the chosen template's page (`dist/docs/<entry file>`) — its files, and the wiring to keep. Most of that wiring passes `tsc` and `wix build` when wrong and fails only in the browser, which is why [Step 5's Preview](../../SKILL.md#validation) is not optional for a routed page.
 
-## File layout
+Take the smallest template that covers what the request names. A settings area or an edit form nobody asked for is not "more complete" — [Step 4c's checklist](../../SKILL.md#step-4c-ux-completeness-self-audit) does not ask for one.
 
-```
-src/extensions/dashboard/pages/{feature}/
-  {feature}.extension.ts        # single wix generate scaffold — always exactly one route registered here
-  {feature}.tsx                 # entry — Case C: Section 1 below. Cases A/B/D: DRAFT_TEMPLATE_ROUTER.md
-  {Feature}App.tsx              # Case A/B/D only — see DRAFT_TEMPLATE_ROUTER.md
-  {Feature}CollectionPage.tsx   # Case A, B, D — see DRAFT_TEMPLATE_COLLECTION.md
-  {Feature}DetailPage.tsx       # Case A only — read-only detail route, DRAFT_TEMPLATE_ROUTER.md §4
-  {Feature}EntityPage.tsx       # Case B, D only — see DRAFT_TEMPLATE_ROUTER.md
-  {Feature}SettingsPage.tsx     # Case C, D only — see DRAFT_TEMPLATE_SETTINGS.md
-  {feature}-api.ts              # fetch/save calls — keep these out of the components
-```
+## 3. Copy it into the extension
 
-Scaffold with a single call regardless of case — this is always one extension:
+Scaffold once — every template is one extension, however many routes it has:
 
 ```bash
 wix generate --params '{"extensionType":"DASHBOARD_PAGE","title":"<title>","route":"<route>"}'
 ```
 
-## 1. Entry — Case C only (router-free, no location plumbing)
+`route` takes no leading slash — `support-tickets`, not `/support-tickets`. See [Dashboard Page → Scaffold](../DASHBOARD_PAGE.md#scaffold).
+
+Then copy **every** file in `templateFiles` into the generated folder (`src/extensions/dashboard/pages/<feature>/`). They import one another by relative path, so keep their names relative to each other; one file on its own does not compile.
+
+- The template's `page.tsx` is the entry file, and the CLI generated none by that name: put its contents into the component file the builder's `component` path points at (e.g. `employee-shifts.tsx`), and add no separate `page.tsx`, which nothing loads. Leave the builder file and the `src/extensions.ts` registration as the CLI wrote them.
+- Rename `Items` / `Item` to your feature and entity, in file names and identifiers alike.
+- Route paths stay page-relative (`/`, `/:id`, `/new`) — never prefix them with `<route>` ([DASHBOARD_PAGE.md](../DASHBOARD_PAGE.md)).
+
+- **Theme the entry file.** In it, replace the template's `WixDesignSystemProvider` and its `@wix/design-system/styles.global.css` import with the app's `BusinessManagerTheme` — written once per app ([BUSINESS_MANAGER_THEME.md § 2](../BUSINESS_MANAGER_THEME.md#2-the-wrapper--write-this-file-once-per-app)), kept in the entry file so it sits above `WixPatternsProvider`. **Business Manager passes none of the redesign through the extension's iframe**, so the bare provider renders the pre-redesign look while `tsc`, `wix build` and `wix preview` all pass.
+
+## 4. Replace the data file
 
-Case C has one page and no rows to open, so it needs no router and no manual `location` wiring. **Cases A, B and D all route** — a row opens a page of its own in every one of them — so their entry file is [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md) §1:
+Each template's data file (`items-api.ts`, `settings-api.ts`) is an in-memory stand-in with the signatures the pages call. Replace the bodies, keep the signatures:
 
-```tsx
-// {feature}.tsx — Case C
-import type { FC } from 'react';
-import { withDashboard } from '@wix/patterns';
-import { WixPatternsProvider } from '@wix/patterns/provider';
-import { BusinessManagerTheme } from '../../BusinessManagerTheme'; // BUSINESS_MANAGER_THEME.md § 2
-import { {Feature}SettingsPage } from './{Feature}SettingsPage'; // DRAFT_TEMPLATE_SETTINGS.md
+- **Whose data it is decides the call.** Data an existing Wix app owns comes from that app's SDK, never a CMS collection ([SDK-First Rule](../../SKILL.md#sdk-first-rule-existing-wix-app-data-is-never-cms)). The method and field names: [DATA_SOURCES.md](DATA_SOURCES.md). Filter paths, operators and cursor paging: [QUERY_AND_PAGING.md](QUERY_AND_PAGING.md).
+- **A CMS collection uses the CMS template, which has no data file** — its `collection.ts` takes the full scoped id, `<app-namespace>/<idSuffix>` for a collection your extension ships ([DATA_COLLECTION.md](../DATA_COLLECTION.md)). The collection does not exist until the app is released ([LIFECYCLE.md](../data-collection/LIFECYCLE.md#the-extension-does-not-create-the-collection)).
+- **On a CMS collection, the prompt's fields are the collection's fields** — every one a column, none hand-written. For a collection your extension ships, create exactly those fields; an existing site collection shows all its fields, and the user hides the rest in the column picker. A stated column list decides the columns only on the hand-wired path.
 
-const Page: FC = () => (
-  <BusinessManagerTheme>
-    <WixPatternsProvider>
-      <{Feature}SettingsPage />
-    </WixPatternsProvider>
-  </BusinessManagerTheme>
-);
+### Installing the CMS pair
 
-export default withDashboard(Page);
+`@wix/patterns-cms` pins one exact `@wix/patterns` version, and the template's page says why a second copy breaks the page silently.
+
+**Already in `package.json`** (some app templates ship both): don't install it again — go straight to the check. **Not there:** install it, then align `@wix/patterns` to its pin:
+
+```bash
+npm install @wix/patterns-cms
+npm install @wix/patterns@$(node -p "require('@wix/patterns-cms/package.json').dependencies['@wix/patterns']")
 ```
 
-`BusinessManagerTheme` is the app's own wrapper around the design-system providers, the `odeditor` theme stylesheet and the Business Manager default props — [BUSINESS_MANAGER_THEME.md § 2](../BUSINESS_MANAGER_THEME.md#2-the-wrapper--write-this-file-once-per-app) has the file to write once per app. **Business Manager passes none of the redesign through the extension's iframe**, so a bare `WixDesignSystemProvider` here renders the pre-redesign look while `tsc`, `wix build` and `wix preview` all pass. `WixPatternsProvider` nests inside it, never above.
+**Either way, confirm a single copy:**
 
-Cases A, B and D differ — they need `location` supplied manually for `PatternsReactRouter`. See [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md) rather than adding that plumbing here; it's dead code without a router underneath it.
+```bash
+npm dedupe
+find node_modules -path '*@wix/patterns/package.json' -not -path '*/dist/*'
+```
 
-## 2. Collection page — Case A, B, D
+More than one line is a bug that `tsc` and `wix build` both pass. Declared ranges produce it when `@wix/patterns` ships ahead of `@wix/patterns-cms`, or a lockfile holds an older one. Run the second `npm install` line above, then the check again.
 
-In [DRAFT_TEMPLATE_COLLECTION.md](DRAFT_TEMPLATE_COLLECTION.md) — `useTableCollection`, a working
-filter, the four placeholder states, and a row that opens. Shared by Cases A, B and D. No
-`SummaryBar` unless the request asked for one, and the drill-in is always a route — never a side
-panel.
+### Turning `query.search` into a query
+
+On the hand-wired path the data file turns one search term into a filter over *several* fields — an OR. **This is where search ships broken**: it renders, it reaches the query, and still returns every row. (The CMS template's source does this itself.)
+
+There is no shared free-text operator; the shape differs per endpoint. Read its *Supported Filters* page ([QUERY_AND_PAGING.md](QUERY_AND_PAGING.md#the-filterable-fields-are-a-closed-list-published-per-endpoint)), then `$or` one clause per identity field it lists. Never route the term to a single field by its shape — a measured run shipped this, and one branch is always dead:
+
+```ts
+query = term.includes('@')
+  ? query.startsWith('loginEmail', term)
+  : query.startsWith('contact.firstName', term);  // a surname matches nothing, ever
+```
 
-## 3. Settings page — Case C, D
+`startsWith` is prefix-only too — "Smith" never finds "John Smith" — so prefer the containment operator when the endpoint declares one, and say which you used in `noResultsState`.
 
-In [DRAFT_TEMPLATE_SETTINGS.md](DRAFT_TEMPLATE_SETTINGS.md) — `useSettingsPage` + `useForm`,
-with the same field-controller patterns as the entity page.
+**Whatever the shape, prove it narrows.** Run one term you expect to hit a known row and one you expect to hit nothing, and check the row count changes for both.
 
-## What to change vs. keep, per case
+## 5. What this skill adds to every template
 
-| Change per request | Keep as shown |
-| --- | --- |
-| Feature/entity names, fields, columns, API calls in `{feature}-api.ts` | Which case (A/B/C/D) — don't over-build D for a request that only named a list |
-| Detail fields, form field types, columns | The drill-in being a route, and the absence of a `SummaryBar` the request never asked for |
-| Real data source (SDK-first per [SDK-First Rule](../../SKILL.md#sdk-first-rule-existing-wix-app-data-is-never-cms)) vs CMS | B/D wiring (provider/router nesting, `parentPath`, `location`): [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md) |
+- **No `SummaryBar` unless the request asked for one** — a named total, count or "how many / how much" figure. The templates ship without one on purpose ([SKILL.md § Step 2](../../SKILL.md)).
+- **The state is MobX.** Deriving anything from the collection state in your own component — a header figure, a badge — goes through `useSelector` ([TABLE_STATE.md](TABLE_STATE.md#reading-state-outside-the-table-it-is-mobx)).
+- **Anything the template does not show** — another filter type, a column renderer, a component the request needs — goes through [The Discovery Chain](../WIX_PATTERNS_DOCS.md#the-discovery-chain). A template replaces composing the shell, never the lookup for a symbol it does not contain.

package/skills/wix-app/references/data-collection/LIFECYCLE.md

@@ -17,10 +17,12 @@ about tooling, not evidence about the collection.
 
 ## Reading the collection from a dashboard page
 
-A page over a CMS collection is an ordinary collection page: the template is
-[DRAFT_TEMPLATE_COLLECTION.md](../dashboard-page/DRAFT_TEMPLATE_COLLECTION.md), and its `fetchData`
-calls `@wix/data` `items.query()` — see [WIX_DATA.md](WIX_DATA.md) for the query, result and paging
-shapes. You write the filters and the columns yourself, exactly as for a vertical SDK.
+A page over a CMS collection uses the package's **CMS Collection and Entity Template**, not the
+hand-wired one — the CMS already owns the field list, so `useCmsSchemaSource` supplies fetch,
+filters, columns and the entity form from it. See
+[DRAFT_TEMPLATE.md](../dashboard-page/DRAFT_TEMPLATE.md). Wiring
+`items.query()` and hand-written columns by hand still compiles, and quietly gives up everything the
+schema would have provided.
 
 ## The site must have CMS, or nothing is created at all
 

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

@@ -1,184 +0,0 @@
-# Draft Template — Collection page (Cases A, B and D)
-
-> Pick your case in [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md) first. This page is shared by A, B
-> and D.
-
-> **You write `fetchData`, the filters and the columns.** This holds whatever the rows are: for a
-> CMS collection `fetchData` calls `@wix/data` `items.query()`
-> ([WIX_DATA.md](../data-collection/WIX_DATA.md)) and nothing else on this page changes.
-
-## Two rules this skeleton encodes, so read them before editing it
-
-**Every row opens a page of its own, never a panel.** `onRowClick` navigates —
-`navigateToEntityPage` to an `EntityPage` route when the record is editable, or to a read-only
-detail route when the page is display-only ([DRAFT_TEMPLATE_ROUTER.md § 4](DRAFT_TEMPLATE_ROUTER.md#4-read-only-detail-route--case-a)).
-A WDS `SidePanel` is not the drill-in: in Cairo it is the host for a page's own side panels — the
-fields card's "Manage fields", a table's column panel — and `example-bm` uses it as a row drill-in
-in exactly nothing. Every collection example there navigates.
-
-**No `SummaryBar` unless the request asked for one.** Not "unless the page seems to want one" —
-unless the prompt named a total, a count, or a "how many / how much" figure. It is absent from this
-skeleton on purpose; adding one uninvited pushes the rows down the page and puts a number on screen
-nobody has to be right about. When you do add one, wire it from
-[SKILL.md § Step 2](../../SKILL.md) — no `SummaryBar` unless the request asked for one.
-
-## The collection page
-
-This is the file [Step 4c's UX Completeness Self-Audit](../../SKILL.md#step-4c-ux-completeness-self-audit)
-is about: a working filter, named filters, and a row that opens.
-
-```tsx
-// {Feature}CollectionPage.tsx — Case A, B, D
-import type { FC } from 'react';
-import {
-  CollectionEmptyState, CollectionErrorState, CollectionNoResultsState, CollectionSearch, CollectionToolbarFilters,
-  MultiSelectCheckboxFilter, Table, stringsArrayFilter,
-  useStaticListFilterCollection, useTableCollection,
-} from '@wix/patterns';
-import { CollectionPage } from '@wix/patterns/page';
-import { usePatternsNavigate } from '@wix/patterns/router';
-import { fetch{Feature}Page, type {Entity}Row } from './{feature}-api';
-
-const STATUS_LABELS: Record<string, string> = { ACTIVE: 'Active', ARCHIVED: 'Archived' };
-// Filter factories are module-level: one instance per page, not per render.
-const statusFilter = stringsArrayFilter<'ACTIVE' | 'ARCHIVED'>({
-  // `name` is NOT the visible title — it feeds a11y legends, BI grouping and dataHooks.
-  // The title comes from the label props in the JSX below; the package's own
-  // `Collection Toolkit.md` guide has the prop model.
-  name: 'Status',
-  itemKey: (item) => item,
-  itemName: (item) => STATUS_LABELS[item] ?? item,
-});
-
-export const {Feature}CollectionPage: FC = () => {
-  const { navigateToEntityPage } = usePatternsNavigate<{Entity}Row>();
-
-  const state = useTableCollection<{Entity}Row, { status: typeof statusFilter }>({
-    queryName: '{feature}',
-    paginationMode: 'cursor', // 'offset' if your API pages by offset
-    itemKey: (item) => item.id,
-    itemName: (item) => item.name,
-    filters: { status: statusFilter },
-    // Every declared filter AND the search box are read here — one that never
-    // reaches the query renders fine and narrows nothing.
-    fetchData: async (query) =>
-      fetch{Feature}Page({
-        limit: query.limit,
-        cursor: query.cursor ?? undefined, // return `cursor: next || undefined` — key always
-        //                                    present, '' walks pages forever
-        search: query.search,
-        filters: { status: query.filters.status },
-      }),
-    // fetchTotal is for a requested aggregate, so it is commented out here. Uncommented, it
-    // must RESOLVE A NUMBER from an endpoint that counts, and it OVERRIDES the fallback to the
-    // loaded-rows count — so a wrong one reports 0 beside a full table while tsc stays green.
-    // Read QUERY_AND_PAGING.md, "What fetchTotal is allowed to call", before uncommenting.
-    // fetchTotal: async (query) => count{Feature}({ search: query.search, filters: query.filters }),
-    fetchErrorMessage: ({ err }) => (err instanceof Error ? err.message : 'Failed to load {feature}'),
-  });
-
-  const statusOptions = useStaticListFilterCollection(statusFilter, ['ACTIVE', 'ARCHIVED']);
-
-  // Nothing here reads `state` directly: the Table observes it internally. The moment you
-  // DO derive a number from it in this component — a header figure, a badge, a requested
-  // SummaryBar — it is MobX, and a plain read is computed once while the collection is still
-  // empty and never recomputed. Wrap it in `useSelector` and select a primitive: TABLE_STATE.md.
-
-  return (
-    <CollectionPage>
-      <CollectionPage.Header title={{ text: '{Page Title}' }} />
-      <CollectionPage.Content>
-        <Table
-          state={state}
-          // `search` defaults to ON, so omitting it ships a box that reaches no
-          // query. Wire it AND read query.search above. If the API has no
-          // free-text filter, resolve the term to one it does support.
-          search={<CollectionSearch placeholder="Search {feature}" />}
-          filters={
-            <CollectionToolbarFilters>
-              {/* BOTH label props, same string, and never accordionItemProps.title.
-                  The resolution model is the package's own `Collection Toolkit.md` guide. */}
-              <MultiSelectCheckboxFilter
-                filter={statusFilter} collection={statusOptions}
-                toolbarItemProps={{ label: 'Status' }}
-                accordionItemProps={{ label: 'Status' }}
-              />
-            </CollectionToolbarFilters>
-          }
-          // Three distinct messages. Without errorState a failed query looks
-          // exactly like a slow one: skeletons, forever.
-          emptyState={<CollectionEmptyState title="No {feature} yet" />}
-          // Name what excluded the rows — a seeded default or a missing scope
-          // looks exactly like "nothing matched", and only one is actionable.
-          noResultsState={<CollectionNoResultsState title="No {feature} match" subtitle="…" />}
-          // errorState is a RENDER FUNCTION: (err, { retry }) => ReactElement.
-          errorState={(err, { retry }) => (
-            <CollectionErrorState
-              title="Couldn't load {feature}"
-              subtitle={String(err)}
-              action={{ text: 'Retry', onClick: retry }}
-            />
-          )}
-          // The drill-in. Editable record → the EntityPage route (`/${item.id}`).
-          // Display-only → the read-only route, DRAFT_TEMPLATE_ROUTER.md §4. Either way a
-          // route, and passing `entity` lets the target title itself before its fetch lands.
-          onRowClick={(item) => navigateToEntityPage({ path: `/${item.id}`, entity: item })}
-          columns={[
-            // One column per field the prompt names; verify each source field —
-            // DATA_SOURCES.md, "A column must show what its header promises."
-            { id: 'name', title: 'Name', render: (item) => item.name },
-          ]}
-        />
-      </CollectionPage.Content>
-    </CollectionPage>
-  );
-};
-```
-
-## Turning `query.search` into a query
-
-`{feature}-api.ts` turns one term into a filter over *several* fields — an OR. **This is where
-search ships broken**: it renders, it reaches the query, and still returns every row, so nothing
-looks wrong until someone counts results.
-
-### A CMS collection — `@wix/data`
-
-`or()` combines two filters; it is **not** a condition. Called on a query or filter holding no
-condition yet it contributes an empty `{}` branch, and `{} OR x` matches the whole collection. Seed
-the filter with the first field, `or()` the rest onto it, then `and()` it onto the query — which is
-also what keeps the facet filters applying to *every* branch:
-
-```ts
-// SHORT_TEXT / LONG_TEXT fields only: `contains` on a number, date or
-// reference field is not a narrower match, it is no match.
-const searchFilter = (term: string, fields: string[]) =>
-  fields.map((f) => items.filter().contains(f, term)).reduce((acc, f) => acc.or(f));
-
-let query = items.query(COLLECTION_ID).eq('status', status).limit(limit);
-const term = search?.trim();
-if (term) query = query.and(searchFilter(term, ['companyName', 'contactEmail']));
-
-// ❌ or() onto a query holding no condition — empty $or branch, every row matches
-items.query(ID).or(items.filter().contains('a', t)).or(items.filter().contains('b', t));
-// ❌ or() onto the query itself — `status` survives only on the first branch
-items.query(ID).eq('status', s).contains('a', t).or(items.filter().contains('b', t));
-```
-
-### A vertical SDK — `@wix/bookings`, `@wix/ecom`, …
-
-No shared free-text operator; the shape differs per endpoint. Read its *Supported Filters* page
-([QUERY_AND_PAGING.md](QUERY_AND_PAGING.md#the-filterable-fields-are-a-closed-list-published-per-endpoint)),
-then `$or` one clause per identity field it lists. Never route the term to a single field by its
-shape — a measured run shipped this, and one branch is always dead:
-
-```ts
-query = term.includes('@')
-  ? query.startsWith('loginEmail', term)
-  : query.startsWith('contact.firstName', term);  // a surname matches nothing, ever
-```
-
-`startsWith` is prefix-only too — "Smith" never finds "John Smith" — so prefer the containment
-operator when the endpoint declares one, and say which you used in `noResultsState`.
-
-**Whatever the shape, prove it narrows.** Run one term you expect to hit a known row and one you
-expect to hit nothing, and check the row count changes for both.

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

@@ -1,204 +0,0 @@
-# Draft Template — Cases A, B and D (router-wired)
-
-**Applies to [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md)'s Cases A, B and D.** All three need `PatternsReactRouter`, because in all three a row opens a page of its own — a panel is not the drill-in ([UX_SUCCESS_MODEL.md](UX_SUCCESS_MODEL.md)). Case A's detail route is read-only (§4); B and D route to a full `EntityPage`. This file covers only what a router adds.
-
-Every snippet below is copied from the installed `dist/docs/*.md` this session read, not from memory.
-
-## 1. Entry — `location` is manual in a Wix CLI app, and only because the router needs it
-
-`PatternsReactRouter` reads the page location through `container.usePageLocation()`, which only `withDashboard`'s `location` prop feeds — nothing supplies it automatically in a Wix CLI app:
-
-```tsx
-// {feature}.tsx — Case A, B or D
-import { useEffect, useState, type FC } from 'react';
-import { dashboard } from '@wix/dashboard';
-import { BusinessManagerTheme } from '../../BusinessManagerTheme';
-import { {Feature}App } from './{Feature}App';
-
-type PageLocation = Parameters<Parameters<typeof dashboard.observeState>[0]>[1]['pageLocation'];
-
-const Page: FC = () => {
-  const [location, setLocation] = useState<PageLocation | undefined>();
-
-  useEffect(() => {
-    const subscription = dashboard.observeState((_pageParams, environment) => {
-      setLocation(environment.pageLocation);
-    });
-    return () => subscription.disconnect();
-  }, []);
-
-  return (
-    <BusinessManagerTheme>
-      {location ? <{Feature}App location={location} /> : null}
-    </BusinessManagerTheme>
-  );
-};
-
-export default Page;
-```
-
-`BusinessManagerTheme` belongs here, not in `{Feature}App.tsx` — its default props must apply above `WixPatternsProvider`. Write it once per app: [BUSINESS_MANAGER_THEME.md](../BUSINESS_MANAGER_THEME.md#2-the-wrapper--write-this-file-once-per-app).
-
-**Skipping either the theme or `location` is a runtime-only failure.** Per `PatternsReactRouter`'s own docs: "Nothing catches this before runtime — type checking and bundling both pass, because neither renders the page." Only a browser catches a missing `location` or an unthemed page, which is why [Step 5's Preview](../../SKILL.md#validation) is not optional.
-
-## 2. App shell — provider, router, routes
-
-```tsx
-// {Feature}App.tsx — Case A, B or D
-import { withDashboard } from '@wix/patterns';
-import { WixPatternsProvider } from '@wix/patterns/provider';
-import { PatternsReactRouter, PatternsReactRoute } from '@wix/patterns/router';
-import { {Feature}CollectionPage } from './{Feature}CollectionPage';
-import { {Feature}EntityPage } from './{Feature}EntityPage';
-// Case D only:
-import { {Feature}SettingsPage } from './{Feature}SettingsPage';
-
-export const {Feature}App = withDashboard(() => (
-  <WixPatternsProvider>
-    <PatternsReactRouter>
-      <PatternsReactRoute type="collection" path="/" element={<{Feature}CollectionPage />} />
-      {/* Case B/D — editable record. Case A registers this ONE route instead, with
-          {Feature}DetailPage as the element and no /new route (§4). Either way the
-          type is `editEntity`: it wires back-navigation to the collection. */}
-      <PatternsReactRoute type="editEntity" path="/:id" element={<{Feature}EntityPage />} />
-      {/* Case B/D only — Case A has nothing to create: */}
-      <PatternsReactRoute type="createEntity" path="/new" element={<{Feature}EntityPage />} />
-      {/* Case D only: */}
-      <PatternsReactRoute type="other" path="/settings" element={<{Feature}SettingsPage />} />
-    </PatternsReactRouter>
-  </WixPatternsProvider>
-));
-```
-
-`PatternsReactRoute`'s `type` is one of exactly `"collection" | "createEntity" | "editEntity" | "other"` — no dedicated settings value, so a settings route is `"other"`. Case B: delete the `/settings` route and the import above it — nothing else changes.
-
-`{Feature}CollectionPage` is [DRAFT_TEMPLATE_COLLECTION.md](DRAFT_TEMPLATE_COLLECTION.md)'s component, unchanged; `{Feature}SettingsPage` (Case D) is [DRAFT_TEMPLATE_SETTINGS.md](DRAFT_TEMPLATE_SETTINGS.md).
-
-## 2b. The collection side of the handoff
-
-The router file above registers `/new`; something has to navigate there. All three of these live on
-the collection page, and `usePatternsNavigate` comes from **`@wix/patterns/router`** — not the root
-export, which is where it is easy to reach for it:
-
-```tsx
-import { PrimaryPageButton } from '@wix/patterns';
-import { usePatternsNavigate } from '@wix/patterns/router';
-
-const { navigateToEntityPage } = usePatternsNavigate<{Entity}>();
-const openNew = () => navigateToEntityPage({ path: '/new' }); // no record yet — omit `entity`
-
-// CollectionPage.Header — primaryAction takes an ELEMENT, not a { text, onClick } config:
-<CollectionPage.Header
-  title={{ text: '{Page Title}' }}
-  primaryAction={<PrimaryPageButton text="Add {entity}" onClick={openNew} />}
-/>
-
-// the empty state should offer the same action, and this one IS a config object:
-<CollectionEmptyState title="No {feature} yet" addNewCta={{ text: 'Add {entity}', onClick: openNew }} />
-
-// and a row opens the edit route:
-onRowClick={(item) => navigateToEntityPage({ path: `/${item.id}`, entity: item })}
-```
-
-The two shapes differ on purpose — `primaryAction` is an element, `addNewCta` is `{ text, onClick }`.
-Guessing either costs a compile round.
-
-## 3. Entity page — one component for both `/new` and `/:id`
-
-Full call details (both generics, what `onSave` receives, the `UseEntityPageParams` pick list) are in `<pkgRoot>/dist/docs/useEntityPage.md` — read it before filling in fields. The part specific to this router-based shape:
-
-```tsx
-// {Feature}EntityPage.tsx — Case B or D (sketch — see dist/docs/useEntityPage.md for the full call)
-import { useParams } from 'react-router-dom'; // NOT @wix/patterns/router — PatternsReactRoute wraps react-router-dom's Route, but only exports PatternsReactRoute/PatternsReactRouter/usePatternsNavigate itself
-import { useEntityPage, EntityPage } from '@wix/patterns';
-import { useForm } from '@wix/patterns/form';
-import { fetch{Entity}, save{Entity}, type {Entity} } from './{feature}-api';
-
-// The form's shape is yours to declare, and need not match the saved entity type.
-type {Entity}FormFields = { name: string };
-
-export const {Feature}EntityPage = () => {
-  const { id } = useParams<{ id?: string }>();
-  const form = useForm<{Entity}FormFields>();
-
-  const state = useEntityPage<{Entity}, {Entity}FormFields>({
-    parentPath: '/', // NOT parentPageId — this shape always uses Patterns Router
-    isNewEntity: () => !id, // a getter: the route can change (/new -> /:id after save) while this stays mounted
-    form,
-    fetch: () => (id ? fetch{Entity}(id).then((entity) => ({ entity })) : Promise.resolve({ entity: undefined })),
-    onSave: ({ widgetsFormData }) =>
-      save{Entity}({ id, ...form.getValues(), ...widgetsFormData }).then((updatedEntity) => ({ updatedEntity })),
-  });
-
-  return (
-    <EntityPage state={state}>
-      <EntityPage.Header title={{ text: id ? 'Edit {Entity}' : 'New {Entity}' }} />
-      <EntityPage.Content>
-        <EntityPage.MainContent>{/* form cards — see dist/docs/EntityPage.md */}</EntityPage.MainContent>
-      </EntityPage.Content>
-    </EntityPage>
-  );
-};
-```
-
-`useEntityPage`'s own docs are explicit about both details above: `parentPath` "Must be passed if using Patterns Router" (`parentPageId` is the non-router alternative — irrelevant here, since Case B/D always uses the router), and `isNewEntity` should be "a getter when the route can change while the page stays mounted" — exactly this component's case, since a successful create typically navigates `/new` → `/:newId`.
-
-**`UseEntityPageParams` is a `Pick<>`, so a param missing from it is a compile error, not an ignored prop.** `isNewEntity` is in that list at 1.470.0 and absent before ~1.46x. If it doesn't compile, read the pick list in your installed `dist/types/hooks/useEntityPage.d.ts` and upgrade — deleting the line makes a create route behave as an edit.
-
-## 4. Read-only detail route — Case A
-
-A display-only collection still routes its rows to a page — but not an `EntityPage`, which has no
-read-only mode and still has none at **1.471.0**: `fetch` and `onSave` are both required, and
-`actionsBarConfig` (`saveCta.text`, `cancelCta`) can retext Save but not remove it. It would ship
-two buttons that either do nothing or save a form nobody was offered.
-
-Use a WDS `Page` — what Cairo does itself: `example-bm`'s `DataExtensionEntityViewPage` and
-auto-patterns' `ViewModeEntityPage` are both plain WDS `Page`s, the latter unexported.
-
-```tsx
-// {Feature}DetailPage.tsx — Case A
-import { useEffect, useState } from 'react';
-import { useParams } from 'react-router-dom';
-import { Card, Loader, Page, Text } from '@wix/design-system';
-import { usePatternsNavigate } from '@wix/patterns/router';
-import { fetch{Entity}, type {Entity} } from './{feature}-api';
-
-export const {Feature}DetailPage = () => {
-  const { id } = useParams<{ id: string }>();
-  const { navigateToCollectionPage } = usePatternsNavigate();
-  const [entity, setEntity] = useState<{Entity} | undefined>();
-
-  useEffect(() => {
-    if (id) {
-      fetch{Entity}(id).then(setEntity);
-    }
-  }, [id]);
-
-  return (
-    <Page>
-      {/* The way back is the header's back button — a read-only page has no Cancel. */}
-      <Page.Header
-        title={entity?.name ?? '{Entity}'}
-        showBackButton
-        onBackClicked={() => navigateToCollectionPage({ path: '/' })}
-      />
-      <Page.Content>
-        {entity ? (
-          <Card>
-            <Card.Header title="Details" />
-            <Card.Divider />
-            <Card.Content>
-              <Text>{entity.name}</Text>
-            </Card.Content>
-          </Card>
-        ) : (
-          <Loader />
-        )}
-      </Page.Content>
-    </Page>
-  );
-};
-```
-
-If the request later grows an edit form this becomes §3's `EntityPage`, route type and `onRowClick`
-unchanged — which is why Case A registers `editEntity`, not `other`.

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

@@ -1,44 +0,0 @@
-# Draft Template — Settings page (Cases C and D)
-
-> Pick your case in [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md) first; this page covers Case C or D.
-
-## The settings page
-
-No dedicated toolkit file exists for this yet (unlike Entity/Collection) — the shape, verified against `useSettingsPage.md`:
-
-```tsx
-// {Feature}SettingsPage.tsx — Case C or D
-import { SettingsPage, useSettingsPage, useSettings } from '@wix/patterns';
-import { useForm } from '@wix/patterns/form';
-import { fetch{Feature}Settings, save{Feature}Settings, type {Feature}Settings } from './{feature}-api';
-
-// The form's shape is yours to declare, and need not match the saved settings type —
-// one field per control on the page.
-type {Feature}SettingsFormFields = { reminderHours: number; notifyStaff: boolean };
-
-export const {Feature}SettingsPage = () => {
-  const form = useForm<{Feature}SettingsFormFields>();
-
-  const state = useSettingsPage<{Feature}Settings, {Feature}SettingsFormFields>({
-    form,
-    fetch: () => fetch{Feature}Settings().then((settings) => ({ settings })),
-    onSave: () => save{Feature}Settings(form.getValues()),
-    onCancel: async () => form.reset(),
-    saveSuccessToast: 'Settings saved',
-    saveErrorToast: (err, { retry }) => ({ message: 'Failed to save settings', action: { text: 'Retry', onClick: retry } }),
-  });
-
-  const settings = useSettings<{Feature}Settings, {Feature}SettingsFormFields>(state);
-
-  return (
-    <SettingsPage state={state}>
-      <SettingsPage.Header title={{ text: '{Settings Page Title}' }} />
-      <SettingsPage.Content>
-        <SettingsPage.MainContent>{/* form cards — same field-controller patterns as EntityPage */}</SettingsPage.MainContent>
-      </SettingsPage.Content>
-    </SettingsPage>
-  );
-};
-```
-
-`useSettingsPage`'s params are all required except `saveSuccessToast`/`saveErrorToast`: `form`, `fetch`, `onSave`, `onCancel`. There is no `parentPath`/`parentPageId` — a settings page isn't reached by drilling into a row, so it carries no back-navigation contract, and Case C needs no router at all to reach it (Section 1's entry renders it directly).