@wix/agent-skills 1.13.0 → 1.15.0

package/skills/wix-headless/references/inline-recipes/setup-restaurant-reservations.md

@@ -0,0 +1,117 @@
+---
+name: "Setup Restaurant Reservations"
+description: Configures Wix **Table Reservations**. Installing the app AUTO-provisions a default reservation location with a full config (approval AUTOMATIC, party size, weekly schedule, tables) — but with online reservations turned OFF. This recipe VERIFIES that location, CUSTOMIZES its config to the request, and TURNS ON online reservations (premium-gated). There is nothing to bulk-seed and no menu dependency. Specifies the *how* (calls + format); party sizes / hours come from the request.
+---
+**RECIPE**: Business Recipe – Table-Reservations Setup for Wix Restaurants (Table Reservations app)
+
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` **and** `wix-site-id: <SITE_ID>`. Body-bearing requests also need `Content-Type: application/json`.
+
+A checklist for turning on **table reservations** for a Wix site.
+**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial reservations setup.
+
+> **⚠️ Reservations is CONFIGURATION, not creation — there is NOTHING to bulk-seed.** Reservations themselves are created by **visitors at runtime** (the frontend flow), not at setup. And a **reservation location CANNOT be created via this API** — the docs are explicit: locations are "created and archived only through the Dashboard, or the Locations API." The Reservation Locations API only **queries / lists / updates**. So "setup" here means: verify the location the install already made, configure it, and switch online reservations on.
+
+> **⚠️ THE INSTALL AUTO-provisions a default reservation location — this recipe VERIFIES and CONFIGURES it.** Installing the Table Reservations app auto-creates **one reservation location** (`default: true`) with its own `location` object and a **complete default configuration** — `approval.mode: "AUTOMATIC"` (manual approval already OFF), `partySize {min:1, max:6}`, `minimumReservationNotice 30 MINUTES`, `defaultTurnoverTime 90`, a 7-day `businessSchedule` (08:00–22:00), `timeSlotInterval 15`, and table management ON with default tables. **The one thing OFF is `onlineReservationsEnabled: false`** — flipping it on is STEP 3.
+
+> **⚠️ NO menu dependency.** Reservations bind to a **location**, not a menu (unlike online ordering, which is menu-first). Do **not** copy the orders "seed the menu first" constraint — reservations can be set up with no menu at all.
+
+> **This recipe is the *how*, not the *what*.** Party-size limits, business hours, turnover time, and reservation-notice come from the request you're fulfilling. This recipe only specifies the calls and the request format. Per the "simple seeds" default, if the request names no reservation specifics, keep the auto-provisioned config and just do STEP 1 + STEP 3.
+
+> **API surface:** the **Reservation Locations** API on `https://www.wixapis.com/table-reservations/reservation-locations/v1/reservation-locations` (list `GET`, query `POST …/query`, get `GET …/{id}`, update `PATCH …/{id}`). The frontend visitor flow (time slots, held/reserve) is a separate concern — see `how-to-code-restaurant-reservations.md`.
+
+> **⚠️ Field names — post-Jan-2026 migration.** Use the **new** field names: **`partySize`** (not `partiesSize`), **`approval`** (not `manualApproval`), **`tables.ids`** (not `tableIds`), **`ignoreConflicts`** (not the three old flags). The old names were removed after 2026-02-28; the install response still echoes some deprecated twins (e.g. `partiesSize` alongside `partySize`) — write the new ones.
+
+---
+
+## Article: Steps for Setting Up Wix Table Reservations
+**YOU MUST** complete the steps in order (1-3) without requiring additional user input. Every step is idempotent — it verifies the auto-provisioned state and only writes when the request calls for a change.
+
+### STEP 1: Discover the auto-provisioned default reservation location
+
+List reservation locations and take the default one. Keep its **`id`** and **`revision`** (the PATCH in STEP 2/3 needs both).
+
+```bash
+curl -sS <AUTH> -X GET "https://www.wixapis.com/table-reservations/reservation-locations/v1/reservation-locations"
+```
+
+Response (`reservationLocations[]`):
+
+```json
+{ "reservationLocations": [
+  { "id": "<reservationLocationId>", "revision": "1", "default": true, "archived": false,
+    "location": { "id": "<locationId>", "name": "Location 1", "timeZone": "America/New_York" },
+    "configuration": { "onlineReservations": {
+      "approval": { "mode": "AUTOMATIC" },
+      "partySize": { "min": 1, "max": 6 },
+      "minimumReservationNotice": { "number": 30, "unit": "MINUTES" },
+      "defaultTurnoverTime": 90,
+      "businessSchedule": { "periods": [ { "openDay": "MONDAY", "openTime": "08:00", "closeDay": "MONDAY", "closeTime": "22:00" } ] },
+      "onlineReservationsEnabled": false,
+      "timeSlotInterval": 15
+    } } }
+] }
+```
+
+**⚠️ CRITICAL:**
+- **Do not POST to create a location** — there is no create method in this API; use the one the install made. If `reservationLocations[]` is **empty**, the install hasn't finished provisioning — **wait briefly and retry the GET once**; do not try to create one. Still empty after one retry → **fail loud** (either the install didn't complete, or the site genuinely has no location; a location can only be added via the Dashboard / Locations API, which is out of scope here).
+- Take the entry with **`default: true`** (there's normally exactly one). Keep `reservationLocation.id` and the **current** `revision`.
+- **Verify `configuration.onlineReservations.approval.mode` is `"AUTOMATIC"`** — that means manual approval is OFF, which is required for a headless site to auto-confirm reservations (there's no dashboard operator to approve). It's the default; only PATCH it (STEP 2 shape) if you find it set to a manual mode.
+
+### STEP 2: Customize the configuration (only what the request names)
+
+PATCH the location to set party-size limits, hours, turnover, or notice per the request. Partial updates are supported; **`revision` is mandatory**. **Config PATCH works on a non-premium site** (unlike the enable toggle in STEP 3).
+
+```bash
+curl -sS <AUTH> -X PATCH \
+  "https://www.wixapis.com/table-reservations/reservation-locations/v1/reservation-locations/<reservationLocationId>" \
+  -d '{
+    "reservationLocation": {
+      "id": "<reservationLocationId>",
+      "revision": "<revision>",
+      "configuration": { "onlineReservations": {
+        "partySize": { "min": 2, "max": 10 },
+        "minimumReservationNotice": { "number": 60, "unit": "MINUTES" },
+        "defaultTurnoverTime": 90
+      } }
+    }
+  }'
+```
+
+**⚠️ CRITICAL:**
+- **`revision` must be the current one** (from STEP 1, or the previous PATCH's response); it increments by 1 each update — a stale revision 400s. Keep the new revision for STEP 3.
+- **You cannot change the `location` object** via this method (address/name live on the business Location) — attempting to returns an application error. Only touch `configuration`.
+- Use the **new** field names (`partySize`, `approval`) — see the migration callout above.
+- Skip this step entirely if the request names no reservation specifics (keep the auto-provisioned config).
+
+### STEP 3: Turn on online reservations (premium-gated)
+
+Flip `onlineReservationsEnabled` on so visitors can book. Send the current `revision`.
+
+```bash
+curl -sS <AUTH> -X PATCH \
+  "https://www.wixapis.com/table-reservations/reservation-locations/v1/reservation-locations/<reservationLocationId>" \
+  -d '{
+    "reservationLocation": {
+      "id": "<reservationLocationId>",
+      "revision": "<revision>",
+      "configuration": { "onlineReservations": { "onlineReservationsEnabled": true } }
+    }
+  }'
+```
+
+**⚠️ CRITICAL — this toggle is PREMIUM-ONLY; on a non-premium site it returns `428 PREMIUM_ONLY`, NOT success.** On a free/headless site this PATCH fails with:
+```json
+{ "message": "Can't turn on online reservation for a non-premium website", "details": { "applicationError": { "code": "PREMIUM_ONLY" } } }
+```
+This is a **site-provisioning precondition, not a recipe bug** — treat `428 PREMIUM_ONLY` as an **expected, non-fatal** outcome: record that the site must be upgraded to premium before online reservations can be turned on (the owner then enables it, in the Dashboard or via this same call on the premium site), and **continue**. Do **not** retry-spiral it and do **not** fail the whole seed over it. (This is stricter than online ordering, where only *paid checkout* needs premium — here the *enable toggle itself* is gated.) On a premium site the same call returns the updated location with `onlineReservationsEnabled: true`.
+
+---
+
+## Conclusion
+Following these steps configures Table Reservations for a site:
+- Uses the **auto-provisioned default reservation location** (discovered, never created — locations come only from the Dashboard / Locations API), with its `id` + `revision` kept.
+- Verifies **manual approval is off** (`approval.mode: "AUTOMATIC"`) so a headless site auto-confirms.
+- **Customizes** party size / hours / turnover / notice per the request via `PATCH` (works on non-premium; `revision` mandatory; `location` object immutable here; new field names).
+- **Attempts to enable online reservations** (`onlineReservationsEnabled: true`) — succeeds on premium, returns a non-fatal **`428 PREMIUM_ONLY`** on a non-premium site (recorded as a premium precondition, not a failure).
+- **Nothing is bulk-seeded** and there is **no menu dependency** — reservations are created by visitors at runtime (`how-to-code-restaurant-reservations.md`).
+</content>

package/skills/wix-headless/references/inline-recipes/setup-restaurants.md

@@ -0,0 +1,152 @@
+---
+name: "Setup Restaurants"
+description: Initializes a Wix Restaurants Menus backend — cleans the install's default sample menu, then bulk-creates items, bulk-creates sections (referencing item ids), and creates the menu (referencing section ids), all visible. Specifies the *how* (calls + format); the menu/section/item counts and names come from the request.
+---
+**RECIPE**: Business Recipe – Initial Setup for Wix Restaurants (Menus API)
+
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` **and** `wix-site-id: <SITE_ID>`. Body-bearing requests also need `Content-Type: application/json`.
+
+A concise checklist for preparing any new Wix site that uses the Wix Restaurants **Menus** app.
+**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial menu setup.
+
+> **This recipe is the *how*, not the *what*.** What to seed — how many menus, which sections, how many items per section and their names/descriptions/prices — is determined by the request you're fulfilling. This recipe only specifies the calls and the request format; it does not decide quantities or which entities to create.
+
+> **API surfaces:** everything is the Restaurants **Menus V1** API on `https://www.wixapis.com/restaurants/menus/v1/...` (menus, sections, items — all under this one service). This is the **new** Wix Restaurants Menus API; do not mix in any older `restaurants/v1beta` or ordering/reservations endpoints. Online ordering and table reservations are **separate apps** and out of scope for menu seeding.
+
+> **REST flattens the protobuf wrappers.** The raw method schemas show fields like `visible`, `id`, `description` as wrapper objects (`{"value": …}`). In the actual REST JSON they are **plain values** — send `"visible": true`, `"description": "text"`, and read back `"id": "<guid>"`. Never send `{"value": …}`.
+
+---
+
+## Article: Steps for Setting Up Wix Restaurants Menus
+**YOU MUST** complete all the following steps **in the given order** (0-3) without skipping any and **without requiring additional user input**. The **Attach images** step runs last, only when `imagery` is on.
+
+**⚠️ CRITICAL ORDER REQUIREMENT: build the hierarchy BOTTOM-UP — items (STEP 1) → sections (STEP 2) → menu (STEP 3).** A section is created with the **`itemIds`** of the items it contains, and a menu is created with the **`sectionIds`** of the sections it contains. So the child ids must exist before you create the parent. Do the cleanup (STEP 0) first of all, so the ids you delete are provably the install's samples.
+
+### STEP 0: Clean the install — remove the default sample menu
+
+**A freshly installed Wix Restaurants Menus app ships a fully populated default "Dinner Menu"** (roughly one menu, ~4 sections, ~21 items). Remove it **before** creating yours, so the storefront shows only your menu. Do this **first** — cleaning before you create guarantees the ids you delete are the install's samples, never your own entities. Delete children before parents (items → sections → menus):
+
+1. **Bulk-delete items** — `GET https://www.wixapis.com/restaurants/menus/v1/items` (collect every `items[].id`), then `DELETE https://www.wixapis.com/restaurants/menus/v1/bulk/items/delete` with body `{"ids": ["<id>", …]}`.
+2. **Bulk-delete sections** — `GET https://www.wixapis.com/restaurants/menus/v1/sections` (collect every `sections[].id`), then `DELETE https://www.wixapis.com/restaurants/menus/v1/bulk/sections/delete` with body `{"ids": ["<id>", …]}`.
+3. **Delete menus** — `GET https://www.wixapis.com/restaurants/menus/v1/menus` (collect every `menus[].id`), then delete each one with `DELETE https://www.wixapis.com/restaurants/menus/v1/menus/{menuId}` (**no bulk-delete endpoint for menus** — one DELETE per menu; there is normally just the single default menu). Single delete takes only the path id — **no `revision` needed**.
+
+The bulk-delete responses carry per-id `results[].itemMetadata.success`; a menu delete returns `200 {}`. If the lists come back empty, this is a safe no-op — continue.
+
+### STEP 1: Bulk-create the items
+
+Create all items in a **single bulk request** to `POST https://www.wixapis.com/restaurants/menus/v1/bulk/items/create`. **How many items, and their names/descriptions/prices, come from the request you're fulfilling — this step only gives the call and the required format.**
+
+**Request body shape** (one representative item shown — repeat item objects inside the `items` array):
+
+```json
+{
+  "items": [
+    {
+      "name": "Bruschetta al Pomodoro",
+      "description": "Grilled sourdough, San Marzano tomatoes, basil.",
+      "priceInfo": { "price": "9.50" },
+      "visible": true
+    }
+  ],
+  "returnEntity": true
+}
+```
+
+**⚠️ CRITICAL FORMAT REQUIREMENTS:**
+- **Price goes in `priceInfo.price` as a decimal STRING** (`"9.50"`, not the number `9.50`). The currency is **derived from the site** — do **not** send a currency; the response echoes a `priceInfo.formattedPrice` (e.g. `"$9.50"`) in the site's currency.
+- **Do NOT use the top-level `price` field** — it is deprecated (superseded by `priceInfo`). Use `priceInfo.price`.
+- **`description` is a plain string** (not rich-text nodes). Omit it for a name-only item.
+- **Set `"visible": true` explicitly** on every item (see the visibility callout below).
+- **Imagery is opt-in** (`SEED.md` § "Entity images"). Seed **text-only by default** — omit `image`. When `imagery` is on, the **Attach images** step below writes an `image` onto each item in a second pass.
+- If part of the bulk request fails, retry the failed items **once** with the exact same format; do not loop.
+
+**⚠️ Reading the response — created items are under `results[].item`, and `results[].itemMetadata.success` is the per-item flag.** A successful bulk create returns `200`:
+
+```json
+{ "results": [
+  { "itemMetadata": { "id": "<itemId>", "originalIndex": 0, "success": true },
+    "item": { "id": "<itemId>", "name": "Bruschetta al Pomodoro", "priceInfo": { "price": "9.50", "formattedPrice": "$9.50" }, "visible": true } }
+], "bulkActionMetadata": { "totalSuccesses": 1, "totalFailures": 0 } }
+```
+
+Keep each item's **`id`** (from `results[].item.id`), grouped by the section it belongs to — STEP 2 wires items into sections via these ids.
+
+### STEP 2: Bulk-create the sections (referencing their item ids)
+
+Create all sections in a **single bulk request** to `POST https://www.wixapis.com/restaurants/menus/v1/bulk/sections/create`. Each section carries the **`itemIds`** array of the items (from STEP 1) that belong to it. **Which sections, and which items go in each, come from the request you're fulfilling.**
+
+**Request body shape** (repeat section objects inside the `sections` array):
+
+```json
+{
+  "sections": [
+    {
+      "name": "Antipasti",
+      "description": "To start",
+      "visible": true,
+      "itemIds": ["<itemId1>", "<itemId2>"]
+    }
+  ],
+  "returnEntity": true
+}
+```
+
+**⚠️ CRITICAL:**
+- **`itemIds` must be real item ids from STEP 1**, in the display order you want. An item can appear in more than one section, but normally each item belongs to exactly one.
+- **Set `"visible": true` explicitly.**
+- Read created sections from **`results[].item`** (the bulk envelope reuses the generic `item` key even for sections). Keep each section's **`id`** — STEP 3 wires sections into the menu via these ids.
+- Retry failed sections **once**; do not loop.
+
+### STEP 3: Create the menu (referencing its section ids)
+
+Create the menu with `POST https://www.wixapis.com/restaurants/menus/v1/menus`. The menu carries the **`sectionIds`** array of the sections (from STEP 2) it contains. There is normally **one** menu; if the request calls for several, use the bulk endpoint `POST https://www.wixapis.com/restaurants/menus/v1/bulk/menus/create` with a `{"menus": [ … ], "returnEntity": true}` body (same envelope as items/sections).
+
+**Request body shape** — the single-create wraps the menu in a **`menu`** object:
+
+```json
+{
+  "menu": {
+    "name": "Dinner",
+    "description": "Evening menu",
+    "visible": true,
+    "sectionIds": ["<sectionId1>", "<sectionId2>"]
+  }
+}
+```
+
+**⚠️ CRITICAL:**
+- **`sectionIds` must be real section ids from STEP 2**, in display order.
+- **Set `"visible": true` explicitly.**
+- The single-create response is `{"menu": { "id": "<menuId>", "sectionIds": [ … ], "visible": true, "urlQueryParam": "dinner" }}` — read the **`menu.id`** (bulk create returns `results[].item` like the others). Keep the `menuId`.
+- **`businessLocationId` is optional** — omit it and the menu/section bind to the site's default (main) business location. Only set it for a multi-location restaurant when the request names locations.
+
+**⚠️ VISIBILITY — set `"visible": true` explicitly at every level (item, section, menu).** Storefront menu queries return only visible entities to visitors. Always include `visible: true` on every item, every section, and the menu, rather than relying on a default — an entity created without it may exist but not render on the live site.
+
+### Attach images (imagery ON only — skip otherwise)
+
+**Only when `imagery` is on** (`SEED.md` § "Entity images"). Items were created text-only in STEP 1; this pass-2 step writes a generated dish image onto each. The **item** is the image-bearing entity (sections and the menu render from their items) — attach per item. Generate + import per `references/IMAGE_GENERATION.md` → keep `file.url` and its `file.id`, then PATCH the item.
+
+**⚠️ On write, `image` is an OBJECT `{ id, url, height, width }`** (per the Create/Update Item docs) — even though the storefront SDK surfaces `item.image` as a bare *string* on **read** (`how-to-code-restaurants.md` § "Rendering images"; at the REST layer the read is an object too). Do **not** write a plain string. The binding field is the image **`id`** (the Wix Media file id); `url` + dimensions are descriptive.
+
+**⚠️ CRITICAL: Update Item is a FULL-ENTITY REPLACE with NO field mask — you MUST echo the item's existing `priceInfo` (and `priceVariants`, if the item is variant-priced) in the PATCH body, alongside `image`.** A body of just `{ id, revision, image }` drops the price and fails **`428 MISSING_ITEM_PRICING`** (`"Item must have either price or price variants"`) — the write does **not** apply. So first **`GET https://www.wixapis.com/restaurants/menus/v1/items/{itemId}`** for the item's current **`revision` + `priceInfo`** (or reuse the `item.revision` + `item.priceInfo` from STEP 1's `returnEntity` response), and echo both back:
+
+```bash
+curl -X PATCH 'https://www.wixapis.com/restaurants/menus/v1/items/<itemId>' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "item": { "id": "<itemId>", "revision": "<current revision>", "priceInfo": { "price": "<current price>" }, "image": { "id": "<file.id>", "url": "<file.url>", "height": 1024, "width": 1024 } } }'
+```
+
+- **Bulk variant** — to image many items at once, `POST https://www.wixapis.com/restaurants/menus/v1/bulk/items/update` with `{"items": [ { "item": { "id", "revision", "priceInfo", "image": {…} } }, … ]}` (each item still needs its own `revision` **and** its `priceInfo` — the full-replace rule applies per item).
+- A **stale or omitted `revision`** fails the update — fetch/echo the current one.
+- **Never block on image failure** (`SEED.md` § "Entity images" / IMAGE_GENERATION "Credits, cost & the not-generating fallback") — on failure, skip and leave the item text-only.
+
+---
+
+## Conclusion
+Following these steps **in order** sets up a new Wix Restaurants Menus site:
+- Starts from a **clean menu** — the install's default sample "Dinner Menu", its sections, and its items are all removed first.
+- Contains the menu, sections, and items called for by the request, built **bottom-up** (items → sections → menu) so every parent references real child ids.
+- Every item, section, and menu is created **`visible: true`** so it appears on the live site.
+- Prices are decimal strings under `priceInfo.price`; currency is the site's own. All calls use the Restaurants **Menus V1** API.
+- Items are seeded **text-only**; when `imagery` is on, the **Attach images** step writes an `image` **object** (`{ id, url, height, width }`) onto each — never a bare string. Update Item is a full replace with no field mask, so the PATCH echoes the item's existing `revision` **and** `priceInfo` alongside `image` (a body missing `priceInfo` fails `428 MISSING_ITEM_PRICING`).

package/skills/wix-headless/references/managed/AUTHENTICATION.md

@@ -0,0 +1,57 @@
+# Authentication — managed (Wix CLI)
+
+For a **managed** project (hosted on Wix infrastructure), every Wix call uses a token minted by the **Wix CLI** — `@wix/cli` + `curl`, no MCP, no SDK. This file is the authority for how `managed` obtains `$TOKEN`, `$SITE_ID`, and the public `clientId`; the flow files (`SETUP.md`, `SEED.md`, `SDK_HANDOFF.md`) defer here.
+
+## 1 · Ensure an authenticated CLI session
+
+```bash
+npx @wix/cli@latest whoami   # exits 0 when logged in; non-zero when logged out
+```
+
+If it's non-zero, **log in yourself** — don't punt to the user and stop:
+
+1. Run `npx @wix/cli@latest login` with **`run_in_background: true`** (no shell `&`, no redirect of your own — the harness captures stdout to its task-output file and returns the path).
+2. Poll that file for the first JSON event: `{"event":"awaiting_user","userCode":"…","verificationUri":"…"}`.
+3. Surface it to the user in plain prose: *"Open `<verificationUri>` and enter the code `<userCode>` — I'll continue once you've logged in."* **Send the message; do not re-invoke login.**
+4. Wait for the harness `task-notification` with `<status>completed</status>` (not a sleep loop). On exit 0, run `whoami` once to confirm, then proceed.
+
+## 2 · Mint the token
+
+```bash
+SITE_ID="<siteId>"   # from wix.config.json
+TOKEN=$(npx @wix/cli@latest token --site "$SITE_ID")
+```
+
+- Mints a **site-scoped REST token**. **Mint once per run and never re-mint** — the CLI returns a **byte-identical** token on every call within a run (it caches internally), so re-minting only costs ~1.25 s of startup. Cache `$TOKEN` and `$SITE_ID` in scratch.
+- Use `npx @wix/cli@latest token …` (not bare `wix token`) so `npx` resolves the project-local CLI.
+- The first `--site "$SITE_ID"` call is the source of truth for `SITE_ID`; bind it in scratch, don't re-derive mid-run.
+
+## 3 · `clientId` for the frontend
+
+The frontend's public `clientId` **is the `appId` field in `wix.config.json`** — for a managed headless project the OAuth **app id and the client id are the same value** (app-id === client-id). It's the same file you already read for `siteId` (§2), so **read `appId` straight from there** — do **not** query the OAuth-apps API, search the docs, or mint anything to obtain it. (It's the public OAuth id, not a secret.)
+
+## REST call shape
+
+```bash
+curl -sS -w "\nHTTP_STATUS:%{http_code}" \
+  -X POST "https://www.wixapis.com/<endpoint>" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "wix-site-id: $SITE_ID" \
+  -H "Content-Type: application/json" \
+  -d '<body>'
+```
+
+- **`Authorization: Bearer $TOKEN`** — the `Bearer` prefix is required.
+- **`wix-site-id: $SITE_ID`** — required by every site-scoped family; include it always.
+- **`Content-Type: application/json`** — on every POST/PATCH body.
+- **Parsing the response:** `-w` appends a `HTTP_STATUS:<code>` line *after* the JSON body. `grep` that line for the status, but parse the **body separately** — piping the combined output to a JSON parser (`python3 -m json.tool`, `json.load`, `jq`) chokes on the trailing status line (`Extra data: line 2 …`). Capture the body to a file with `-o body.json` (status still comes from `-w`), or drop the last line, before parsing.
+
+## Recovery ladder
+
+Re-mint is **not** a recovery step (the token is byte-identical) — retry the *same* call with the cached token.
+
+| Symptom | First response | If it still fails |
+|---|---|---|
+| `401 Unauthorized` | Retry once with the cached token. | CLI session expired — run `npx @wix/cli@latest login` (a new session), then re-mint. |
+| `403 Forbidden` | Retry once with the cached token. | App not installed yet (re-check the apps-installer returned 200), or the caller lacks permission — surface the response; don't loop. |
+| `404` on a documented URL | Re-read the recipe — a path typo. | Recipe bug; surface and stop. |

package/skills/wix-headless/references/managed/CONNECT.md

@@ -0,0 +1,74 @@
+# Connect — wire an existing project to a managed Wix backend
+
+**Managed only.** This flow runs when the project type is `managed` and the operation is
+`connect` **or** `iterate` — a frontend project is already on disk (or a design URL was fetched into
+CWD) and the user wants it hosted on Wix and powered by Wix Business Solutions. It attaches Wix to the
+project (or reuses the existing connection when iterating), runs the shared backend flow, wires the UI
+to that backend, builds, and releases. **The only difference for `iterate`** — the project is already
+connected, so §1 skips `init` and reuses the existing `wix.config.json`.
+**No Designer, no templates, no binding-map machinery** — `SDK_HANDOFF.md` is the wiring reference.
+
+Run these in order:
+
+## 1 · Attach Wix to the project — skip if already connected
+
+**If a `wix.config.json` (or `.wix/`) is already present, the project is already connected to Wix — this is the *iterate* case.** Do **not** run `init` again (it's for attaching a *new* Wix project). Read `./wix.config.json` → hold `SITE_ID` in scratch, and skip to §2.
+
+> **Iterate is incremental.** An already-connected project may already be set up and/or seeded from a prior run. In §3–§4, **check current state before acting** — query installed apps before installing, check for already-seeded content before seeding (re-seeding duplicates it), and inspect existing wiring before adding. Do only the delta the new intent requires; leave the rest untouched.
+
+Otherwise, attach Wix in place:
+
+```bash
+CI=1 npm create @wix/new@latest init
+```
+
+Run from the project directory. It creates `wix.config.json` (with the `siteId` and the headless
+OAuth app) and registers the project's origin on that app. Read `./wix.config.json` → hold `SITE_ID`
+in scratch.
+
+**If the design was brought in from elsewhere** (a `.zip`/folder/file, or a fetched design-file URL),
+place it into CWD **first** — unzip/copy/fetch the design's files into the working directory so it's the
+project on disk — **then** `init`. An empty CWD plus a brought-in design is still `connect`, not create:
+land the design, then attach Wix to it.
+
+## 2 · Authenticate
+
+Per `references/managed/AUTHENTICATION.md` — `whoami`/login if needed, then mint the site token
+(`$TOKEN`) for `$SITE_ID`.
+
+## 3 · Backend flow (shared)
+
+- **`references/SETUP.md`** — install the apps the resolved `verticals[]` need.
+- **`references/SEED.md`** — create the backend content (and, if `imagery` is on, attach entity images).
+
+## 4 · Wire the existing UI
+
+**Read the frontend reference for *how to connect* first**, keyed on the brought project's framework:
+an **Astro** project → **`references/astro.md`** (auto-auth, no client); **any other framework or a
+static design** → **`references/non-astro.md`** (manual `OAuthStrategy` client). The chosen file carries
+the connect mechanics and the framework caveats; **`references/SDK_HANDOFF.md`** carries the
+per-capability packages, the SDK docs, and the seeded schema (all other content is queried live).
+
+Connect the existing project to the live backend. Install the SDK packages the loaded verticals need;
+then, with **additive** edits:
+- bind seeded content into the regions that already exist (product grids, post lists, item pages…);
+- add the connected feature the intent implies where it's missing (e.g. a contact/RSVP form, a cart);
+- always guard SDK calls (try/catch + fallback) so a failed call never blanks the page.
+
+A run must end with the site actually reading from / writing to Wix — `init` + `release` with nothing
+wired is not an acceptable outcome. If `imagery` is on and a surface needs an image, generate it per
+**`references/IMAGE_GENERATION.md`** (up to the per-run `imageCap`, Discovery §4); for any slot not
+generated — off, over the cap, or a failure — render the **themed-block fallback** (a styled `div` on
+the design tokens), never an empty or broken slot.
+
+## 5 · Build & release
+
+**Release once, at the very end** — only after Setup (§3), Seed **including the entity-image attach** (`SEED.md` § "Entity images"), the UI wiring (§4), and any imagery are all complete. Don't `build && release` mid-flow to preview. **A re-release does not refresh backend content:** a headless frontend fetches seeded content and entity images at **runtime**, so they're not in the build output — changing a seeded entity or attaching an image after release is live on the next request with **no** re-publish. Re-release only when the **frontend build output** changed. A backend image that isn't showing is an attach-shape bug (`SEED.md` § "Entity images"), not a stale cache — don't re-release to clear one.
+
+If the project has its own build (`package.json` with a `build` script), run `npm run build` and point
+`wix.config.json`'s `site.outputDirectory` at the build output. A **static** site (no build) needs the
+static-hosting fixes in **`references/managed/DEPLOYMENT.md`** — the entry file must be named
+`index.html`, and `outputDirectory` must point at the directory holding it (init's `./dist` default is
+wrong for static). Then finalize per **`references/managed/DEPLOYMENT.md`** (`npx @wix/cli@latest release` — Wix
+publishes + registers the origin OOTB). Close with a short summary (apps installed, content seeded, what
+was wired, live URL).

package/skills/wix-headless/references/managed/CREATE.md

@@ -0,0 +1,130 @@
+# Create — scaffold a new managed Wix Headless project
+
+**Managed only.** This flow runs when the project type is `managed` and the operation is
+`create` (an empty directory + a "build me a site" intent). It scaffolds a fresh Wix Headless
+project, runs the shared backend flow against it, builds the frontend wired to that backend, and
+releases. There is **no Designer and no template library** — the frontend is built ad-hoc to the
+user's intent, using `SDK_HANDOFF.md` as the integration reference.
+
+Run these in order:
+
+## 0 · Resolve the frontend framework
+
+Default is **Astro** — the documented managed default. Set `frontendFramework` to a non-Astro
+framework **only if the user names one**: "Vite", "React", "Vue", "Svelte", "Next", "plain HTML/static",
+or any "not Astro / don't use Astro" phrasing. Never infer a framework the user didn't name
+(`references/non-astro.md` Caveat N1). Hold `frontendFramework` in scratch — it selects the **scaffold
+command (§1)**, the **wiring reference (§4)**, and the **build command (§5)**. Derive `<folder-name>` as
+a lowercase, npm-safe name from the brand (lowercase letters, numbers, hyphens; starts with a letter or
+number).
+
+## 1 · Scaffold the project
+
+Branch on `frontendFramework` from §0. **Both** branches end with a `wix.config.json` (the Wix link:
+`siteId` + private-app `appId`) in the project root — read it → hold `SITE_ID` (the `siteId`) in scratch.
+
+### Astro (default)
+
+Run the **documented** create command (flags and rationale: `references/astro.md` §1):
+
+```bash
+CI=1 npm create @wix/new@latest -- headless \
+  --folder-name <folder-name> \
+  --business-name "<Brand Name>" \
+  --site-template \
+  --skip-install \
+  --no-publish
+```
+
+- The `--` separator is required. Bare `--site-template` (no value) keeps it on the **blank** starter —
+  the model owns design, so don't adopt a business template; a value, or omitting the flag, would
+  prompt and abort in a non-interactive shell.
+- The command provisions the Wix site + private app and writes `wix.config.json`. It requires a
+  logged-in CLI session (step 2 handles login if needed).
+- It creates the project in a **subdirectory named `<folder-name>`** — there is no in-place option, so
+  **`cd <folder-name>`** and run the rest of the flow from inside it (it's the project root, with the
+  single `.wix/`).
+- `--skip-install` defers dependency install to step 4 (which adds the SDK package set); run
+  `npm install` there before building.
+
+### Non-Astro (a framework was named)
+
+There is **no Wix scaffolder for a non-Astro site** (`non-astro.md` N1) — so scaffold the framework's
+**own** project first, then `init` it onto Wix (two steps, in this order):
+
+```bash
+# 1. the framework's OWN documented scaffolder — e.g. Vite + React:
+npm create vite@latest <folder-name> -- --template react
+cd <folder-name>
+# 2. connect this folder to a fresh Wix headless project, IN PLACE:
+CI=1 npm create @wix/new@latest init
+```
+
+- Use the framework's documented create command (read its docs if unsure of the template flag) — Vite,
+  Next, SvelteKit, Vue, etc. For **plain static HTML** there's no scaffolder: create the folder and an
+  `index.html` yourself, then run `init`.
+- `npm create @wix/new@latest init` runs **in place** (no new subdirectory, no Astro files added): it
+  signs you in, provisions the Wix site + private app, and writes `wix.config.json`
+  (`siteId`, `appId`, `site.outputDirectory: "./dist"`). It takes no flags. Run it **from inside**
+  `<folder-name>` *after* the framework scaffold exists.
+- A static (no-build) frontend builds to no `dist` — fix `site.outputDirectory` per
+  `managed/DEPLOYMENT.md` ("Static frontends") before release.
+
+## 2 · Authenticate
+
+Per `references/managed/AUTHENTICATION.md` — `whoami`/login if needed, then mint the site token
+(`$TOKEN`) for `$SITE_ID`. (Scaffold already required a logged-in CLI session.)
+
+## 3 · Backend flow (shared)
+
+Run the agnostic flow against the scaffolded site:
+- **`references/SETUP.md`** — install the apps the resolved `verticals[]` need.
+- **`references/SEED.md`** — create the backend content (and, if `imagery` is on, attach entity images).
+
+## 4 · Build the frontend (wired to the backend)
+
+**Read the frontend reference for *how to connect* first — pick it by `frontendFramework` (§0):**
+
+- **Astro** (default) → **`references/astro.md`**: managed-Astro auto-authenticates, so the frontend
+  creates **no client** (no `OAuthStrategy`, no `clientId`) — you `import { x } from "@wix/<pkg>"` and
+  call methods. astro.md also carries the load-bearing caveats (the always-on `astro.config.mjs`
+  integrations, SSR error guards, island hydration).
+- **Non-Astro** → **`references/non-astro.md`**: the manual `OAuthStrategy` visitor-client path
+  (`createClient({ modules, auth: OAuthStrategy({ clientId }) })`), where `clientId` is the public
+  `appId` from the `wix.config.json` written by `init` (§1).
+
+Then build the pages the user's intent calls for, **wired to the live backend**, using
+**`references/SDK_HANDOFF.md`** for the per-capability packages, the SDK docs, and the seeded schema to
+bind (collection/form names + field keys; all other content is queried live). Install the SDK packages the loaded verticals need, author the pages/components directly in the
+project, and bind them to the live backend content. Keep it scoped to what was asked — no speculative pages.
+
+> **`npm install` note (Astro):** always run **`npm install --ignore-scripts`**. Astro pulls `sharp`
+> as an *optional* transitive dep for **local, build-time**
+> image optimization this headless flow never uses (all imagery is remote Wix Media URLs served through
+> plain `<img>`), and its from-source native build can fail and abort the whole install; `--ignore-scripts`
+> skips that failing build up front. **Do not** use the deprecated `--no-optional` (silent no-op in modern
+> npm — sharp still builds) or `--omit=optional` (sharp still resolves). A failed/absent `sharp` is
+> **expected and harmless — never build, retry, or repair it, and never spend time diagnosing it**
+> (`astro.md` Caveat A9).
+
+If `imagery` is on and a surface needs an image (e.g. a homepage hero, an about-section visual),
+generate it per **`references/IMAGE_GENERATION.md`** and use its `file.url` — up to the per-run
+`imageCap` (Discovery §4). Generate only what the pages actually use. For any slot **not** generated
+(imagery off, over the cap, or a generation failure), render the **themed-block fallback** — a styled
+`div` on the site's design tokens — never an empty slot or a broken `<img>` (`IMAGE_GENERATION.md`).
+
+## 5 · Build & release
+
+**Release once, at the very end.** Do **not** `build && release` mid-flow to "preview" progress. Reach this step only after **all** of the earlier work is done: Setup (§3), Seed **including the entity-image attach** (`SEED.md` § "Entity images" — pass-2 patches), the frontend wiring (§4), and any page imagery. A single release at the end is the target; each extra build+release cycle is wasted wall time.
+
+**A re-release does not refresh backend content — don't reach for one to "fix" seeded data or images.** A headless frontend fetches seeded backend content **and entity images at runtime** (via the SDK / REST), so that content is *not* baked into the build output. If you change a seeded entity or attach an image **after** releasing, the live site already reflects it on the next request — there is nothing to re-publish. Re-release **only** when the **frontend build output itself** changed. In particular, a backend image that isn't showing is an **attach-shape bug** (wrong write shape → the entity has no image — see `SEED.md` § "Entity images" / the capability recipe's **Attach images** step), **not** a stale CDN cache; don't re-release to "clear a cache" for it.
+
+Produce the build output, then finalize per **`references/managed/DEPLOYMENT.md`**
+(`npx @wix/cli@latest release` — Wix publishes the site and registers the origin OOTB). The build step
+depends on `frontendFramework` (§0):
+
+- **Astro** → `npx @wix/cli@latest build`.
+- **Non-Astro** → the framework's own build (e.g. `npm run build`); a static (no-build) site skips this.
+  `release` publishes whatever `site.outputDirectory` points at (default `./dist`).
+
+Close with a short summary (apps installed, content seeded, pages built, live URL).

package/skills/wix-headless/references/managed/DEPLOYMENT.md

@@ -0,0 +1,57 @@
+# Deployment — managed (Wix CLI release)
+
+For a **managed** project, Wix owns the hosting, so finalizing the live site is a single command — Wix handles publishing the site **and** registering the deployed origin on the OAuth app **out of the box**. There are no manual publish or origin-registration calls (unlike the self-hosted types).
+
+## Release
+
+From the project directory:
+
+```bash
+CI=1 npx @wix/cli@latest release
+```
+
+- Publishes whatever the managed project is configured to deploy to Wix's hosting/CDN, and brings the live site up.
+- The deployed origin is registered on the OAuth app automatically — the frontend's visitor SDK calls are accepted from the live URL with no extra step.
+- The published URL is printed on stdout (`Site published on <url>`).
+
+## Member login on a **non-Astro** frontend — register the callback URI (post-release)
+
+**Only when the run has member login on a non-Astro SPA/static frontend using the Wix login page** (`inline-recipes/how-to-code-members-non-astro.md` — the `getAuthUrl` → `/callback` handshake). Astro's built-in `/api/auth/*` callback shapes are auto-registered; a **non-Astro SPA's own callback path is not** — and **login stays dead (4xx on the login redirect) until you register it**. This is a genuine gap `wix release` does *not* close for you.
+
+- `release` auto-registers the deployed **origin** (`allowedRedirectDomains`) — that's the visitor-SDK/CORS surface (above). It does **not** register the member-login **callback URL** (`allowedRedirectUris`). These are two different fields; members needs **both**, and only the first is automatic.
+- **This is a post-release step** — the callback URL embeds the deployed origin, which is unknown until `release` prints it. Do it right after release, once the URL is known.
+- **⚠️ `allowedRedirectUris` IS writable via the API — do not conclude it's read-only/dashboard-only.** The `UpdateOAuthApp` reference may not list it among the obvious updatable fields, but a masked `PATCH` sets it. The trap is a **required field mask**: without `mask.paths` the `PATCH` returns `200` and **silently no-ops**.
+
+```bash
+ID="<clientId>"   # the OAuth app id == the public clientId
+# 1) GET first and append — the PATCH REPLACES the array, so include what's already there:
+curl -sS -w "\nHTTP_STATUS:%{http_code}" https://www.wixapis.com/oauth-app/v1/oauth-apps/$ID \
+  -H "Authorization: Bearer $TOKEN"
+# 2) PATCH with the field mask (register BOTH the exact callback and the versioned-preview wildcard):
+curl -sS -X PATCH https://www.wixapis.com/oauth-app/v1/oauth-apps/$ID \
+  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
+  -w "\nHTTP_STATUS:%{http_code}" -d '{
+    "oAuthApp": { "id": "'"$ID"'",
+      "allowedRedirectUris": [ <existing…>, "https://<host>/callback", "https://*-<host>/callback" ] },
+    "mask": { "paths": ["allowedRedirectUris"] }
+  }'
+```
+
+- Include **both** the exact URL **and** the `https://*-<host>/…` wildcard — Wix serves versioned preview subdomains. The callback path must match the recipe's `redirectUri` **exactly** (e.g. `window.location.origin + '/callback'`).
+- `allowedRedirectDomains` and `allowedRedirectUris` can go in **one** `PATCH` (list both under `mask.paths`) if you ever need to set the origin by hand too.
+- **If you're not the one deploying**, you can't know the domain — flag the member-login callback URI to the user to register, and note **login is dead until they do** (higher-stakes than the origin flag).
+
+> **Custom-login** (`how-to-code-members-custom-login.md`) does **not** need this — `register`/`login` are direct API calls with no login-page redirect. Only `sendPasswordResetEmail`'s `redirectUri` and logout's return URL need allow-listing there.
+
+## Static frontends (no build step)
+
+These two fixes are **Wix-hosting facts** — they apply to a connected **static** site (plain HTML, no bundler) on the managed path, and the docs are silent on both. A bundler SPA that builds to its own output directory doesn't need them.
+
+- **The entry file must be named `index.html`.** Wix serves `index.html` at the site root. A brought-in design named anything else (e.g. `"My Design.html"`) **publishes "successfully" but 500s/404s at runtime**. Rename the entry to `index.html` **before** release and fix internal references to it.
+- **`site.outputDirectory` must point at the directory holding `index.html`.** `init` writes `site.outputDirectory: "./dist"`, which assumes an SPA that *builds* to `dist`. A static site has no build, so `./dist` is wrong — set `outputDirectory` in `wix.config.json` to the directory that actually contains `index.html`, or `release` publishes but the live site 404s at root.
+
+## Transient errors
+
+A release can hit transient infrastructure errors (`ECONNRESET`, `ETIMEDOUT`, `STATE_MISMATCH`, "try again shortly"). Retry the release serially up to **3×** with a short backoff. **Build failures are not retryable** — they're code bugs; fix the code, not the retry.
+
+That's the whole of finalize for `managed` — no `site-publisher` call, and no `oauth-app` **origin** PATCH (the origin is auto-registered). The **one** exception is the member-login callback on a non-Astro frontend above — that `allowedRedirectUris` PATCH is manual and required.