@wix/agent-skills 1.36.0 → 1.36.1

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

@@ -1,136 +0,0 @@
----
-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 (0-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 0: Configure the business location address
-
-**Set a real street address on the site's default business location.** The reservation location **is** the site's business location (same entity — the reservation location's `location` object is the business `Location`), and a fresh site provisions it with an **empty street address**. A complete restaurant site needs a real address: it's where guests come, it's what the reservation/experience surface and the Business Manager show, and it's the **same** location online ordering requires (so a site with both ordering and reservations does this once). Set it via the **Locations API** — `PUT https://www.wixapis.com/locations/v1/locations/<id>` (Update Location). Docs: <https://dev.wix.com/docs/api-reference/business-management/locations/introduction.md>.
-
-```bash
-# 1) find the default location + its revision
-curl -sS <AUTH> -X GET "https://www.wixapis.com/locations/v1/locations"   # take the entry with "default": true
-# 2) overwrite it with a real address (FULL override — send the whole object)
-curl -sS <AUTH> -X PUT "https://www.wixapis.com/locations/v1/locations/<id>" \
-  -d '{ "location": {
-    "id": "<id>", "revision": "<revision>", "default": true,
-    "name": "<Business name>", "timeZone": "Europe/Paris",
-    "address": { "country": "FR", "subdivision": "FR-75", "city": "Paris", "postalCode": "75001",
-      "streetAddress": { "number": "18", "name": "Rue des Lumières" },
-      "formattedAddress": "18 Rue des Lumières, 75001 Paris, France" } } }'
-```
-
-**⚠️ Earned gotchas (identical to `setup-restaurant-orders.md` STEP 0 — the same call):** Update Location is a **full override**, not a partial update (a "just the address" body is the classic *"reported success, nothing changed"* failure); **echo `"default": true`** or it 400s `CHANGE_DEFAULT_FORBIDDEN`; **`revision` is mandatory**; **`country` is a 2-letter ISO code**. The address also propagates to Site Properties. **Where the address comes from:** the request; if the brief names none, set a clearly-marked placeholder and **flag in the handoff that the owner must set their real address**.
-
-### 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

@@ -1,152 +0,0 @@
----
-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). **Only remove the menu when it's obviously the install's own default "Dinner Menu" on a fresh install.** Do **not** assume an existing menu is a sample: the site may already hold the owner's **real menu** (a connect/iterate run, or an owner-populated site). If what's there isn't obviously install sample data, or you're unsure, **do not delete it — ask the user first** (`SEED.md`: seeding is additive; deleting real content needs the owner's approval). When it clearly is the install's sample, remove it **before** creating yours so the storefront shows only the intended menu (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

@@ -1,71 +0,0 @@
-# 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
-
-### Secret boundary — mandatory
-
-Never read authentication material or tokens into agent context.
-Never emit them to stdout, stderr, logs, prompts, or tool results.
-
-```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. A foreground command that exits in seconds, one JSON event per line:
-
-```bash
-node ../../scripts/bootstrap.mjs   # path relative to this file
-```
-
-| Event | Do |
-|---|---|
-| `logged_in` | Session exists — continue. |
-| `awaiting_user` (`verificationUri`, `userCode`, `message`) | Send `message` verbatim, then stop. Re-run the script when the user says they're done → `logged_in`. Re-running early returns the **same** code, not a new one. |
-| `cli_unreachable` / `login_failed` (`detail`) | Show `detail` and stop. |
-
-### What the script does
-
-Read `../../scripts/bootstrap.mjs` if you want to see it: it sets `AI_AGENT` so the CLI emits JSON events instead of an interactive TUI, starts `wix login` detached with its output in a file under the OS temp dir (a pipe would die with the parent), and prints the device code. It is the one login path; there is no manual variant. Codes last ~10 min; after that, run it again and surface the new code.
-
-## 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

@@ -1,74 +0,0 @@
-# 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 (the Dynamic Context call in `DISCOVERY.md` §1 reports them in one call), 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) and **both links — the live site URL and the site dashboard `https://manage.wix.com/dashboard/<SITE_ID>`** (see `managed/DEPLOYMENT.md` § "Give the user both links"; `<SITE_ID>` is the `siteId` in scratch), then run the feedback checkpoint (`managed/DEPLOYMENT.md` § "Before you sign off").

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

@@ -1,149 +0,0 @@
-# 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).
-
-**If the user didn't specify their own design direction** (no palette, no theme/style words, no
-reference site, no brand guidelines), **decide the run's design tokens per `references/DESIGN.md`**
-before writing any component — theme polarity, a 2–4 color palette, type scale, radius/spacing — and
-hold them for reuse across every page and the themed-block fallback (`IMAGE_GENERATION.md`). If the
-user *did* specify a direction, use theirs instead — `DESIGN.md` is a fallback, not a checklist to
-enforce over an explicit ask. Either way, `DESIGN.md` §3's accessibility floor (WCAG 2.2 AA contrast,
-16px/1.5 body type) always applies — a page that fails it isn't done yet, regardless of whose palette
-it's using.
-
-**For page copy:** if the user didn't supply their own copy or voice direction, write hero/section
-headlines, kickers, subtitles, and CTA labels per **`references/CONTENT.md`** — otherwise use theirs.
-Either way, `CONTENT.md` §1 (the business's category must read literally above the fold) always holds —
-a page a first-time visitor can't identify isn't done yet, regardless of voice.
-
-**If a loaded vertical ships an experience overlay** — `references/inline-recipes/experience-<vertical>.md`
-(today: `experience-store.md`, `experience-donations.md`) — read it after `DESIGN.md`/`CONTENT.md`. It carries that vertical's own
-design and copy bar (what its surfaces must show, how to derive the direction from its content); the
-general files stay the floor.
-
-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) and **both links — the live site URL and the site dashboard `https://manage.wix.com/dashboard/<SITE_ID>`** (see `managed/DEPLOYMENT.md` § "Give the user both links"; `<SITE_ID>` is the `siteId` in scratch), then run the feedback checkpoint (`managed/DEPLOYMENT.md` § "Before you sign off").