@wix/agent-skills 1.18.2 → 1.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.18.2",
+  "version": "1.19.1",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-app/SKILL.md

@@ -8,7 +8,7 @@ compatibility: requires `@wix/cli` >= 1.1.192.
 
 Helps build extensions for Wix CLI applications. Covers all extension types: dashboard pages, modals, plugins, menu plugins, custom element widgets, Editor React components, site plugins, embedded scripts, backend APIs, events, service plugins, and data collections.
 
-**Scaffolding is owned by the Wix CLI.** For every extension type except Backend API, files, folders, builder boilerplate, UUIDs, and `src/extensions.ts` registration are generated by `wix generate --params`. This skill provides the decision logic, API guidance, configuration semantics, and business-logic patterns that fill in the generated stubs.
+**Scaffolding is owned by the Wix CLI.** Use `wix generate --params` for every supported type. It generates files and, where applicable, builder boilerplate, UUIDs, and `src/extensions.ts` registration. HTTP endpoints are discovered from files and need no registration. This skill provides the decision logic, API guidance, configuration semantics, and business-logic patterns that fill in the generated stubs.
 
 ## ⚠️ MANDATORY WORKFLOW CHECKLIST ⚠️
 
@@ -22,14 +22,19 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
   - [ ] Determined full scoped collection IDs if Data Collection extension is being created (see [Collection ID Coordination](#collection-id-coordination))
   - [ ] 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 [Collection Toolkit](references/dashboard-page/COLLECTION_TOOLKIT.md) for which component serves each need.
-    - [ ] **The page shows aggregate numbers, not only rows** (`SummaryBar`) — unless the prompt asks for a single record. "How many, and which ones need me" is why someone opens a dashboard.
+  - [ ] **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.
     - [ ] **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 none of the three is what gets built when nobody states the requirement — it is the most common way a generated dashboard disappoints.
-  - [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md), then `Read` `dist/dts-bundle/index.json` for the component inventory, upgrading `@wix/patterns` if that file is missing. The patterns docs are only ever read directly from those two published files — never by hand from anywhere else in `node_modules`.
-  - [ ] **🛑 Component Docs Gate (MANDATORY, dashboard UI only):** Printed the doc for every patterns component, hook, and state type you are about to write — `Read` its file from `dist/docs/index.json`, and `Read` its bundled `.d.ts` from `dist/dts-bundle/index.json` for any patterns type you name in your own code. The inventory gives the name; the doc gives the props and the import path. Name what you read before the first line of JSX.
+    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.
+  - [ ] **🛑 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).
+
+    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.
 - [ ] **Step 3:** Checked API references; used MCP discovery only for gaps
   - [ ] 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`
@@ -107,32 +112,31 @@ Dashboard pages at Wix are built from two libraries. For **every** UI element, r
 
 ### 1. `@wix/patterns` — page structure and data collections
 
-Patterns owns the page shell and everything collection-shaped. These concepts are patterns' territory — if you need one, look it up there first rather than assembling it from WDS parts:
-
-| Need | Look for |
-| --- | --- |
-| Page shell, header, content area, sticky footer | `CollectionPage`, `EntityPage`, `SettingsPage` (+ their `.Header` / `.Content` sub-parts) |
-| Table, grid, table↔grid switch, folder views | `Table`, `Grid`, `TableGridSwitch`, `TableFolders`, `GridFolders` |
-| Collection state — paging, sorting, selection, loading | `useTableCollection()` and its sibling hooks (one per collection type) |
-| Filters, search, sorting, view presets/tabs | the collection's filter and view APIs |
-| Row actions, bulk actions, drag-and-drop | the collection's feature APIs |
-| Multiple pages inside one extension | `PatternsReactRouter`, `PatternsReactRoute`, `usePatternsNavigate` |
-| **Add / edit / view one item from a collection** | `EntityPage` + `useEntityPage` (fetch + save + validation), reached with `usePatternsNavigate().navigateToEntityPage`. Form state via `useForm` / `useController` from `@wix/patterns/form` (`useController`, never `register`). **Not** a dashboard modal — see [Entity create and edit](#entity-create-and-edit) |
-| Overlays tied to a collection (item picker, bulk-action confirm) | `PickerModal` / `usePickerModal`, `bulkActionModal` |
-
-**Looking a component up is two direct file reads** — no script, never `node_modules` browsed by hand. Resolve the installed package root once per session ([Prerequisites](references/WIX_PATTERNS_DOCS.md#prerequisites)), then reuse it. Start with what exists:
-
-```bash
-cat <pkgRoot>/dist/dts-bundle/index.json
-```
+Patterns owns the page shell and everything collection-shaped: page shells and their header /
+content / footer sub-parts, tables and grids and the switch between them, folder views,
+collection state (paging, sorting, selection, loading), filters, search, view presets, row and
+bulk actions, drag-and-drop, in-extension routing, the overlays tied to a collection, and the
+add / edit / view page for one listed item. If you need one of those, it is patterns' — look it
+up rather than assembling it from WDS parts.
 
-Then read the doc for each name you plan to use, including the state types they cross-reference — `Read <pkgRoot>/dist/docs/index.json` to find the file, then `Read` it directly. Props and import paths exist only there, and patterns is not a flat namespace — `@wix/patterns/page`, `/provider`, `/form` — so an import from memory is a guess.
+**Which component serves a given need is the library's own answer, not this skill's.** It ships
+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).
 
-Each doc gives its import line, props table, and an example. For a TypeScript type rather than a component — `Filter<T>`, `RangeItem<T>`, `CursorQuery`, a `...Props` interface — look it up the same way in `dist/dts-bundle/index.json` instead and `Read` the `.d.ts` at exactly the `file` path it gives; it's already fully resolved, which is what keeps a deep `@wix/bex-core/dist/types/...` path out of the tree.
+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`
+names the worked call, and `bundle` says whether props live in a `.d.ts` or in the doc's own
+table. Read the one artifact your open question needs. Resolve `<pkgRoot>` once per session
+([Prerequisites](references/WIX_PATTERNS_DOCS.md#prerequisites)) and reuse it.
 
-If `dist/dts-bundle/index.json` doesn't exist, the installed `@wix/patterns` predates this feature — upgrade it, then re-check. See [Prerequisites](references/WIX_PATTERNS_DOCS.md#prerequisites). **A missing index is not a reason to fall through to step 2**; it means the lookup has not happened yet. Falling through here is the single most common way a dashboard page ends up built entirely from WDS.
+**Add / edit / view one item from a collection is an `EntityPage`, not a dashboard modal** — see
+[Entity create and edit](#entity-create-and-edit), and `Collection to Entity Flow.md` in the
+package for the flow itself.
 
-Full lookup workflow, provider selection, and the provider/page separation rule: [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md).
+**Falling through to step 2 because a lookup was inconvenient is the single most common way a
+dashboard page ends up built entirely from WDS.** A missing index means the lookup has not
+happened yet, not that patterns lacks the component.
 
 ### 2. `@wix/design-system` — everything inside the shell
 
@@ -163,9 +167,9 @@ This is the most common place the selection order gets dropped: the collection g
 
 The documented flow:
 
-1. From the collection page's action cell or primary action, call `navigateToEntityPage({ path, entity })` from `usePatternsNavigate()`. (The patterns docs give this exact use case — "navigate to an entity page on an action cell click on a collection page" — and it renders the entity header immediately, before the fetch resolves.) On the **create** route there is no record to pass: omit `entity` and see [ENTITY_PAGE_TOOLKIT.md § Create route](references/dashboard-page/ENTITY_PAGE_TOOLKIT.md#create-route), which is what the whole "add new" flow turns on.
+1. From the collection page's action cell or primary action, call `navigateToEntityPage({ path, entity })` from `usePatternsNavigate()`. (The patterns docs give this exact use case — "navigate to an entity page on an action cell click on a collection page" — and it renders the entity header immediately, before the fetch resolves.) On the **create** route there is no record to pass: omit `entity` and read the **Create route** section of `<pkgRoot>/dist/docs/useEntityPage.md`, which is what the whole "add new" flow turns on.
 2. Register the route with `PatternsReactRoute` inside `PatternsReactRouter`.
-3. In the entity page, `useEntityPage({ fetch, onSave })` owns fetching, saving, validation, dirty state, loading skeletons, and error states. Form state comes from `useForm` / `useController` in `@wix/patterns/form`. The call itself — both generics, what `onSave` receives, which params exist — is in [ENTITY_PAGE_TOOLKIT.md](references/dashboard-page/ENTITY_PAGE_TOOLKIT.md).
+3. In the entity page, `useEntityPage({ fetch, onSave })` owns fetching, saving, validation, dirty state, loading skeletons, and error states. Form state comes from `useForm` / `useController` in `@wix/patterns/form`. The call itself — both generics, what `onSave` receives, which params exist — is in `<pkgRoot>/dist/docs/useEntityPage.md`.
 4. Compose the body from `EntityPage.Header`, `EntityPage.MainContent`, `EntityPage.AdditionalContent`, and `EntityPage.Card`. **WDS goes inside those cards** — `FormField`, `Input`, `Text` for the individual fields.
 
 Use a Dashboard Modal for dialogs that neither write nor display a listed record: a delete or discard confirmation, an unsaved-changes prompt, an informational notice, or any dialog on a page that lists nothing. Dialog size and field count are not exceptions — a one-field create form over a listed record is still an `EntityPage`. Reach for a modal because the interaction persists nothing, never because "the form should open in a modal."
@@ -183,7 +187,7 @@ Use a Dashboard Modal for dialogs that neither write nor display a listed record
 | Service Plugin | Backend | `SERVICE_PLUGIN` | [SERVICE_PLUGIN.md](references/SERVICE_PLUGIN.md) |
 | App Tools (AI assistant tools) | Backend | `APP_TOOLS`, then `SERVICE_PLUGIN` with `pluginType: TOOLS_PROVIDER_CONFIG` | [APP_TOOLS.md](references/APP_TOOLS.md) |
 | Backend Event Extension | Backend | `EVENT` | [BACKEND_EVENT.md](references/BACKEND_EVENT.md) |
-| Backend API | Backend | — (manual, see banner below) | [BACKEND_API.md](references/BACKEND_API.md) |
+| Backend API (HTTP endpoint) | Backend | `HTTP_ENDPOINT` | [BACKEND_API.md](references/BACKEND_API.md) |
 | Data Collection | Backend | `DATA_COLLECTION` | [DATA_COLLECTION.md](references/DATA_COLLECTION.md) |
 | Editor React component | Site | `EDITOR_REACT_COMPONENT` | [EDITOR_REACT_COMPONENT.md](references/EDITOR_REACT_COMPONENT.md) |
 | Custom element widget | Site | `CUSTOM_ELEMENT` | [CUSTOM_ELEMENT_WIDGET.md](references/CUSTOM_ELEMENT_WIDGET.md) |
@@ -193,7 +197,7 @@ Use a Dashboard Modal for dialogs that neither write nor display a listed record
 **Key constraints:**
 - Dashboard Page cannot use `<Modal />`; use a separate Dashboard Modal and `dashboard.openModal()`.
 
-> **⚠️ Backend API is the only extension type the CLI does NOT scaffold.** `wix generate` has no `BACKEND_API` handler. Create files directly per [BACKEND_API.md](references/BACKEND_API.md).
+> **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
 
@@ -216,8 +220,6 @@ 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) |
-| Dashboard Collection Toolkit (which component per user need) | [COLLECTION_TOOLKIT.md](references/dashboard-page/COLLECTION_TOOLKIT.md) |
-| Reading a patterns bundle or doc file the index names | [PATTERNS_BUNDLE_READING.md](references/dashboard-page/PATTERNS_BUNDLE_READING.md) |
 
 ---
 
@@ -418,17 +420,17 @@ Use the Extension Types Reference Table and decision content above. State extens
 
 ### Step 4a: Scaffold via the CLI
 
-For each extension **except Backend API**, run `npx wix generate --params '<json>'`. The command returns `{"success":true,"extensionType":"...","newFiles":[...]}` on success.
+For each supported type, including HTTP endpoints, run `npx wix generate --params '<json>'`. The command returns `{"success":true,"extensionType":"...","newFiles":[...]}` on success.
 
-If the command fails because of unknown or invalid params, run `npx wix schema generate --type <extensionType>` to print the JSON Schema for that extension type, fix the `--params` payload, and retry. Do not fall back to manual scaffolding.
+If the command fails because of unknown or invalid params, run `npx wix schema generate --type <extensionType>` to print the JSON Schema for that extension type, fix the `--params` payload, and retry. Do not fall back to manual scaffolding. The one exception is `HTTP_ENDPOINT` on a CLI older than 1.1.243, which predates the generator but still supports the extension: create the endpoint file by hand as described in [BACKEND_API.md](references/BACKEND_API.md#generate-for-the-project-type).
 
 **What the CLI does automatically:**
 - Creates folders and stub files
-- Generates a fresh UUID for the extension `id`
-- Updates `src/extensions.ts` with the import and `.use()` call
+- For registered extensions, generates a fresh UUID and updates `src/extensions.ts` with the import and `.use()` call
+- For HTTP endpoints, creates the route file without changing `src/extensions.ts`
 - Enforces naming rules (kebab-case, hyphen-required custom elements, etc.)
 
-**Backend API exception:** Create `src/pages/api/*.ts` files manually per [BACKEND_API.md](references/BACKEND_API.md).
+**HTTP endpoints:** Run `npx wix generate --params '{"extensionType":"HTTP_ENDPOINT","name":"hello"}'`, then implement the handler in the returned file. Follow [BACKEND_API.md](references/BACKEND_API.md); if the route does not respond, its troubleshooting hint shows how to confirm discovery from the build output.
 
 ### Step 4b: Fill in business logic
 
@@ -497,7 +499,7 @@ The following actions need to be done manually by you:
 
 ## Extension Registration
 
-`wix generate --params` updates `src/extensions.ts` automatically for every CLI-supported extension type. The only case that still requires manual editing is Backend API. For background, troubleshooting, and the manual recovery pattern when `src/extensions.ts` drifts, see [EXTENSION_REGISTRATION.md](references/EXTENSION_REGISTRATION.md).
+`wix generate --params` updates `src/extensions.ts` automatically for registered extensions. HTTP endpoints require no import or `.use()` call; the runtime discovers their files. For background, troubleshooting, and the manual recovery pattern when `src/extensions.ts` drifts, see [EXTENSION_REGISTRATION.md](references/EXTENSION_REGISTRATION.md).
 
 ---
 

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

@@ -1,82 +1,95 @@
 
 # Wix Backend API Builder
 
-Creates HTTP endpoints for Wix CLI applications — server-side routes that handle HTTP requests, process data, and return responses. HTTP endpoints are powered by Astro endpoints and are automatically discovered from the file system.
+Creates HTTP endpoints for Wix app projects. Determine the existing runtime
+before choosing the directory, handler type, or frontend URL.
 
-**Key facts:**
+## Scope and Runtime Detection
 
-- Files live in `src/pages/api/` with `.ts` extension
-- Cannot be added via `npm run generate` — create files directly
-- Don't appear on the Extensions page in the app dashboard
-- No extension registration needed (auto-discovered)
-- Replace the legacy "HTTP functions" from the previous Wix CLI for Apps
+- The CLI uses the `@wix/custom-extensions` runtime when the project's own
+  `package.json` declares that package in `dependencies` or `devDependencies`. A
+  transitive installation under `node_modules` is not enough. Do not infer the
+  runtime from using `wix dev`, `wix build`, or the Wix CLI alone.
+- Existing `@wix/astro` apps retain Astro routing. Do not add
+  `@wix/custom-extensions`, move routes into `src/endpoints`, change their handler
+  imports, or introduce `WIX_SERVER_BASE_PATH` to apply the other runtime's recipe.
 
-## Use Cases
+## Generate for the Project Type
 
-Use HTTP endpoints when you need to:
+```bash
+npx wix generate --params '{"extensionType":"HTTP_ENDPOINT","name":"hello"}'
+```
 
-- Build REST APIs with multiple HTTP methods
-- Integrate with external APIs or services
-- Handle complex form submissions or file uploads
-- Serve dynamic content (images, RSS feeds, personalized data)
-- Access runtime data or server-side databases
+Names use lowercase letters, digits, and hyphens; slash-separated names such as
+`payments/checkout` create nested routes. Do not include a leading slash or `.ts`.
+The generator creates GET/POST stubs; keep only the methods the task needs.
+
+For Wix app projects, the generator preserves the selected runtime:
+
+| Project | Generated file | Route before any server base path | `APIRoute` import |
+| --- | --- | --- | --- |
+| `@wix/custom-extensions` | `src/endpoints/hello.ts` | `/hello` | `@wix/custom-extensions/types` |
+| `@wix/astro` | `src/pages/api/hello.ts` | `/api/hello` | `astro` |
+
+In `@wix/custom-extensions` projects, endpoints live in `src/endpoints` by default and require
+`@wix/custom-extensions@^0.2.14`; older releases neither scan that directory by
+default nor export `./types`, and the build passes without serving anything. The
+generator upgrades the package; when creating the file by hand, upgrade it
+yourself. Install changed dependencies before validating. If `app()` in
+`src/extensions.ts` passes `apiDir`, that directory (under `src/`) is the one the
+runtime scans instead, and the generator does not read it: either remove `apiDir`
+to use the default, or move the generated file into `src/<apiDir>`. The route is
+`/<name>` either way.
+
+If `wix generate` does not recognize `HTTP_ENDPOINT`, the CLI predates the
+generator (added in `@wix/cli` 1.1.243). Update the CLI, or create the file by hand:
+put it in the directory from the table above, export the handlers shown in
+[HTTP Methods](#http-methods), and import `APIRoute` from
+`@wix/custom-extensions/types` or from `astro`, matching the project's runtime. Do
+not add `astro` to a `@wix/custom-extensions` project to make an Astro-style import
+resolve. No registration step is needed.
 
 ## File Structure and Naming
 
-### Basic Endpoint
-
-File path determines the endpoint URL:
-
-```
-src/pages/api/<your-endpoint-name>.ts
-```
-
-### Dynamic Routes
+Nested paths are relative to the runtime's endpoint directory:
 
-Use square brackets for dynamic parameters:
-
-```
-src/pages/api/users/[id].ts → /api/users/:id
-src/pages/api/posts/[slug].ts → /api/posts/:slug
-src/pages/api/users/[userId]/posts/[postId].ts → /api/users/:userId/posts/:postId
-```
+| `@wix/custom-extensions` file | Route | Astro equivalent |
+| --- | --- | --- |
+| `src/endpoints/payments/checkout.ts` | `/payments/checkout` | `src/pages/api/payments/checkout.ts` → `/api/payments/checkout` |
+| `src/endpoints/users/[id].ts` | `/users/:id` | `src/pages/api/users/[id].ts` → `/api/users/:id` |
 
 ## HTTP Methods
 
-Export named functions for each HTTP method. Type with `APIRoute` from `astro`. Each handler receives a `request` object and returns a `Response`:
+Export a named handler for each requested HTTP method. Preserve the generated
+`APIRoute` import for the project's runtime. For `@wix/custom-extensions` projects:
 
 ```typescript
-import type { APIRoute } from "astro";
-
-export const GET: APIRoute = async ({ request }) => {
-  console.log("Log from GET."); // This message logs to your CLI.
-  return new Response("Response from GET."); // This response is visible in the browser console
-};
+import type { APIRoute } from "@wix/custom-extensions/types";
 
-export const POST: APIRoute = async ({ request }) => {
-  const data = await request.json();
-  console.log("Log POST with body: ", data); // This message logs to your CLI.
-  return new Response(JSON.stringify(data)); // This response is visible in the browser console.
+export const GET: APIRoute = async () => {
+  return Response.json({
+    message: "Hello from the backend!",
+    timestamp: new Date().toISOString(),
+  });
 };
 ```
 
+In an Astro project, use `import type { APIRoute } from "astro"` instead.
+The request/response examples below apply to both runtimes.
+
 ## Request Handling
 
 ### Path Parameters
 
 ```typescript
 export const GET: APIRoute = async ({ params }) => {
-  const { id } = params; // From /api/users/[id]
+  const { id } = params; // From users/[id].ts in the endpoint directory
 
   if (!id) {
-    return new Response(JSON.stringify({ error: "ID required" }), {
-      status: 400,
-      statusText: "Bad Request",
-      headers: { "Content-Type": "application/json" },
-    });
+    return Response.json({ error: "ID required" }, { status: 400 });
   }
 
-  // Use id to fetch data
+  return Response.json({ id });
 };
 ```
 
@@ -91,7 +104,7 @@ export const GET: APIRoute = async ({ request }) => {
   const limit = parseInt(url.searchParams.get("limit") || "10", 10);
   const offset = parseInt(url.searchParams.get("offset") || "0", 10);
 
-  // Use query parameters
+  return Response.json({ search, limit, offset });
 };
 ```
 
@@ -106,23 +119,15 @@ export const POST: APIRoute = async ({ request }) => {
     const { title, content } = body;
 
     if (!title || !content) {
-      return new Response(
-        JSON.stringify({ error: "Title and content required" }),
-        {
-          status: 400,
-          statusText: "Bad Request",
-          headers: { "Content-Type": "application/json" },
-        }
+      return Response.json(
+        { error: "Title and content required" },
+        { status: 400 }
       );
     }
 
-    // Process data
+    return Response.json({ title, content });
   } catch {
-    return new Response(JSON.stringify({ error: "Invalid JSON" }), {
-      status: 400,
-      statusText: "Bad Request",
-      headers: { "Content-Type": "application/json" },
-    });
+    return Response.json({ error: "Invalid JSON" }, { status: 400 });
   }
 };
 ```
@@ -136,116 +141,110 @@ const contentType = request.headers.get("Content-Type");
 
 ## Response Patterns
 
-Always return a `Response` object with proper status codes and headers:
+Return a `Response` from every handler path. `Response.json(body, { status })`
+serializes JSON and sets `Content-Type: application/json` automatically.
 
-```typescript
-// 200 OK
-return new Response(JSON.stringify({ data: result }), {
-  status: 200,
-  headers: { "Content-Type": "application/json" },
-});
-
-// 201 Created
-return new Response(JSON.stringify({ id: newId, ...data }), {
-  status: 201,
-  headers: { "Content-Type": "application/json" },
-});
-
-// 204 No Content (for DELETE)
-return new Response(null, { status: 204 });
-
-// 400 Bad Request
-return new Response(JSON.stringify({ error: "Invalid input" }), {
-  status: 400,
-  statusText: "Bad Request",
-  headers: { "Content-Type": "application/json" },
-});
-
-// 404 Not Found
-return new Response(JSON.stringify({ error: "Not found" }), {
-  status: 404,
-  statusText: "Not Found",
-  headers: { "Content-Type": "application/json" },
-});
-
-// 500 Internal Server Error
-return new Response(JSON.stringify({ error: "Internal server error" }), {
-  status: 500,
-  statusText: "Internal Server Error",
-  headers: { "Content-Type": "application/json" },
-});
-```
+| Status | Use |
+| --- | --- |
+| 200 | Successful read or update (default) |
+| 201 | Resource created |
+| 204 | Success without a body: `new Response(null, { status: 204 })` |
+| 400 | Invalid request |
+| 404 | Resource not found |
+| 500 | Unexpected server failure; return a generic error |
+
+For example: `Response.json({ error: "Not found" }, { status: 404 })`.
 
 ## Frontend Integration
 
-Call HTTP endpoints from frontend components using Wix's built-in HTTP client (`httpClient.fetchWithAuth()`):
+For app extensions, use `httpClient.fetchWithAuth()` from `@wix/essentials`.
+Build the URL from the extension module's origin, not the host page's origin.
+
+### `@wix/custom-extensions` Projects
+
+`wix dev` may run with `--base`, so the request must preserve
+`import.meta.env.WIX_SERVER_BASE_PATH`. The runtime defaults this value to `/`
+without a configured base, including the normal production build.
+During dev, the injected value is Vite's resolved base, which already has a
+trailing slash even when `--base` omits it. Concatenate the endpoint name
+directly, with `/` as a fallback for a missing/empty value.
+Do not hardcode the base prefix or add `/api` to a `@wix/custom-extensions` route.
 
 ```typescript
 import { httpClient } from "@wix/essentials";
 
-// GET request
-const baseApiUrl = new URL(import.meta.url).origin;
-const res = await httpClient.fetchWithAuth(
-  `${baseApiUrl}/api/<your-endpoint-name>`,
-);
-const data = await res.text();
-
-// POST request
-const res = await httpClient.fetchWithAuth(
-  `${baseApiUrl}/api/<your-endpoint-name>`,
-  {
-    method: "POST",
-    body: JSON.stringify({ message: "Hello from frontend" }),
-  },
-);
+const origin = new URL(import.meta.url).origin;
+const basePath = import.meta.env.WIX_SERVER_BASE_PATH || "/";
+const endpointUrl = `${origin}${basePath}hello`;
+
+// Inside an event handler or runtime data-loading function:
+const res = await httpClient.fetchWithAuth(endpointUrl);
+if (!res.ok) {
+  throw new Error(`Request failed: ${res.status}`);
+}
 const data = await res.json();
 ```
 
-## Identity and Authorization
+Keep the module origin: passing only `${basePath}hello` can resolve against the
+hosting site's origin instead of the app server.
+
+### Astro App Extensions
 
-Endpoints run as the **app**, so this is one of the few places `auth.elevate` is valid — it works only in backend code, never in a site, editor, or dashboard extension. It wraps the SDK method rather than being called around it, so inside a request handler you invoke the wrapper:
+For a standard Astro app endpoint, use its `/api` route without the
+`WIX_SERVER_BASE_PATH` variable. If the existing Astro configuration has its own base path,
+preserve that project's URL handling instead of applying the root-only example:
 
 ```typescript
-import { auth } from "@wix/essentials";
-import { locations } from "@wix/business-tools";
+import { httpClient } from "@wix/essentials";
 
-const elevatedArchive = auth.elevate(locations.archiveLocation);
-const archived = await elevatedArchive(locationId); // locationId read from the request
+const endpointUrl = new URL("/api/hello", import.meta.url).href;
+const res = await httpClient.fetchWithAuth(endpointUrl);
 ```
 
-**Only create an endpoint for calls that need it.** Settle that with [Identity and Elevation Requirement](../SKILL.md#identity-and-elevation-requirement) *before* adding a file under `src/pages/api/` — an endpoint wrapping a call the extension could have made itself is a correctness or privacy bug, not extra indirection, because elevating inside it re-targets a session-resolved call away from the visitor or hands back what the platform deliberately withheld.
-
-**Elevation bypasses Wix's permission check, so the endpoint must re-check the caller itself** — otherwise every caller who can reach it gets the elevated operation, and only `httpClient.fetchWithAuth()` (see [Frontend Integration](#frontend-integration)) sends the caller's identity for the handler to check; a bare `fetch` sends nothing and leaves the endpoint open.
-
-What you can establish depends on the host: a dashboard caller is a Wix user, whose roles already limit them. From a site or editor extension `members.getMyMember()` identifies a logged-in member, but there is **no documented way to prove the caller is the site owner** — a real constraint, not an oversight, so an owner-only operation belongs in a dashboard extension, where the Wix user identity already carries the authority, rather than behind an endpoint reachable from a site extension.
-
-## Build, Deploy, and Delete
+For either runtime, a POST uses the same endpoint URL with `method: "POST"`, a
+JSON body, and `Content-Type: application/json`, provided the route exports POST.
 
-To take HTTP endpoints to production, build and release your project:
-
-1. Build the project assets using the [`build`](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/build) command.
-2. Optionally create preview URLs using the [`preview`](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/preview) command to share with team members for testing.
-3. Release your project using the [`release`](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/release) command.
-
-Once released, endpoints are accessible at production URLs and handle live traffic.
+## Identity and Authorization
 
-To delete an HTTP endpoint, remove the file under `src/pages/api/` and release again.
+`auth.elevate` works only in backend code. Wrap the SDK method, then invoke
+that wrapper inside the request handler:
 
-## Output Structure
+```typescript
+import { auth } from "@wix/essentials";
+import { locations } from "@wix/business-tools";
 
+const elevatedArchive = auth.elevate(locations.archiveLocation);
+const archived = await elevatedArchive(locationId); // locationId read from the request
 ```
-src/pages/api/
-├── users.ts              # /api/users endpoint
-├── users/
-│   └── [id].ts           # /api/users/:id endpoint
-└── posts.ts              # /api/posts endpoint
-```
-
-## Backend-API-specific Conventions
 
-- Type all handlers with `APIRoute` from `astro`.
-- Always return `Response` objects with `JSON.stringify()` for JSON.
-- Use proper HTTP status codes (200, 201, 204, 400, 404, 500).
-- Include `Content-Type: application/json` header on JSON responses.
-- Include `statusText` in error responses.
-- Validate input parameters and request bodies.
+Before routing SDK calls through an endpoint, apply the
+[Identity and Elevation Requirement](../SKILL.md#identity-and-elevation-requirement).
+Keep visitor/session-resolved and caller-filtered calls in the frontend: elevation
+can change whose data is accessed or expose data the platform withheld.
+
+**Elevation bypasses Wix's permission check.** The endpoint must authorize the
+caller before invoking an elevated method. Use `httpClient.fetchWithAuth()` to
+send caller identity; a bare `fetch` does not supply that identity. Authentication
+alone does not grant permission to perform the operation.
+
+Dashboard callers are Wix users. For site/editor callers, `members.getMyMember()`
+identifies a logged-in member but does not prove site ownership. Owner-only
+operations belong in a dashboard extension; do not expose them to site visitors
+on the assumption that member authentication proves ownership.
+
+## Validate, Deploy, and Delete
+
+1. Install changed dependencies, typecheck, and run `wix build`.
+2. If a dev site is configured (`wix dev-site`), run `wix dev` and request the
+   URL; also exercise the frontend caller when one was requested. `wix preview`
+   uploads a version and exits; it is not a server.
+3. When deployment is requested, use the normal build/preview/release commands,
+   unless the environment hosting the project manages deployment itself.
+
+To delete an endpoint, remove its file from the appropriate directory and apply
+that change through the same deployment flow. No `.use()` cleanup is needed.
+
+If a route 404s, or the file was created by hand, confirm it was discovered: in a
+`@wix/custom-extensions` build `grep 'pattern:' dist/server/index.mjs` lists every route (a
+dynamic segment prints as `:"id"`); in an Astro build the route string appears
+under `dist/`. A missing entry means the file is outside the scanned directory.

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

@@ -6,17 +6,13 @@ Dashboard pages appear in the site owner's Wix dashboard, where admins manage da
 
 A dashboard page is a workflow, not a screen. The site owner has to understand the situation, focus on what needs attention, investigate one record, act, and see the result confirmed — so translate the prompt into those needs before choosing any component.
 
-Do this first because a bare filtered table answers "what are all the records" and none of "how many", "which one needs my attention", or "why did this happen" — and a table is what you get by default if the workflow was never named. Read [UX Success Model](dashboard-page/UX_SUCCESS_MODEL.md) now, and run its evaluation checklist before calling the page done. Which component serves each need: [Collection Toolkit](dashboard-page/COLLECTION_TOOLKIT.md).
+Do this first because a bare filtered table answers "what are all the records" and neither "which one needs my attention" nor "why did this happen" — and a table is what you get by default if the workflow was never named. Read [UX Success Model](dashboard-page/UX_SUCCESS_MODEL.md) now, and run its evaluation checklist before calling the page done. Which component serves each need is the installed package's own answer — see [The Discovery Chain](WIX_PATTERNS_DOCS.md#the-discovery-chain).
 
 ## UI Libraries — Read Before Writing Any JSX
 
-At Wix, dashboard pages are built from `@wix/patterns` and `@wix/design-system`, in that order of preference:
+`@wix/patterns` first, `@wix/design-system` for the leaf UI inside its shell, custom React only when neither has it. Do not hand-write React for anything either library provides, and do not decide a component is missing without checking.
 
-1. **`@wix/patterns` first** — page shells (`CollectionPage`, `EntityPage`, `SettingsPage`), tables/grids, collection state hooks, filters, sorting, row and bulk actions, in-extension routing. Look every name up directly in `dist/dts-bundle/index.json` and `dist/docs/index.json` (start with the inventory). See [WIX_PATTERNS_DOCS.md](WIX_PATTERNS_DOCS.md).
-2. **`@wix/design-system` second** — the leaf UI inside that shell (inputs, buttons, form fields, text, layout, cards, badges, icons). Choose components via the `wix-design-system` skill.
-3. **Custom React last** — only when neither library has it.
-
-Do not hand-write React for anything either library already provides, and do not decide a component is missing without checking. Full rule: [SKILL.md → Component Selection Order](../SKILL.md#component-selection-order).
+The order, what each library owns, and how to look a name up are stated once: [SKILL.md → Component Selection Order](../SKILL.md#component-selection-order).
 
 ## Scaffold
 
@@ -33,9 +29,9 @@ wix generate --params '{"extensionType":"DASHBOARD_PAGE","title":"<title>","rout
 
 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`.
 
-**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: [Entity Page Toolkit](dashboard-page/ENTITY_PAGE_TOOLKIT.md).
+**Never reuse `<route>` as a path prefix inside this page's `PatternsReactRouter`** — its location is already page-scoped, so a page scaffolded `route: "shifts"` still routes from `path="/"`, and `path="/shifts"` silently never matches. Page-relative paths: `<pkgRoot>/dist/docs/Collection to Entity Flow.md`.
 
-**Then, before writing UI:** resolve the package root and `Read <pkgRoot>/dist/dts-bundle/index.json` once, per [Prerequisites](WIX_PATTERNS_DOCS.md#prerequisites). Each Bash call is a fresh shell — re-set the path variable in every call.
+**Then, before writing UI:** resolve the package root and probe `<pkgRoot>/dist/docs/index.json` once with `grep`/`python3` — not a whole-file `Read`, which truncates it silently — per [Prerequisites](WIX_PATTERNS_DOCS.md#prerequisites). That index carries each symbol's `importPath`, `examples` and `bundle`, which is what decides whether you need to open anything else at all. Each Bash call is a fresh shell — re-set the path variable in every call.
 
 ## Capabilities
 
@@ -74,7 +70,7 @@ Dashboard Pages cannot use `<Modal />`. For a true dialog overlay you **MUST** u
 >
 > **If this page lists nothing** (settings, config) the rule doesn't apply. But "I built the list without `@wix/patterns`" is not an exception: a page that lists records should be a `CollectionPage`.
 >
-> See [Entity create and edit](../SKILL.md#entity-create-and-edit) and [WIX_PATTERNS_DOCS.md](WIX_PATTERNS_DOCS.md); for the `useEntityPage` call itself, [Entity Page Toolkit](dashboard-page/ENTITY_PAGE_TOOLKIT.md).
+> See [Entity create and edit](../SKILL.md#entity-create-and-edit) and [WIX_PATTERNS_DOCS.md](WIX_PATTERNS_DOCS.md); for the `useEntityPage` call itself, `<pkgRoot>/dist/docs/useEntityPage.md`.
 
 **Ecom Navigation:** See [Ecom Navigation Reference](dashboard-page/ECOM_NAVIGATION.md) for ecom-specific navigation helpers.