@wix/agent-skills 1.20.1 → 1.22.0

package/package.json

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

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

@@ -51,6 +51,7 @@ export default extensions.appTools({
   tools: [
     {
       methodName: 'get-order-status',
+      displayName: 'Get Order Status',
       description: 'Returns the current fulfillment status, shipping carrier, and tracking number for a customer order. Use this tool when a collaborator or customer asks where their order is, whether it has shipped, when it will arrive, or needs a tracking number. Requires a valid orderId.',
       requestSchema: {
         type: 'object',
@@ -120,7 +121,7 @@ when it will arrive, or needs a tracking number. Requires a valid orderId.'
 ## Checklist
 
 - [ ] Tool declarations filled in the generated `.extension.ts` (replace the stub `myMethod`)
-- [ ] Set `activated: true` on every tool you want the AI assistant to invoke (`activated: false` tools are declared but never called)
+- [ ] Set `activated: true` on every tool you want the AI assistant to invoke (`activated` is optional and **defaults to `false`** if omitted — an omitted or `false` tool is declared but never called, with no build error to warn you)
 - [ ] `runTool` handler covers every `methodName` that has `activated: true`
 - [ ] Inputs validated defensively (schemas are advisory, not enforced by Wix)
 - [ ] Wix API calls wrapped with `auth.elevate` from `@wix/essentials`

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

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