@wix/agent-skills 1.19.0 → 1.19.1

package/skills/wix-manage/references/seo/manage-google-search-console.md

@@ -0,0 +1,272 @@
+---
+name: "Manage Google Search Console for a Wix Site"
+description: "Connect a Wix site to Google Search Console and drive its setup through the public GSC Connection and Site Readiness APIs: check connection and readiness, start the Google authorization, verify ownership, add the property, submit the sitemap, request indexing, read search performance, run URL inspection, recover a stale connection, or disconnect. The site owner authorizes in their own browser via a single-use connect URL."
+---
+
+# Manage Google Search Console for a Wix Site
+
+The **GSC Connection API** links a Google account to the site. The **GSC Site
+Readiness API** acts through that account: verifies ownership, adds the Search
+Console property, submits the sitemap, requests indexing, reads search performance
+and URL inspection. Both select the site from the caller's authorization context
+and take no site ID. Use the site already selected in the environment. If none is
+selected, list the available sites. Select the only site automatically; if several
+are available, ask the user to choose by name before making site-specific calls.
+Never invent a site ID or ask the user to type one.
+
+All endpoints are under `https://www.wixapis.com`: Connection calls under
+`/gsc/connection/v1`, everything else under `/gsc/v1`.
+
+## Start every task with two reads
+
+Both are side-effect free. Do them before describing the site's state.
+
+```
+GET https://www.wixapis.com/gsc/connection/v1/connection
+```
+
+```json
+{ "connection": { "status": "VALID", "connectedEmailMasking": "m*******@gmail.com", "ownedByCaller": true } }
+```
+
+```
+GET https://www.wixapis.com/gsc/v1/site-readiness
+```
+
+```json
+{ "siteReadiness": { "status": "NOT_READY", "blockingReason": "SITE_OWNER_NOT_VERIFIED" } }
+```
+
+Read them together:
+
+| `connection.status` | `siteReadiness` | Meaning | Next |
+|---|---|---|---|
+| `NOT_CONNECTED` | `NOT_READY` / `SITE_OWNER_NOT_VERIFIED` | No Google account linked | Connect (below) |
+| `PENDING` | any | An authorization attempt is open | Ask the user to finish it in their browser, do not start another |
+| `VALID` | `READY` | Connected and verified | Property steps if the user wants them |
+| `VALID` | `NOT_READY` / `SITE_OWNER_NOT_VERIFIED` | Connected, not verified | Verify Site |
+| `INVALID` | `NOT_READY` / `TOKEN_INVALID` | Credentials rejected by Google | Reconnect |
+| `VALID` | `NOT_READY` / `DOMAIN_MISSING` | No connected domain | User connects a domain first |
+
+`blockingReason` is `UNKNOWN_BLOCKING_REASON` when the status is `READY`; not an
+error. Treat an unrecognized reason as "not ready, no known next action".
+
+`READY` covers connection and verification only. Whether the property was added,
+the sitemap submitted, or indexing requested comes from **List Events**.
+
+## `VALID` can be stale, and `MISSING_TOKEN` means reconnect
+
+`INVALID` is only written when a real call to Google is rejected, so a site nobody
+has queried since its credentials broke keeps reporting `VALID`. The tell arrives
+on the first Google-facing call:
+
+```json
+{ "message": "FAILED_PRECONDITION: Missing Token", "details": { "applicationError": { "code": "MISSING_TOKEN" } } }
+```
+
+The reference describes `MISSING_TOKEN` as "no Google account is connected"; it
+also fires when the stored credentials are gone while Get Connection still said
+`VALID`. Either way: the Google account must be reconnected. Do not retry, and do
+not tell the user the site is connected.
+
+## Connect a Google account
+
+Get Connect URL is `GET`, but it **writes**: every call starts a new single-use
+authorization attempt (two-hour expiry) and Get Connection reports `PENDING` while
+it is open. Use Get Connection to check connection status. Call Get Connect URL
+when starting a connection or reconnection attempt; while the user completes that
+attempt, use Get Connection for status checks. Request a new URL when a new attempt
+is needed, such as after expiry. On an already-connected site it is allowed: the
+same Google account refreshes the credentials, a different one replaces the
+connection. Say which before you do it.
+
+1. Read Get Connection. If `VALID`, stop unless the user wants to reconnect.
+2. Call [Get Connect URL](https://dev.wix.com/docs/api-reference/business-management/seo/google-search-console/connection-v1/get-connect-url). The request takes no parameters or body.
+
+   ```
+   GET https://www.wixapis.com/gsc/connection/v1/connect-url
+   ```
+
+   ```json
+   { "connectUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=407408718192.apps.googleusercontent.com&redirect_uri=https%3A%2F%2Fwww.wixapis.com%2Fgsc%2Fconnection%2Fv1%2Fconnect-callback&response_type=code&scope=openid%20email%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fwebmasters&state=EXAMPLE_STATE" }
+   ```
+
+   The response above is illustrative. Wix generates the authorization URL,
+   including its OAuth query parameters. Give the user the exact returned
+   `connectUrl`; do not construct, modify, or reuse the example URL.
+
+3. Give the URL to the user and ask them to tell you when they have finished. Wix
+   completes the exchange server-side; there is no code to send back.
+4. When the user says they are done, read Get Connection once and confirm `VALID`.
+   Do not poll while waiting. If it is still `PENDING`, the user has not finished;
+   if the attempt expired (two hours), request a fresh URL only after they agree.
+
+## Writes need a published, indexable site with a connected domain
+
+Get Connect URL, Verify Site, Add Site, and Submit Sitemap fail with
+`FAILED_PRECONDITION` until the site is published, has a connected (premium)
+domain, and allows indexing. The code names the first failing check:
+
+```json
+{ "message": "FAILED_PRECONDITION: The site has no connected domain. Connect a domain before connecting the site to Google Search Console",
+  "details": { "applicationError": { "code": "DOMAIN_NOT_CONNECTED" } } }
+```
+
+Codes: `SITE_NOT_PUBLISHED`, `DOMAIN_NOT_CONNECTED`, `SITE_NOT_INDEXABLE`. A free
+site on a `wixsite.com` address cannot complete these writes. Report the missing
+prerequisite and stop. When listing sites to find one that qualifies, filter for
+premium sites with a connected domain.
+
+## Set the site up in Search Console
+
+Run the steps the user asked for, in this order, confirming before each write.
+Bodies are empty unless shown.
+
+| Step | Call | Notes |
+|---|---|---|
+| Verify ownership | `POST /gsc/v1/verify-site` with `{ "method": "META" }` | Synchronous against Google, allow up to 60 s. Idempotent. Wix already places the meta tag. |
+| Add the property | `POST /gsc/v1/add-site` | Requires a verified site. |
+| Submit the sitemap | `POST /gsc/v1/submit-sitemap` | Wix hosts and generates the sitemap. Google processes it asynchronously. |
+| Request indexing | `POST /gsc/v1/request-site-indexing` | Success means Google accepted the request, not that the site is indexed. |
+| Request one page | `POST /gsc/v1/request-page-indexing` with `{ "url": "https://www.example.com/about" }` | Full URL of a page on this site. |
+
+All succeed with `{}`. Re-read Get Site Readiness after each step and act on the
+current `blockingReason`. Verify Site on an already-verified site returns `{}` and
+re-stamps the `SITE_VERIFIED` event date: safe, but not a change to report.
+
+Two Google-side failures are retryable. `RESOURCE_EXHAUSTED` (`GOOGLE_QUOTA_EXCEEDED`):
+the quota is daily, tell the user to retry tomorrow. `UNAVAILABLE`
+(`GOOGLE_UNAVAILABLE`): retry once after a few seconds. On any other error your next
+message is the final response: name the step that failed and the error code, and
+make no further Search Console calls.
+
+## Check what was done: List Events and List Sitemaps
+
+```
+GET https://www.wixapis.com/gsc/v1/events
+```
+
+```json
+{ "events": [
+  { "eventType": "ACCOUNT_CONNECTED", "occurredDate": "2025-10-29T11:10:15.869Z" },
+  { "eventType": "SITE_VERIFIED", "occurredDate": "2026-09-07T11:39:31.992Z" },
+  { "eventType": "SITE_ADDED", "occurredDate": "2025-10-29T11:07:39.050Z" } ] }
+```
+
+One entry per event type with the date it **last** occurred, **not sorted by
+date**: never read the last entry as the latest event. Types: `ACCOUNT_CONNECTED`,
+`SITE_VERIFIED`, `SITE_ADDED`, `SITEMAP_SUBMITTED`, `SITE_INDEXING_REQUESTED`,
+`PAGE_INDEXING_REQUESTED`. A missing type means that step never happened.
+
+```
+GET https://www.wixapis.com/gsc/v1/sitemaps
+```
+
+```json
+{ "sitemaps": [ { "url": "https://www.example.com/blog-posts-sitemap.xml", "type": "sitemap", "pending": false,
+  "lastDownloadedDate": "2026-09-05T15:14:47.210Z", "errorCount": "0", "warningCount": "0",
+  "contents": [ { "type": "web", "submittedCount": "1", "indexedCount": "1" } ] } ] }
+```
+
+Wix submits several sitemaps, typically one per content type. `pending: true` with
+an empty `type` means Google has not processed it yet. Counts are strings.
+
+## Read search performance
+
+```
+GET https://www.wixapis.com/gsc/v1/search-analytics?startDate=2026-08-01&endDate=2026-08-31&dimensions=query&rowLimit=5
+```
+
+```json
+{ "results": [ { "keys": ["best of santorini"], "clicks": 0, "impressions": 3, "ctr": 0, "position": 36 } ] }
+```
+
+- `startDate` and `endDate` are required, `YYYY-MM-DD`, end inclusive.
+- `dimensions` repeats: `date`, `query`, `page`, `country`, `device`,
+  `searchAppearance`; omit for one aggregate row. `keys` follow your order.
+- `type`: `web` (default), `image`, `video`, `news`. Page with `rowLimit`/`startRow`.
+- It is Google's own report: the latest days are usually missing, and there is no
+  history from before the property was added. Empty `results` is a real answer.
+
+## Inspect pages
+
+Page IDs are Wix static-page IDs, not URLs. Discover them with
+[List Item SEO Tags](https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/list-item-seo-tags)
+for `STATIC_PAGE`. The request has no body:
+
+```
+GET https://www.wixapis.com/promote/seo/v1/item-seo-tags/STATIC_PAGE
+```
+
+Relevant response fields (unrelated SEO fields omitted; IDs are illustrative):
+
+```json
+{ "itemSeoTags": [ { "id": "STATIC_PAGE:c1dmp", "itemType": "STATIC_PAGE", "itemId": "c1dmp" } ],
+  "pagingMetadata": { "count": 1, "hasNext": false, "cursors": {} } }
+```
+
+If `pagingMetadata.hasNext` is `true`, pass `pagingMetadata.cursors.next` back as
+`paging.cursor` in the next request's query string, URL-encoded. Continue until
+`hasNext` is `false`. The optional `paging.limit` controls the page size; omit the
+cursor on the first request. Treat cursors as opaque.
+
+Use each selected entry's `itemId` as a `pageIds` entry for Inspect URLs. Do not
+use the composite `id` (`STATIC_PAGE:c1dmp`) or a page URL, and never invent an ID.
+The example below assumes discovery returned `c1dmp` for the selected page.
+
+```
+POST https://www.wixapis.com/gsc/v1/inspect-urls
+```
+
+```json
+{ "pageIds": ["c1dmp"], "updateResults": true }
+```
+
+```json
+{ "results": [ { "page": { "pageId": "c1dmp", "name": "Home", "path": "/", "itemType": "STATIC_PAGE" },
+  "status": "OK", "createdDate": "2026-09-07T12:09:55.301Z",
+  "data": { "inspectionResultLink": "https://search.google.com/search-console/inspect?resource_id=https%3A%2F%2Fwww.example.com%2F&id=EXAMPLE_INSPECTION_ID",
+    "indexStatusResult": { "verdict": "PASS", "coverageState": "Submitted and indexed",
+      "indexingState": "INDEXING_ALLOWED", "lastCrawlTime": "2026-08-16T11:39:45Z",
+      "googleCanonical": "https://www.example.com/", "userCanonical": "https://www.example.com/" } } } ],
+  "status": "COMPLETE", "remainingPageCount": 0 }
+```
+
+- `data.inspectionResultLink` is returned by Google. The complete URL above is
+  illustrative; use the actual returned link unchanged, including its query
+  parameters. Do not construct a link from the example values.
+- Each page spends one unit of the account's Google quota (2,000 per property per
+  day): confirm the page list first. Sites over 2,000 pages fail with
+  `SITE_EXCEEDS_INSPECTION_LIMIT`.
+- The site stores **one** inspection; without `updateResults: true` a new call
+  replaces it. Prefer `true` unless the user wants a clean run.
+- `ONGOING`: poll `GET https://www.wixapis.com/gsc/v1/inspection` every few
+  seconds until `COMPLETE` or `ERROR` (same shape plus `updatedDate`).
+- `remainingPageCount > 0` on `COMPLETE` means quota ran out. Name the missing
+  pages; do not call it done.
+- `data` is Google's raw URL Inspection payload: read `indexStatusResult.verdict`
+  (`PASS`, `PARTIAL`, `FAIL`, `NEUTRAL`) and `coverageState`; text is English only.
+  `UNKNOWN_INSPECTION_STATUS` with empty `results` means never inspected.
+
+## Disconnect and clear
+
+Two different removals; confirm which one the user wants.
+
+| Call | Removes | Keeps |
+|---|---|---|
+| `POST /gsc/connection/v1/disconnect` | Stored Google credentials | Verification tag, Search Console property |
+| `POST /gsc/v1/clear-verification` | Verification tag, verification state, **and** credentials | Search Console property |
+
+Neither removes the site from Search Console or revokes Wix's access on Google's
+side. Disconnect with no stored credentials returns `NOT_FOUND`
+(`CONNECTION_NOT_FOUND`).
+
+## When a call fails
+
+- `403` or `PERMISSION_DENIED`: stop after the first and report the missing SEO
+  permission (reads need view access to SEO settings, writes need manage access).
+  Do not try another site, path, or method.
+- `FAILED_PRECONDITION`: act on `details.applicationError.code` as above. Do not
+  retry the same call.
+- Get Connect URL is a recovery step only for `MISSING_TOKEN`, `INVALID`, or
+  `TOKEN_INVALID`, and only after the user agrees to reconnect.

package/skills/wix-manage/references/sites/upload-static-site.md

@@ -0,0 +1,53 @@
+---
+name: "Upload a Website or HTML Files"
+description: Get a user's ready-made website live on Wix when they already have the site files — an index.html, a zip, or a static build exported from an AI builder or any other tool — by sending them to the Wix Headless drop page, where they upload the files and instantly get a live hosted site they can claim into their account. Use whenever the user wants to upload, publish, or host their own HTML/CSS/JS files as a NEW site. Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
+---
+
+# Upload a Website or HTML Files
+
+The user already has a finished website as files — hand-written HTML, a zip
+export, or the output of an AI site builder — and wants it live on Wix as a
+new site. There is no API call to make. Send them to the upload page and
+explain the flow:
+
+```
+https://www.wix.com/headless/drop?utm_campaign=mcp
+```
+
+**Always give the URL exactly as written above, including the
+`utm_campaign=mcp` query parameter.** It attributes the visit to an
+assistant/MCP referral; dropping or rewriting it breaks that attribution.
+
+## What happens on that page
+
+1. The user drags in their files (or a zip) — no login needed.
+2. Wix hosts them immediately on a live URL they can open and share.
+
+## Tell the user before they upload
+
+Share the requirements that match their situation — these are the common
+reasons an upload fails:
+
+- The upload must contain an **HTML file at the top level of the site's
+  files**. It does not need to be named `index.html` — a single HTML file of
+  any name is served as the homepage — and a zip or folder that wraps
+  everything in one top-level folder (e.g. `my-site/index.html`) is unwrapped
+  automatically.
+- Size limits: **3 MB per file, 20 MB total.**
+- **Static files only** — HTML, CSS, JavaScript, and assets. If the user has
+  framework source code that needs a build step (a `package.json`, React/Vue
+  source, etc.), they must run their build first and upload the build output
+  folder's contents, not the source.
+
+## Route the request correctly
+
+| The user has… | Do this |
+|---|---|
+| Site files on their machine (HTML/zip/AI-builder export), wants a new site | This recipe — send them to the drop URL above |
+| A live site or store on another platform (a URL), or CSV/TSV exports, and wants content/products migrated | [Site Import](site-import.md) |
+| An existing Wix site they want to add HTML, an embed, or custom code into | Not this recipe — that's embedding custom code in the site editor |
+| Images, videos, or documents to add to a site | [Upload Media to Wix](../media/upload-media-to-wix.md) — media goes to the site's media files, not a new site |
+
+Do not try to perform the upload for the user through an API, and do not
+create a site for them with other site-creation tools instead — the drop page
+is the flow.

package/skills/wix-manage/references/stores/change-store-currency.md

@@ -5,6 +5,6 @@ description: "Changes the store's payment currency through Site Properties and e
 
 # Change Store Currency
 
-Use the [Site Properties currency recipe](https://dev.wix.com/docs/api-reference/business-management/site-properties/skills/change-payment-currency-site-properties.md) to set the requested payment currency and read it back. Confirm the change with the user before updating it.
+Use the [Change a Site's Regional Properties (Currency, Time Zone, Language) via Site Properties API](../site-properties/change-payment-currency-site-properties.md) recipe to set the requested payment currency and read it back. Confirm the change with the user before updating it.
 
 Catalog product responses may temporarily show the previous currency after carts and checkout use the new one. Allow time for propagation, then recheck.

package/skills/wix-vibe-headless/platforms/base44-ecom-light-seed-with-install.md

@@ -100,7 +100,9 @@ product **without** `imageUrl` and attach it afterwards with `attachProductImage
 
 ## STEP 4 — Wrap up
 
-### Preview
+### Verify
+
+Verify **once, after the seed** — home, shop, and a product page against the populated catalog.
 
 Images that are still generating may show `/__generating__/…` placeholders;
 the platform replaces these automatically at turn end, with a stock fallback if generation

package/skills/wix-vibe-headless/platforms/base44-ecom-light-seed.md

@@ -85,7 +85,9 @@ product **without** `imageUrl` and attach it afterwards with `attachProductImage
 
 ## STEP 3 — Wrap up
 
-### Preview
+### Verify
+
+Verify **once, after the seed** — home, shop, and a product page against the populated catalog.
 
 Images that are still generating may show `/__generating__/…` placeholders;
 the platform replaces these automatically at turn end, with a stock fallback if generation

package/skills/wix-vibe-headless/platforms/base44-ecom-light.md

@@ -62,7 +62,7 @@ need to diagnose and fix it.
 
 **No seeding in this flow** — the client is the only deliverable. Do not seed, populate, or write data to Wix.
 
-### Preview
+### Verify
 
 Images that are still generating may show `/__generating__/…` placeholders;
 the platform replaces these automatically at turn end, with a stock fallback if generation

package/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md

@@ -9,7 +9,7 @@ or configuration changes are needed to build the UI. Never mock products or hand
 `/checkout` URL; the shipped cart uses the eCom redirect session.
 
 ## Prerequisites
-- The site's **Wix Stores** catalog is the read/cart target. It's installed and seeded separately, in parallel with this build — so it may be empty at build time; render the empty state until products land.
+- The site's **Wix Stores** catalog is the read/cart target. It may be empty while the client is being built — render the empty state cleanly. Flows that seed do so after the client is built; verify the storefront once the catalog is populated, not against the empty state.
 
 ## Already installed in `src/`
 Successful deployment verified these files are in place; use this map without needing to read their source (`@/` → `src/`).

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

@@ -1,80 +0,0 @@
-# Collection Toolkit — what to reach for, per user need
-
-[UX_SUCCESS_MODEL.md](UX_SUCCESS_MODEL.md) says what a dashboard must do for the person using it. This file says which component does it, so the stage list resolves to real names instead of a hand-rolled approximation.
-
-Everything below is a real name in the installed `@wix/patterns`. Confirm the props before writing JSX by reading its doc from `dist/docs/index.json` — and if a name is missing from `dist/dts-bundle/index.json`, the installed version is older than this file; work from that inventory, not from memory.
-
-> **The two requirements below are not suggestions.** A page that renders a filtered table and nothing else is the single most common failure of a generated dashboard: it answers "what are all the records" and nothing about how many, which one needs attention, or why something happened. Measured runs produce exactly that page unless the requirement is stated.
->
-> 1. **A dashboard that reports on records shows aggregate numbers**, not only rows.
-> 2. **A dashboard whose rows represent real business records lets the user open one**, unless the prompt is explicitly a report or an export.
-
-## Understand — the aggregate
-
-| Need | Component |
-| --- | --- |
-| Totals, counts, status breakdown above the table | `SummaryBar` |
-| Which subset the numbers describe | wire each metric to the collection's filter state so the count follows the filters |
-
-`SummaryBar` sits inside the page shell, above the collection. Compute the values from the same query the table uses, or a count query alongside it — a metric that disagrees with the visible rows is worse than no metric.
-
-## Focus — narrowing
-
-| Need | Component |
-| --- | --- |
-| Free-text search | `CollectionSearch` |
-| The filter bar itself | `CollectionToolbarFilters` |
-| Pick several values from a known list | `MultiSelectCheckboxFilter`, `MultiInlineCheckboxFilter`, `MultiAutoInlineCheckboxFilter` |
-| Pick one value | `SingleSelectFilter`, `RadioGroupFilter`, `TabsFilter` |
-| Values fetched from an API, not a fixed list | `MultiSelectCollectionFilter` + `useFilterCollection` |
-| Type-ahead over many values | `AutoCompleteFilter` |
-| Date or number ranges | `DateRangeFilter`, `NumberRangeFilter` |
-| Comparison operators (greater than, contains) | `OperatorFilterPicker` + `operatorFilter` |
-| The filter's state object | `idNameArrayFilter`, `stringFilter`, `stringsArrayFilter`, `arrayFilter`, `dateRangeFilter`, `customFilter` |
-| A fixed in-memory option list for a filter | `useStaticListFilterCollection` |
-| Sorting | `Sortable Columns`, `MultiLevelSorting` |
-
-**Read the index once, then go straight to files.** `dist/dts-bundle/index.json` answers every name in this table in a single read — resolve it once per session and keep it, rather than re-reading it per lookup. Each entry names the exact file to open next.
-
-**A factory or hook's doc is often empty where its signature should be** — the props table is generated for components, so `idNameArrayFilter`'s doc shows an `## API` heading with nothing under it. Its bundle has the signature: `<T extends { id: string; name: string }>(params?) => ArrayFilterState<T>`. That holds for every `use…` hook and every `…Filter` factory in the table above, and it is the difference between knowing a name and being able to call it — so for these, read the bundle the index names, not the doc.
-
-**A filter must narrow the result.** Declare it in the collection hook's `filters` map and read it inside `fetchData`, so the value reaches the query. Filter UI that renders but never changes the rows is a defect that looks like a feature — and it is the failure mode these components exist to prevent.
-
-## Investigate — opening one record
-
-| Surface | Use when | Built from |
-| --- | --- | --- |
-| **Side panel** | Inspect or lightly edit one record while keeping the filtered list on screen. The V1 default for review dashboards. | WDS `SidePanel` — patterns has no side panel |
-| **Entity page** | Multi-section detail, editing, history, or a link someone can share. | `EntityPage` + `useEntityPage`, reached with `usePatternsNavigate().navigateToEntityPage`, form state from `@wix/patterns/form`. The call itself: [ENTITY_PAGE_TOOLKIT.md](ENTITY_PAGE_TOOLKIT.md) |
-| **Expanded row** | A couple of extra fields, no separate workspace needed. | The collection's own row expansion |
-| **Picker / bulk confirm** | Choosing records, or confirming an action on many. | `PickerModal` + `usePickerModal`, `bulkActionModal` |
-
-A dialog that creates, updates or displays one listed record is **not** a dashboard modal — a create / "add new" form included, since it writes the record. See [DASHBOARD_MODAL.md](../DASHBOARD_MODAL.md); for the create route itself — registering it, and the four params that differ from the edit call — [ENTITY_PAGE_TOOLKIT.md § Create route](ENTITY_PAGE_TOOLKIT.md#create-route). A row the user cannot open is the second most common failure after the missing aggregate.
-
-**Form state on an entity page** comes from `@wix/patterns/form` — `useForm` for the form, `useController` for a single field. That subpath re-exports `@wix/bex-core/form`, which wraps `react-hook-form`, so its API is react-hook-form's and only a handful of its names appear in the patterns docs: `FieldValues`, `ControllerProps` and most of the rest are documented by react-hook-form, not here. `Read <pkgRoot>/dist/dts-bundle/exports/form.d.ts` to see what the subpath actually gives you.
-
-## Act and confirm
-
-| Need | Component |
-| --- | --- |
-| Page header actions | `PrimaryActions`, `SecondaryActions`, `More Actions` — passed to the page header's `primaryAction`, `secondaryActions` and `moreActions` slots |
-| Table toolbar button | `PrimaryActionButton` — the table's own `primaryActionButton` prop |
-| Row actions | `deleteSecondaryAction`, in the row's `actionCell` |
-| Acting on a multi-row selection | `MultiBulkActionToolbar`, `bulkActionModal` |
-| Immediate feedback, then reconcile | `useOptimisticActions(state.collection)` ✅ — not `useOptimisticActions(state)` ❌: `useTableCollection()` returns `TableState<T, F>`, and the hook takes the `CollectionState<T, F>` that state exposes as `state.collection`. Returns `CollectionOptimisticActions` |
-| A banner above the table | `TableTopNotification` |
-
-## The states that are not the happy path
-
-| State | Component |
-| --- | --- |
-| Collection is genuinely empty | `CollectionEmptyState` |
-| Filters or search matched nothing | `CollectionNoResultsState` |
-| Feature needs a paid plan | `CollectionPremiumEmptyState` |
-| Load failed | the collection state's error handling — give the user a way to retry |
-
-Empty and no-results are different messages: one means "add your first record", the other means "loosen the filters". Shipping only the first makes a working filter look broken.
-
-## Export
-
-`ExportButton` (its doc is `ExportTo`) for CSV and similar. Reach for it when the prompt mentions exporting, downloading, or sending records elsewhere.

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

@@ -1,140 +0,0 @@
-# Entity Page Toolkit — calling `useEntityPage`
-
-[COLLECTION_TOOLKIT.md](COLLECTION_TOOLKIT.md) says a row the user cannot open is a defect, and sends you to `EntityPage` + `useEntityPage` to fix it. This file is the call itself.
-
-## The call
-
-```tsx
-import { useEntityPage, EntityPage } from '@wix/patterns';
-import { useForm } from '@wix/patterns/form';
-
-interface Shift {
-  id?: string;
-  name?: string;
-}
-
-interface ShiftFormFields {
-  name?: string;
-}
-
-const form = useForm<ShiftFormFields>({ defaultValues: { name: '' } });
-
-const state = useEntityPage<Shift, ShiftFormFields>({
-  fetch: () => api.getShift(shiftId).then((entity) => ({ entity })),
-  onSave: ({ widgetsFormData }) =>
-    api
-      .updateShift(shiftId, { ...form.getValues(), ...widgetsFormData })
-      .then((updatedEntity) => ({ updatedEntity })),
-  form,
-  parentPath: '/',
-});
-```
-
-**`parentPath` is relative to the router's own mount point — the dashboard page's
-own root, not the page's `route` value.** A dashboard page scaffolded with
-`{"route": "shifts"}` is served at `/dashboard/shifts`, but `PatternsReactRouter`
-still sees its own location start fresh at `/` inside that page — so `parentPath`,
-every `PatternsReactRoute`'s `path`, and the `path` passed to
-`navigateToEntityPage()` / `navigateToCollectionPage()` must never repeat the
-page's own `route`/name. `parentPath: '/shifts'` on a page whose `route` is
-`"shifts"` is the single most common way this gets copied wrong — it looks like a
-reasonable guess (name the parent after the page) and compiles, but the
-collection route it points back to is registered at `path="/"`, not
-`path="/shifts"`, so `parentPath` must match that: `'/'`. See [Create
-route](#create-route) below for the full route registration.
-
-From **1.465.0** the library's own docs state this rule — `PatternsReactRouter.md`,
-`usePatternsNavigate.md` and `useEntityPage.md`'s **Create route**. On an older
-install they don't, and their examples *demonstrate* the mistake
-(`navigateToEntityPage({ path: '/shifts/new' })`, `navigateToCollectionPage({ path:
-'/entities' })`); prefer this rule over what those examples show.
-
-`EntityPage` and `useEntityPage` are **root** exports. `@wix/patterns/page` holds `CollectionPage` and `WidgetsFormProvider` only, so importing the entity page from there is `TS2305: has no exported member` — the collection page and the entity page do not live in the same place. `Read <pkgRoot>/dist/dts-bundle/exports/page.d.ts` to see what that subpath actually gives you.
-
-## Name both generics
-
-`useEntityPage<T, V extends FieldValues = FieldValues>` takes the entity type **and** the form-values type. `V` does not infer from the `form` argument — it falls back to `FieldValues`, and a `useForm<ShiftFormFields>()` then fails to assign with `Type 'UseFormReturn<ShiftFormFields, …>' is not assignable to type 'UseFormReturn<FieldValues>'`. Naming a single generic only works when the form is untyped.
-
-`useEntityPage<any, ShiftFormFields>` makes that error go away and takes the entity type with it — `state.entity` becomes `any`, and every field access below it stops being checked. Name the entity type.
-
-## `onSave` does not hand you the form values
-
-`OnSaveParams` has exactly one key. `widgetsFormData` carries what the **widget** fields contributed — extended fields, tags — not what the user typed into your own fields. Those come from the form you already own:
-
-```tsx
-onSave: ({ widgetsFormData }) => {
-  const values = form.getValues();                  // your fields
-  const { extendedFields, tags } = widgetsFormData; // widget fields
-  …
-};
-```
-
-Reaching for a `values`-shaped key on the `onSave` argument is the usual first guess, and there isn't one.
-
-## The params are a `Pick`
-
-`UseEntityPageParams` picks a fixed set off `EntityPageStateParams` — `fetch`, `onSave`, `saveSuccessToast`, `saveErrorToast`, `deleteAction`, `transformEntityToCollectionItem`, `isNewEntity` (create vs edit — [Create route](#create-route)), `form`, `parentPageId`, `parentPath`, `parentReferrer`, `schemaSource`. Anything outside that list is an excess-property error on the object literal. `container` is the common guess and is not one of them: the hook calls `useWixPatternsContainer()` itself.
-
-Confirm the shape rather than guessing — the hook's doc ends by pointing at the bundle rather than tabulating props, because props tables only exist for components. `Read <pkgRoot>/dist/dts-bundle/index.json`, then `Read` the bundled `.d.ts` for each of `useEntityPage`, `UseEntityPageParams`, and `OnSaveParams` at exactly the `file` path the index gives.
-
-## Create route
-
-The example above is edit-only. "Add new" is an `EntityPage` too, and it is not the same call with the id left out. Four things differ, and three of them fail silently if you guess:
-
-- The route is its own `PatternsReactRoute type="createEntity"`. One component can serve both entity routes; the route is what tells them apart.
-- `navigateToEntityPage({ path })` — omit `entity`. It exists so the header can render a title before the fetch resolves, and a create route has no record to give it. A placeholder is worse than nothing: until `fetch` resolves it *is* `state.entity`.
-- `fetch` is required on the create route too, and `{ entity: undefined }` is the create case built into its return type — not a loading state, and there is no `fetch`-less variant.
-- `isNewEntity` is the only param that tells the page which route it is on. Omitted, a create page that seeds defaults through `fetch` is announced to the collection as an *update*: the collection changes a row it does not have, the new record never appears in the list, and the only trace is a `Fetched page info for updated entity not found` console error.
-
-`Read <pkgRoot>/dist/docs/useEntityPage.md` before writing one — its **Create route** section carries the worked component that serves both routes off one `useParams` answer, and the `boolean | (() => boolean)` getter form for `isNewEntity`.
-
-**If that file has no `Create route` heading, the installed `@wix/patterns` predates 1.464.0.** Upgrade and re-read rather than working around it: on those versions `navigateToEntityPage` types `entity` as required, so omitting it does not compile, and passing the placeholder that satisfies it is the failure the bullet above describes.
-
-## Around the call
-
-| Step | What owns it |
-| --- | --- |
-| Getting here from the collection page | `usePatternsNavigate()` → `navigateToEntityPage({ path, entity })` |
-| Registering the route | `PatternsReactRoute` inside `PatternsReactRouter` |
-| Form state and field binding | `useForm` / `useController` from `@wix/patterns/form` — `useController`, never `register` |
-| Body layout | `EntityPage.Header`, `.MainContent`, `.AdditionalContent`, `.Card` |
-| The fields inside those cards | `@wix/design-system` (`FormField`, `Input`, `Text`) |
-
-Every `path` in that first row — the route's own `path`, `parentPath`, and the `path` argument to `navigateToEntityPage`/`navigateToCollectionPage` — is relative to the page's own root, never to its `route`/name. See the `parentPath` note under [The call](#the-call) above; it is the same rule everywhere a path appears in this table.
-
-`@wix/patterns/form` re-exports `@wix/bex-core/form`, which wraps `react-hook-form` — so `form.getValues()`, `form.reset()` and the rest are react-hook-form's API, documented there rather than in the patterns docs.
-
-## Binding a field: `useController`, never `register`
-
-`register` returns props for a plain `<input>`, and WDS components are not one. Two ways it fails:
-
-`<Input {...register('qty')} />` does not compile — `register` always returns `min`/`max` as `string | number`, whatever options you passed, and WDS types them `number | undefined`. The error names `InputProps`, which reads like a WDS bug and isn't.
-
-`<Input ref={register('qty').ref} />` **does** compile and is wrong. `Input`'s `ref` is its imperative handle (`Ref<InputImperativeActions>`); `register`'s ref is `(instance: any) => void`, so it accepts that and binds the handle rather than the `<input>`. The field never registers, validation never sees it, and nothing reports it.
-
-Bind through value/onChange instead:
-
-```tsx
-import { useController, useForm } from '@wix/patterns/form';
-import { FormField, Input } from '@wix/design-system';
-
-type ProductForm = { name: string; qty: number };
-
-function NameField({ form }: { form: ReturnType<typeof useForm<ProductForm>> }) {
-  const { field, fieldState } = useController({
-    name: 'name',
-    control: form.control,
-    rules: { required: 'Name is required' },
-  });
-
-  return (
-    <FormField label="Name" required status={fieldState.error ? 'error' : undefined} statusMessage={fieldState.error?.message}>
-      <Input value={field.value} onChange={field.onChange} onBlur={field.onBlur} />
-    </FormField>
-  );
-}
-```
-
-Rules live in `rules`, not on the WDS component. If you need `register` for a DOM concern such as input masking, `Input` takes `inputRef?: React.Ref<HTMLInputElement>` — pass the ref there, never to `ref`.
-
-A dialog that creates, updates or displays one listed record is **not** a dashboard modal — a create / "add new" form included, since it writes the record. See [DASHBOARD_MODAL.md](../DASHBOARD_MODAL.md).