@wix/agent-skills 1.36.0 → 1.36.1

package/skills/wix-headless/references/FEEDBACK.md

@@ -1,129 +0,0 @@
-# Feedback — relay the user's building-with-Wix experience to Wix
-
-A tiny, optional capability: send the **user's** feedback about the experience of *building with
-Wix* to Wix, attributed to the authenticated user. Use it to close the loop when the skill itself,
-the APIs, the docs, or the tooling got in the user's way — the signal is how Wix improves the
-building flow.
-
-This is **not** support, and not for the user's own site content. It is meta-feedback about
-*building with Wix*.
-
-## When to offer it (user-approved only — never auto-send)
-
-Sending is always the user's call, but **offering is not** — default to offering, don't wait to be
-asked or for the user to complain first. Offer once, in plain prose, in any of these situations; send
-only after an explicit yes:
-
-- The user **explicitly asks** to send feedback / report something to Wix ("tell Wix that…", "report
-  this", "send feedback"). Then just confirm the wording and send.
-- The user **complains, is frustrated, or reports a Wix bug** in the course of the work ("this API is
-  broken", "the docs are wrong", "why is this so hard"). Acknowledge, then offer to pass it on.
-- **The run hit any real friction** — not just repeated failures. A single confusing error, a doc
-  that was wrong/stale/missing, an extra round trip you had to make, a workaround you had to invent,
-  or anything that cost more turns than it should have all qualify — it doesn't need to have happened
-  more than once. When you notice it, offer in the moment: *"That [error/doc gap] tripped us up —
-  want me to send it to Wix as feedback?"*
-- **At the natural end of every run** (deployment/handoff, or wherever the skill's flow closes out),
-  do a deliberate self-check over the whole session even if nothing felt dramatic at the time — friction
-  you shrugged off or silently retried past is still signal. If the self-check turns up anything,
-  offer before you sign off rather than letting the run end without asking.
-
-Bias toward offering over staying quiet: a redundant offer costs the user one "no thanks"; a friction
-point that goes unreported is a signal Wix never gets. Only skip the offer when the run was genuinely
-clean end to end.
-
-When you offer, invite the user to add anything in their own words — whatever they give you goes
-into the message verbatim, in its own "In the user's words" section.
-
-Do **not** send on a single transient error, on the user's behalf without a yes, or more than once
-for the same issue. When unsure, ask rather than send.
-
-## Compose a useful message
-
-Wix receives only free text, so a bare sentence is low-signal. Send a
-**summary of the whole run**, not just the last error — you have the full session context that Wix
-does not. Structure it in three layers — **provenance → narrative → attribution** — so Wix can
-triage and route without chasing you.
-
-**1. Provenance** — labelled lines. A starting point, not a schema: omit lines that don't apply,
-add any field or value that would help Wix understand the run:
-
-```
-Agent / model: <e.g. Claude Code · Opus, Cursor, … / whatever you are>
-Wix tooling used: <MCP tools, Wix CLI, REST via curl, … or other/none>
-Platform / hosting: <headless, Velo, Wix-hosted, self-hosted, …>
-Wix areas / APIs: <account & site management, CMS, media, auth, … — whatever the run touched>
-Wix products: <stores, bookings, events, blog, … or none — plain API work is a valid answer>
-Project type / frontend: <managed | self-managed | stripe | other> · <Astro, Next.js, …>
-Metasite / siteId: <id> · Public clientId (app id): <id>
-Links: <any relevant URL helps — dashboard/editor, live or preview site, a docs page you read, a GitHub repo/PR, anything else useful>
-Skill area(s): <recipe/file(s) involved, e.g. inline-recipes/setup-bookings.md STEP 5>
-Other ids: <service / product / checkout / etc. ids created this run, as relevant>
-```
-
-**2. Narrative:**
-
-- **In the user's words** — anything the user added when you offered, quoted verbatim (redact
-  secrets only). Skip the section if they added nothing.
-- **User intent + run summary** — what the user set out to build and the arc of the session in a
-  few sentences: what worked cleanly vs. what fought back.
-- **Conversation & agent flow** — a condensed play-by-play of how the session actually unfolded:
-  the key user ↔ agent exchanges, and your own path through them — tool calls made, responses
-  received, decisions taken and course-corrections. Distilled, not a transcript dump — enough for
-  Wix to replay the flow.
-- **Friction points** — the heart of it. Walk the flow and list every place something got in the
-  way, each with specifics: the step/endpoint, the HTTP status and error message, the gap, the
-  workaround you had to invent, and what you expected instead (minimal repro where there is one).
-  Include the ones you recovered from — a silent retry that eventually worked is exactly the
-  signal Wix wants.
-
-**3. Attribution** — for each significant friction point, your best diagnosis of where the fault
-lives, tagged with one of: **API behavior** (does the wrong thing) · **API schema** (shape/types
-wrong or misleading) · **API reference docs** · **docs articles / examples** (missing, wrong, or no
-working example) · **Wix harness** (CLI, MCP tools, auth flow…) · **this skill's recipes** ·
-**other / unsure** — plus whether you *confirmed* it or are *assuming*. Don't force a tag; a wrong
-route is worse than "unsure".
-
-**Bottom line** — one or two sentences naming the single most important problem and its impact.
-Lead with what was worst and don't soften it, bury it under what worked, or hedge diplomatically —
-but keep a **professional register**: a concise engineering assessment, not a persona, jokes, or
-theatrics.
-
-Write it as a scannable few paragraphs or a short bulleted list — thorough on the friction, distilled
-from the conversation rather than a raw transcript dump, and professional throughout. Confirm the
-final wording with the user before sending. **Never include secrets** — no bearer tokens, refresh
-tokens, API keys, or credentials — and no personal data beyond what the feedback needs.
-
-## Send it
-
-This call identifies **you** (the human account), so it needs a **user-scoped** bearer — mint it
-with the bare command: `npx @wix/cli@latest token`. The site-scoped bearer `AUTHENTICATION.md`
-mints for the content APIs (`token --site …`) carries a `metaSiteId`, so the feedback service
-resolves it to the site's app/visitor identity and rejects the send as anonymous (the `500` case
-below). Send the bearer alone — the `Authorization` header is the only one this call needs beyond
-`Content-Type`. If the CLI isn't logged in yet (e.g. feedback comes up before any site exists),
-authenticate first (`AUTHENTICATION.md` §1), then run `token`.
-
-```bash
-TOKEN=$(npx @wix/cli@latest token)   # bare token command → user-scoped bearer
-curl -sS -w "\nHTTP_STATUS:%{http_code}" \
-  -X POST "https://www.wixapis.com/mcp-serverless/v1/headless-feedback" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"message":"<composed feedback>"}'
-```
-
-- **Success = `HTTP_STATUS:200`** with an empty body `{}`. Tell the user it was sent.
-- **`500` `"Unable to determine target user id, anonymous messages are not allowed"`** — the token
-  was site-scoped. Re-mint user-scoped (`npx @wix/cli@latest token`, bare) and retry once.
-- **`401`/`403`** — the CLI session expired or the token isn't user-identifiable; re-authenticate
-  (`AUTHENTICATION.md` §1), re-mint user-scoped, retry once. If it still fails, surface the response
-  and stop — do not loop.
-
-## Hard rules
-
-- ✅ Offer proactively whenever the run warrants it; send only after an explicit user yes.
-- ✅ One submission per issue; never spam with retries or duplicates.
-- ✅ Compose a specific, factual message; confirm the wording first.
-- ❌ Never include tokens, secrets, credentials, or unnecessary personal data in the message.
-- ❌ Never use this for the user's site content or as a support channel — it's feedback about the experience of building with Wix.

package/skills/wix-headless/references/IMAGE_GENERATION.md

@@ -1,80 +0,0 @@
-# Image generation (opt-in, all project types)
-
-A single reusable capability: generate an image with **Wix AI (Runware)** via the `wixapis.com` proxy, import it into Wix Media, and attach it where it's needed. **Opt-in** — only runs when `imagery` is on (resolved in `DISCOVERY.md`; default off → text-only). It's **agnostic to the project type**: it uses `$TOKEN`/`$SITE_ID` from the provided authentication mechanism, exactly like every other call.
-
-Use it **intelligently, by need** — there's no fixed slot list:
-- **Entity images** — during Seed, attach images to seeded image-bearing entities (e.g. stores products, blog covers, CMS items, bookings services, restaurant items, portfolio projects + collection covers, event heroes — illustrative, not a write-shape index; each capability's recipe pins its own attach shape, see §3). **Attaching the generated image to the entity is a required second step** — a seeder creates the entity in pass 1 (text-first), then a pass-2 update/patch writes the image onto it. An entity is not "done" until its image is attached (or the attach is skipped because imagery is off / it failed — then it stays text-only, which is fine).
-- **Contextual / decorative images** — when the skill is building a frontend (the create/connect flows) and the agent or user decides a surface needs one (e.g. a homepage hero, an about-section visual). Generate only what the page actually uses, up to the per-run `imageCap` (`DISCOVERY.md` §4); a slot over the cap or off gets the **themed-block fallback** (below), not an empty gap.
-
-## 1 · Generate
-
-```
-POST https://www.wixapis.com/runwareschemaless/v1/request
-body: [
-  { "taskType": "imageInference", "taskUUID": "<UUIDv4>", "outputType": "URL",
-    "outputFormat": "PNG", "positivePrompt": "<prompt>",
-    "width": 1024, "height": 1024, "model": "google:4@2", "numberResults": 1 }
-]
-```
-
-Auth: the universal call shape (`Authorization: Bearer $TOKEN`, `wix-site-id: $SITE_ID`, `Content-Type: application/json`). Extract `data[0].imageURL` (short-lived — import it immediately).
-
-- **`taskUUID`** must be a real UUIDv4 (`uuidgen`); slugs return `400 invalidTaskUUID`.
-- **Allowed dimensions** (per model): `1024×1024` (square — products, squares), `1376×768` (16:9 — heroes/banners), `1200×896` (4:3 — editorial). Free-form sizes 400.
-- **Forbidden for `google:4@2`**: `steps`, `CFGScale` (→ `400 unsupportedParameter`). Alternatives if it keeps failing: `bfl:5@1`, `runware:400@1`.
-
-### Batching
-- **`google:4@2`** times out (`504`) when one request bundles **N≥3** tasks. Fire **N parallel 1-task requests** as concurrent sibling `curl` calls in a single batch — never N≥3 tasks in one body, never sequential one-per-turn.
-- **`bfl:5@1` / `runware:400@1`** can batch multiple tasks in one request body.
-
-## 2 · Import to Wix Media
-
-```
-POST https://www.wixapis.com/site-media/v1/files/import
-body: { "url": "<imageURL from generate>", "mimeType": "image/png", "displayName": "<name>.png" }
-```
-
-Keep two values from the `file` object: **`file.url`** (the full permanent `wixstatic.com` URL) and **`file.id`** (the WixMedia file id, e.g. `<hash>~mv2.jpg`). Some entities bind by url, others by id — **which one a given entity uses is the recipe's concern** (§3), not this common section's. (The import response has **no `fileUrl` field** — the id is `file.id`.)
-
-**Importing several images? Use one bulk call, not N singles** — `POST https://www.wixapis.com/site-media/v1/bulk/files/import-v2` (≤100 per call):
-
-```
-body: { "importFileRequests": [ { "url": "<imageURL>", "mimeType": "image/png", "displayName": "<name>.png" }, … ] }
-```
-
-Response is `{ "results": [ { "itemMetadata": { "originalIndex", "success" }, "item": { "url", "id", … } } ] }` — read each hit's **`item.url`** / **`item.id`** (same values as the single import's `file.url` / `file.id`) and its `itemMetadata.success`.
-
-## 3 · Attach (by entity type)
-
-The pass-2 **write shape is per-entity earned knowledge and lives in each capability's seed recipe** — right next to the create shape the seeder already reads (`inline-recipes/setup-<capability>.md`). **That recipe is authoritative** — read the exact shape there (field paths, any required companion fields, silent-drop warnings, confirm-by-requery), not here. This section is navigation only and carries no shapes:
-
-| Entity | Recipe | Section |
-|---|---|---|
-| Store product | `setup-online-store.md` | **Attach images** |
-| Blog post cover | `setup-blog.md` | **Attach images** |
-| CMS item | `setup-cms.md` | **Attach images** |
-| Bookings service | `setup-bookings.md` | **Attach images** |
-| Rental service | `setup-rentals.md` | **Attach images** |
-| Portfolio project / collection | `setup-portfolio.md` | **Attach images** (cover + gallery) |
-| Restaurant menu item | `setup-restaurants.md` | **Attach images** |
-| Event hero (`mainImage`) | `setup-events.md` | **Attach images** |
-| *(any entity whose recipe doesn't pin one)* | — | discover live via `DOC_DISCOVERY.md` |
-
-- **Frontend** (when building a site) — drop `file.url` into the `<img src>` / CSS `background-image` of the page being built.
-
-## Prompts
-
-Brand-contextual, never generic. Include: subject; the brand aesthetic/mood; the palette (real tones, e.g. "warm cream and forest green"); style/lighting; and always **"no text, no watermarks"** (AI-rendered text is garbled). Pull context from the brand + the entity (product name/description, post topic, page purpose).
-
-**At least one image per page must show the real subject of the business** — the actual service/product/space, not just abstract or decorative art; decorative visuals layer in *addition* to that, never *instead of* it (`CONTENT.md` § Images has the full rule + the fillable-slot fallback for when only the user's own real photos will do).
-
-## Credits, cost & the not-generating fallback
-
-Each generated image costs **1 Wix AI credit**, billed at the account level regardless of project type (the account behind the metasite must have credits). Volume is bounded in `DISCOVERY.md` §4 — carry those two values through:
-
-- **Cost is surfaced** — the pre-work line states the plan in credits (*"~N images ≈ N credits"*). Keep the running count honest with that estimate.
-- **Honor the per-run `imageCap`** (default ~12, from Discovery). Generate up to the cap by priority (hero/most-visible surfaces first); **beyond the cap, don't generate — render the themed-block fallback** and log what was capped. Never silently exceed the cap on a "throughout"-style phrase.
-
-**Themed-block fallback (the not-generating path).** Whenever a **frontend** image isn't generated — imagery off, over the cap, declined, or a generation failure — render a **styled `div` that follows the site's design tokens** (palette, radius, spacing, an optional label/gradient) in the slot, never an empty gap or a broken `<img>`. It's deterministic, needs no input, never hangs — so it's the safe default for any non-interactive run and keeps the layout on-brand at zero credits. (A *seeded backend entity* with no image just stays text-only — there's no div to render server-side; `SEED.md` § "Entity images".)
-
-**Never block the run on image failure**: on `unsupportedParameter`/`unsupportedDimensions` fix and retry once; on model/5xx/credit-exhaustion, **skip that image and continue** — a frontend slot falls back to a themed block, a seeded entity stays text-only (the user can add their own later).

package/skills/wix-headless/references/SDK_HANDOFF.md

@@ -1,108 +0,0 @@
-# SDK-integration handoff
-
-**This is the last step — reach it only after Setup and Seed have run.** The guide below is filled from the `seeded` map (created IDs), which exists only because Seed executed; if you're here without having installed the apps and seeded content, go back and do that first. The guide *describes* the backend the earlier steps built.
-
-The skill **returns this document** describing how to call Wix from the frontend, then **exits**. The host agent — which owns the frontend, the framework, and the build — does the wiring. We describe what to use and **link to the live Wix SDK docs for the API shapes**; the host decides where they go.
-
-> **Link to the docs for API shapes; don't inline examples.** The Wix SDK docs are versioned and complete; hand-written snippets under-specify the hard parts (rich-content rendering, package versions, types) and lead the host to build against a wrong shape. The handoff supplies what the docs can't: the **seeded IDs**, the **`clientId` source**, and the **package set**. The package set is the **inlined map in §3** — the SDK doc `.md` pages don't surface the `@wix/*` import string to navigation, so the map is the source of truth for *which* packages; the **inline recipe** each row points to is the source of truth for *how* to call them (current API shape + version).
->
-> **The linked docs are the source of truth for current API shapes and versions — read them for the integration. Existing code (in this or any other project) is not a substitute: it may target a different SDK version and silently mislead.**
-
-Emit the document as the skill's final message (a Markdown block the host can act on or save). Fill it from the run's `verticals[]`, the `seeded` map, the OAuth app's public `clientId`, and — for each loaded capability — its **Required site features** and **Implementation checklist** from `references/CAPABILITIES.md` (§6). Include **only** the loaded capabilities. The guide isn't just "here are the IDs and packages"; it's the spec for a *complete* site, so the host builds real features (author, comments, dates…) rather than a bare data dump.
-
-## What the document contains
-
-### 1 · Packages to install
-The always-on package is **`@wix/sdk`** (provides `createClient` + `OAuthStrategy`). Add the union of the loaded capabilities' runtime packages from the **map in §3**. **Runtime packages only** (no scaffold/build deps). For install details and current versions, link: <https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/install-sdk-packages.md>.
-
-### 2 · Client setup (and the clientId source)
-With a **manual client** the frontend authenticates as an **anonymous visitor** via `OAuthStrategy`, with `clientId` = the OAuth app's **public client id**. This is the model for **host-owned** frontends (this guide is emitted) and the skill's **non-Astro** path (`references/non-astro.md`). **Managed-Astro is the exception** — it auto-authenticates with **no client at all** (`references/astro.md`); skip this section's `clientId` wiring there. Two facts hold whenever a client *is* used: the `clientId` is **not secret** (it's the public OAuth id), and the **`client_secret` never reaches the frontend.** Two type-independent steps:
-
-1. **Obtain the `clientId`** via the provided authentication mechanism — **see `<TYPE_DIR>/AUTHENTICATION.md`** (each type names where the public id comes from; don't re-mint or re-fetch it if the type already provides it).
-2. **Get the `clientId` into the client bundle** — this depends on **who owns the frontend**, not on the project type:
-   - **The host owns the frontend** (this guide is *emitted* — backend-only: self-managed, stripe, or managed backend-only) → the host exposes the value to client code via its framework's public-env convention (`NEXT_PUBLIC_*`, `VITE_*`, `PUBLIC_*`, …).
-   - **The skill owns the frontend** (this guide is *applied* — managed create/connect) → **how the frontend authenticates is framework-specific, so follow the frontend reference, not this bullet.** On **Astro** (the default) authentication is automatic — there is **no client and no `clientId` to wire** (`references/astro.md`). On a **non-Astro** frontend you build a manual client (`references/non-astro.md`): wire the `clientId` in via the framework's public-env convention if one exists, otherwise inline the public id into the client code/bundle.
-
-For the current `createClient` + auth-strategy shape, link:
-- <https://dev.wix.com/docs/sdk/articles/set-up-a-client.md>
-- <https://dev.wix.com/docs/sdk/articles/set-up-a-client/authorization-strategies.md>
-
-> **Confirm the `clientId` reached the built bundle before deploying.** Public-env wiring fails silently — a mis-wired public var inlines as `undefined`, and then *every* visitor token call from the live site 400s with no other clue. After the production build, verify the **actual `clientId` value** is present in the built output (check that the value resolves — not merely that the variable *name* appears somewhere). Doing this pre-deploy stops it from being mistaken for an origin/CORS problem afterward.
-
-### 3 · Per-capability packages + API docs (package from the map; recipe for shapes)
-For each loaded capability, give the host the **package(s)** from the map below and point it at the capability's **inline recipe** (`references/inline-recipes/how-to-code-*.md`) — the pinned API shape, methods, version, and failure modes live there; don't re-summarize them here. The map is the source of truth for *which* packages; the recipe is the source of truth for *how* to call them. **The recipes are local — Read them with the file tool, don't curl.**
-
-Before implementing a capability, Read the local recipe linked in its row.
-
-| Capability | Package(s) | Required recipe |
-|---|---|---|
-| donations | `@wix/donations` + `@wix/ecom` + `@wix/redirects` | `how-to-code-donations.md` — campaign reads, numeric donation options, Cart V2 → hosted redirect, diagnostics and anonymous verification; follow its shared experience reference. |
-| stores | `@wix/stores` + `@wix/categories` (+ `@wix/ecom`, `@wix/redirects` for cart/checkout) | `how-to-code-a-store.md` — Catalog V3 gallery (sort/filter/paging), product page (variants, prices, ribbons), Cart V2 + checkout, and what a complete storefront shows. |
-| blog | `@wix/blog` (+ `@wix/ricos` to render `richContent`; **`@wix/comments` + `@wix/members`** when the blog has comments/members; `@wix/blog` `likes` when the site has members) | `how-to-code-a-blog.md` — Blog V3 read/render + member features (likes, comments). Supplement: <https://dev.wix.com/docs/sdk/business-solutions/blog.md>. |
-| cms | `@wix/data` | `how-to-code-cms.md` — `items.query` read contract. |
-| forms | `@wix/forms` | `how-to-code-forms.md` — schema-driven render (read the live form schema, visitor token/no elevate) + Form Submissions v4 write contract. |
-| events | `@wix/events` (+ `@wix/redirects` for the ticketed hosted-checkout redirect) | `how-to-code-events.md` — Events V3 read + the `TICKETING`-vs-`RSVP` branch. |
-| bookings | `@wix/bookings` (+ `@wix/auto_sdk_ecom_cart-v-2`, `@wix/redirects` for the cart/checkout that holds the seat; `@wix/forms` for the schema-driven booking form) | `how-to-code-bookings.md` — Services V2 read + `createBooking → ecom Cart V2 → checkout-or-place`. |
-| rentals | **`@wix/bookings`** — the same package set as bookings (`@wix/auto_sdk_ecom_cart-v-2`, `@wix/redirects`, `@wix/forms`). **There is NO `@wix/rentals` package** and its absence is not a missing capability: Wix Rentals ships no APIs of its own and runs on the Bookings APIs with rentals-specific field values. Never report rentals as "not buildable headlessly". | `how-to-code-rentals.md` — a **delta** on `how-to-code-bookings.md`: filter the catalog by the rentals `appId` (`ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e`), two-call hourly availability (start slots → end options), the consecutive-day walk for daily, duration-based `previewPrice`, then the **unchanged** booking/cart/checkout sequence carrying the rentals `appId` on `catalogReference`. |
-| pricing-plans | `@wix/pricing-plans` (+ `@wix/members` — login is a hard dep; and for the Bookings-membership integration `@wix/bookings` + `@wix/ecom` (+ `@wix/redirects`)). **Use `@wix/pricing-plans`, NOT the Wix-site `@wix/site-pricing-plans` (`startOnlinePurchase` is site page-code, not headless).** | `how-to-code-pricing-plans.md` — Plans V3 grid + login-gated order/subscribe + book-with-membership. |
-| restaurants | `@wix/restaurants` (menu display — **no `@wix/ecom`** unless online ordering is in the run; reservations are a separate app) | `how-to-code-restaurants.md` — Menus V1 display-only read. |
-| restaurants — online ordering (add-on; only when the Orders app is in the run) | add `@wix/ecom` + `@wix/redirects` to the row above | `how-to-code-restaurant-orders.md` — ordering cart/checkout on top of the menu display. |
-| portfolio | `@wix/portfolio` (+ `media` from `@wix/sdk` to resolve image strings; **no** `@wix/ecom`/`@wix/redirects` — display-only) | `how-to-code-portfolio.md` — Portfolio v1 display-only read. |
-| restaurants — table reservations (add-on; only when the Table Reservations app is in the run) | `@wix/table-reservations` (a **distinct** package from `@wix/restaurants`; **no ecom/redirects** — a reservation is a hold, not a purchase) | `how-to-code-restaurant-reservations.md` — book-a-table hold→reserve. |
-| restaurants — experiences (add-on; special dining occasions guests reserve — chef's table, tasting menu) | `@wix/table-reservations` (same package; the **`experiences`** namespace + `timeSlots`/`reservations`) | `how-to-code-restaurant-reservations.md` — "Booking an experience" (query experiences → scheduled slots → reserve with `experienceId`). |
-
-> **Cross-cutting packages** (`CAPABILITIES.md` § "Cross-cutting capabilities"): these aren't per-vertical rows but get added to the package list when the run used them. If **coupons** were seeded, add `@wix/marketing`. The eCommerce checkout packages (`@wix/ecom`, `@wix/redirects`) are already folded into the stores row above — include them once when any purchase-flow vertical is present.
-
-> **members (cross-cutting — add when the site has login / account / gated content, or whenever pricing-plans is loaded).** Package: **`@wix/members`** (current member / profile via `getCurrentMember` — **not** the dev-preview `@wix/site-members`); auth is the `OAuthStrategy`/session methods on the always-on **`@wix/sdk`**. **The API shape lives in the axis recipe — Read the one that matches the frontend, not both:** `how-to-code-members-astro.md` (Astro: built-in `/api/auth/login` + `/api/auth/logout`, no client) or `how-to-code-members-non-astro.md` (non-Astro: manual `OAuthStrategy` handshake). Both are the **Wix-hosted login page** (the default). **Only if the brief explicitly asks for a custom/branded login form or custom sign-up fields**, Read `how-to-code-members-custom-login.md` instead — the surface is chosen by intent, not by project type.
-
-> **Why a map and not navigation:** the SDK doc `.md` pages don't expose the `@wix/*` import string to a reader (it's only in the page's interactive UI), so the package column is inlined here as the source of truth. If a package name ever drifts, reconcile it against the SDK install article (§1) — not by guessing from the module URL. The linked pages remain authoritative for the API itself.
-
-### 4 · Seeded schema (what the host binds to — names + field keys, not content IDs)
-The host binds to **schema**, not to a frozen list of content IDs. **Content is discovered live**: every listing is a query-all (`queryProducts`/`queryPosts`/`queryEvents`/`queryServices`/`queryPlans`/`items.query`/`listMenus`…), every detail page resolves a `[slug]`/`[...slug]` route from the URL at request time (the frontend is SSR — no `getStaticPaths`), and category/nav is a live query. So the frontend never needs the seeded per-item id/slug arrays — and **not carrying them is deliberate**: an id the host was never handed is an id it can't hardcode, so content the owner adds later in the backoffice flows through by construction (see §6).
-
-Carry only the **structural** carve-outs the coding step genuinely reads — the collection/form *names and keys* you must know to query and bind, which do **not** change when an owner adds a row:
-- **cms:** `collectionId` + field keys per collection
-- **forms:** `formId` + each form's field `target` keys (the submission keys the frontend binds `name` = target). Field set, labels, options, and validation (`required`, format, length/pattern) are read live from the schema (`how-to-code-forms.md`).
-
-Everything else the host resolves live from the queries in §3. (Static platform constants — Stores/Bookings app IDs, the Blog appDefId — and the public `clientId` are needed too, but they're identical for every site, not seed output; they're in §2/§3.)
-
-### 5 · Integration notes (headless-auth specifics the per-module docs won't frame)
-- **Restaurants online ordering has real-world go-live preconditions the code can't satisfy — surface them to the owner.** For a working ordering flow the site needs: **(1) a business location with a real address** (the skill sets this in `setup-restaurant-orders.md` STEP 0 — but if the brief gave no address, a placeholder was used and the owner MUST replace it, or checkout stays "testing only"); **(2) a premium plan**; **(3) a configured payment method**. State these plainly in the guide/summary — the site is not "done" for real orders until the owner completes them. (The same premium+payment note applies to any eCommerce checkout, e.g. stores.)
-- The visitor token has **no per-user identity** → seeded **CMS collections are public/shared** across all visitors (not per-user, not cross-device). Per-user storage needs member auth.
-- Frontend CMS access is **read**; visitor writes go through **Forms** submissions.
-- **Blog comments are member-gated — read public, write authenticated.** Querying/rendering comments is public, so list them server-side in SSR. **Submitting** needs a logged-in member, so don't gate the form behind an upfront login check (that branch is what burns deliberation): render the form always and resolve identity at submit — POST to a backend endpoint (`src/pages/api/*.ts`) that calls `createComment` with the request session; if the caller isn't a member, redirect to the built-in `/api/auth/login?returnUrl=…`. **Do not build the comment form as a client island** — the API-endpoint + session path is the documented shape and avoids the browser-auth detour. The comment API keys (post `referenceId`, Blog appDefId, author lookup via `post.memberId`) are in `how-to-code-a-blog.md`.
-- **Member auth is one mechanism split on the frontend axis (the §3 members note routes to the right recipe), and orthogonal to elevation.** Sign-up and log-in are the *same* flow (the Wix login page logs in **or** registers); log-out is its inverse. Two layers stay separate: **identity** (logged-in vs not — no app install) vs **profile** (name/photo/roles — needs the **Wix Members Area app** installed, `SETUP.md`). **pricing-plans is a hard dependency**: subscribing requires a logged-in member; for the other verticals, member login is a soft add-on for their "my …" surfaces only. **A member reading their own data (own orders/bookings/subscriptions, plan-gated content) uses the member token with NO `auth.elevate`** — elevation is the separate admin/permission axis (site-wide reads, server-side only), not something member features need.
-- **Gating is a LIVE signal, never a hardcoded id list.** Whenever content is gated (members-only articles, plan-eligible class booking, any "premium" surface), decide eligibility from a signal read **at request time** — a queryable flag carried on the content (a `members-only` blog category/tag or a boolean CMS field) and live coverage/eligibility (Cart V2's `currentCartV2.calculateCurrentCart()` → `summary.paymentSummary.memberships`, or the member's active-order `planId`s matched against **live** Benefit-Program coverage). **Never** gate on a frozen set of "premium" slugs/ids or a seed-time `plan→service` map: a gated post or a newly-covered service the owner adds later would silently read as public/ineligible. See `how-to-code-a-blog.md` (member features) and `how-to-code-pricing-plans.md` (coverage read).
-
-### 6 · What a complete site must include (per loaded capability)
-When **donations** is loaded, carry the donor-experience reference linked in `how-to-code-donations.md`
-into the handoff. Distinguish anonymous API verification, hosted-checkout verification and an actual
-payment; do not claim one from another or omit the bounded donation handoff check.
-
-For each loaded capability, carry its **Required site features** and **Implementation checklist** from `references/CAPABILITIES.md` into the guide — in plain product language, lightly tailored to what was seeded. **This is the build spec, not optional polish:** the host should build every *required feature* and cover every *checklist* item. For example, a blog must show the **author** (name + photo), the publish date and reading time, the cover image, and the **full formatted content** (not flattened text) — a posts-list-plus-plain-text-body is incomplete. The host maps these onto its own components using the packages/docs in §3 and the seeded schema in §4.
-
-- State them as the *what* (product behaviour), not the *how* (no component code, no API calls) — the host owns the build.
-- **When a loaded vertical ships an experience overlay** (`references/inline-recipes/experience-<vertical>.md`; today `experience-store.md`, `experience-donations.md`), point the host at it alongside the checklist — it is that vertical's design and copy bar (surfaces, first-viewport rules, truthful copy), read after the general `DESIGN.md`/`CONTENT.md`.
-- If a *required feature* depends on backend support that **Seed** enabled (e.g., comments), note it's available so the host wires it. If Seed could **not** enable it, say so plainly rather than implying the site is complete.
-- **When pricing-plans is loaded, `login / account / gated content` is a *required* feature, not optional polish** — a plans grid with no way to log in and subscribe is incomplete (subscribing requires a member; §5 member-auth note). Point the host at the matching `how-to-code-members-*.md` recipe. For the other verticals, a "my …" surface (my orders / my bookings / my registrations) is a member-gated *enhancement* — list it only if the run's intent calls for an account view, and flag it needs the same login mechanism.
-- **Curation / hero / nav must come from a LIVE query, never a pinned slug/id.** A "featured" or "latest" item, a hero, and every nav/category bar must be driven by a query — "next upcoming" (`queryEvents` filtered to `UPCOMING`/`STARTED`, sorted by start date), "newest" (`queryPosts`), `queryCategories`, etc. — resolved at request time. A pinned "featured event" slug not only fails to rotate as the owner adds content, it can go **stale/past**. Even a **single-item** site (one event, one product) must drive its homepage from the *listing query*, not a hardcoded lone slug — so a second item the owner adds later surfaces automatically instead of staying invisible.
-- **State the residual limitation honestly — don't over-claim a "self-maintaining" site.** New **content** flows through live with no code change and no re-publish: a product, post, event, service, plan, menu item, or category the owner adds in the backoffice appears via the live queries above. **Forms are schema-driven, so an added/removed/relabelled form *field* of a supported input type (text/email/phone/url/textarea/dropdown) — or a tightened validation rule (`required`, `minLength`/`maxLength`/`pattern`, format) — also reflects live with no code change** (`how-to-code-forms.md`). But **new content *types / collections / ticket-tier semantics*, and a form field of a *novel type the renderer doesn't handle yet*, require a code change** — the frontend renders an authored schema, so a new CMS field, a new collection, a novel ticket structure, or an unsupported form field type won't render until coded. Say this plainly in the guide rather than implying the site maintains itself beyond that.
-- **Before finishing, verify nothing is pinned.** Confirm no route, listing, gate, or nav is filtered against a seed-time id/slug array held in code — every such filter must key off a **stable id used in a live query** (a `categoryId` from `queryCategories`, a `slug` from the URL/query result), not a frozen membership list. A pinned array is the one way owner-added content silently fails to appear.
-
-## How to navigate the Wix docs
-
-> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
-> - Pages are either content pages (article/reference text) or menu pages (a list of links to child pages).
-> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/business-solutions.md`).
-> - Top-level index of all portals: <https://dev.wix.com/docs/llms.txt>
-> - Full concatenated docs: <https://dev.wix.com/docs/llms-full.txt>
-> - **§3 points at a local inline recipe per capability — Read it first (first priority); it's already curated, so read it as-is rather than re-discovering the shape.** For a pinned SDK doc link (inside a recipe, or the blog supplement in §3), `curl` its `.md` directly.
-> - **`SearchWixSDKDocumentation` is second priority — for *discovering* a method the recipe doesn't pin, or when a menu hides the runtime functions.** Curling a module *menu* (e.g. `…/sdk/business-solutions/blog.md`) often surfaces only dashboard/extension pages, not the runtime query functions — `SearchWixSDKDocumentation "blog query posts"` returns the actual `posts.queryPosts`/`listPosts` shapes (with `?apiView=SDK` schema links) the menu doesn't expose.
-
-## After deploy: finalize per the project type
-
-The guide describes the backend; how the site is published and how its origin is allowed to call Wix depend on the project type. After deployment, **finalize per `<TYPE_DIR>/DEPLOYMENT.md`** — it carries the type-specific steps (and tells you whether anything is required of the user).
-
-## After emitting the document
-
-Once the guide is emitted and the deployment checklist is done — site published, origin registered (or the user has been flagged) — the skill's work is done. Close with a short plain-prose summary of what was set up (apps installed, content seeded per capability, site published, origin registered or pending). What happens with the guide — installing packages, wiring components, choosing a framework — is the host's to decide.

package/skills/wix-headless/references/SEED.md

@@ -1,74 +0,0 @@
-# Seed — create the backend content
-
-For each resolved capability, create the backend content its *what* names. This file carries **only the *what*** (entities, counts, policy) and points at each capability's **inline recipe** for the API *how*. **No endpoints, payloads, field templates, caps, or batching mechanics live here** — those are inlined in the per-capability recipe (`inline-recipes/setup-*.md`, mapped in §2); read them there.
-
-Use `$TOKEN` / `$SITE_ID` from the provided authentication mechanism (see `<TYPE_DIR>/AUTHENTICATION.md`). The capabilities are **independent** — no cross-capability ordering or shared data (**two exceptions:** (a) **pricing-plans depends on bookings' service IDs**, so seed bookings before pricing-plans; (b) **restaurants online ordering depends on the restaurants menu** — the ordering add-on binds each menu to an operation, so the menu must be seeded before ordering — both in §2). For each one: read its inline recipe (§1; §2 maps each capability to its `setup-*.md`), build the body from `intent.<cap>` + `brand`, execute against `wixapis.com` with the universal call shape (Bearer `$TOKEN` + `wix-site-id` — see `SETUP.md` §1), and collect the created IDs into a `seeded` map keyed by capability.
-
-> **Cleaning up install sample data is fine on a fresh install — but never delete real content without approval.** Some recipes start by removing the app install's **default sample/mock data** (e.g. a demo "Dinner Menu", a "My Portfolio" collection, sample products). That is safe **when you just installed the app and what's present is obviously the install's own sample/demo content**. But the site may already hold **real content** (an iterate/connect re-run, or a site the owner has populated) — if what's there isn't obviously install sample data, or you're unsure, **do not delete it: ask the user for approval first.** Seeding is otherwise **additive** — create the requested content alongside what's there; deleting or overwriting existing products / collections / menus / forms / projects / media is destructive and needs the user's explicit ask or approval.
-
-> **Concurrency is an optional optimization, never a requirement.** Seeding the capabilities **one after another always works** — that is the safe default, and an agent doing everything itself simply seeds each in turn. Because the capabilities are independent (above), **if** your runtime can run work concurrently you **may** seed several at the same time to save wall-clock. Treat this strictly as "you may," never "you must": a correct seed must never *depend* on parallelism.
->
-> **These constraints hold whether you seed serially or concurrently:**
-> - **Bookings before pricing-plans.** The plan→service coverage step needs the created service IDs, so keep the two in order and seed them together.
-> - **Restaurants menu before its online ordering.** The ordering add-on (`setup-restaurant-orders.md`) verifies/reshapes the auto-provisioned ordering setup for each menu. Installing the Orders app auto-enables ordering for menus that exist *and* for menus created after install, so ordering binds either way — but seed the menu first, then the ordering, as one unit, so the verify step has a menu to confirm against. If you split this work off to run concurrently, hand over the seeded `menuId`s and seed menus-then-ordering together.
-> - **Intra-recipe serial rules stay.** Store categories are created one at a time (they share the `@wix/stores` tree revision; concurrent creates `409`), and pricing-plans' sub-steps stay ordered.
->
-> **Read a capability's recipe only if you're going to seed it yourself; if that capability is seeded as a separate concurrent unit, that *unit* reads the recipe — you don't.** Don't read all the seed recipes into your own context and *then* hand the work off — that loads each recipe twice (once wasted) and bloats working memory. Read-if-you-seed applies equally to the do-it-all-yourself path (read each recipe once, when you seed that capability) and the split-off path (only the unit that seeds a capability reads its recipe).
-
-## 1 · Where the *how* comes from — the inline recipes
-
-Each built capability's create flow lives in a **local recipe** at `inline-recipes/setup-<capability>.md` (§2 maps each capability to its file). Most inline their endpoints and bodies; Donations delegates to the shared management recipe to avoid a second maintained contract. **Open the mapped recipe and follow its local references**; do not rediscover covered calls. **Read a recipe once per run** — if you already opened it while planning, proceed from what you have — and only read a capability's recipe if you're going to seed it yourself (a separate concurrent unit reads its own; see the concurrency note above).
-
-For a capability with **no** inline recipe (e.g. `coupons`), or for a field/error/endpoint a recipe doesn't cover, **`DOC_DISCOVERY.md` is the fallback** — never the first move.
-
-Two cautions apply to every capability regardless of recipe:
-
-> **Public host, not `/_api/`.** Some method pages show an internal `https://www.wixapis.com/_api/<service>/...` URL in the schema header while the examples use the bare `https://www.wixapis.com/<service>/...`. Always call the **public (non-`/_api/`) form** — that's the external/headless endpoint; the `/_api/` prefix is internal and may be rejected.
-
-> **Imagery is opt-in.** When `imagery` is **off** (the default), create entities **text-only** — omit image fields or use the placeholder the recipe documents; don't source imagery. When `imagery` is **on**, still create the entities text-first here, then attach generated images in the "Entity images" step below. This applies to **every** vertical, stores included — there is no per-vertical exception.
-
-## 2 · What to seed per capability
-
-Each entry states only the entities, where their count/content comes from, the policy that is genuinely the skill's call, the IDs to keep, and **which inline recipe carries the calls** — read that local recipe and any shared recipe it delegates to for everything else.
-
-- **donations** — *Donation campaigns.* Recipe: **`setup-donations.md`**. Read existing campaigns first; do not seed for a frontend-only request. For an authorized new setup, use `intent.donations.campaigns` and the shared recipe's constraints. Keep created IDs transiently for readback and cover-image attachment; campaigns are discovered live in the frontend. Goals, deadlines and impact claims require supplied/approved content; payment readiness is separate from campaign creation.
-- **stores** — *A product catalog.* Recipe: **`setup-online-store.md`**. `intent.stores.productCount` products whose names/prices fit `brand`. If `intent.stores.categoriesNamed` is non-empty, create exactly those categories and assign products into them; **if empty, create none** (skill policy — overrides any docs default). **Variant cardinality — keep it small by default:** unless `intent.stores` calls for specific options, give each product **at most one option with ≤3 choices** (so ≤3 variants/product); many products legitimately have **no** options (a single variant). Seeding cost scales with the variant Cartesian product and the field count per variant, so don't manufacture options the brief doesn't need — but **honor a larger/explicit option set when intent names one** (this default is a floor, not a cap). Text-only by default (images only when `imagery` is on — §1, §4). **Keep (seed-time only):** `categoryIds[]` to assign products into their categories; **nothing goes to the handoff** — the frontend lists products and categories **live** (`queryProducts` / `searchProducts` / `queryCategories`), so owner-added products/categories appear with no code change.
-- **blog** — *Initial posts.* Recipe: **`setup-blog.md`**. `intent.blog.postCount` posts on `intent.blog.topics` (or brand-derived topics). Text-only (no covers). **Keep:** nothing for the handoff — posts are discovered **live** (`queryPosts`, `[...slug]` routes). Track created post ids only transiently (to confirm success / assign categories).
-- **cms** — *Content collections.* Recipe: **`setup-cms.md`**. One collection per `intent.cms.collections` entry; `itemCount` items each, content from `brand`. Collections are **public-read** (visitor reads on the frontend) by default. **(Opt-in, members only)** if the brief calls for per-user-private or member-only data **and** members login is in the run, seed that collection **member-scoped** instead (per-user or member-only — see `setup-cms.md`); a per-user collection is seeded **empty** (members populate it), since admin-seeded rows are owned by the admin. **Keep (→ handoff):** `collectionIds{<name>}` + each collection's **field keys** — this is *structural* (the frontend must know the collection name and its fields to query and bind; it doesn't change when an owner adds a row). `itemIds{<name>:[]}` only transiently, for wiring multi-references during seeding.
-- **forms** — *Visitor-fillable forms.* Recipe: **`setup-forms.md`**. One form per `intent.forms.forms` entry; fields from the entry, `purpose` names the form. **Keep (→ handoff):** `formIds[]` + each form's field **`target`** keys — *structural* (the frontend binds each input's `name` = target to submit; targets are **immutable**, so they don't go stale when an owner relabels a field).
-- **events** — *A ticketed or RSVP occasion, or upcoming events.* Recipe: **`setup-events.md`**. Each event is **either `TICKETING`** (paid — it has ticket tiers) **or `RSVP`** (free — the registration form is built-in, so don't seed form fields) per intent. For an **RSVP occasion** (a wedding, party, gathering): one RSVP event with the occasion's real details (title, a **future** date/time, location). For a **ticketed** event: the event plus its ticket tiers (default a single `"General Admission"` tier if none named). For a **listing** site: `intent.events.eventCount` events with brand-appropriate titles and **future** start dates (a default location/timezone is fine). Text-only. **Keep:** nothing for the handoff — events and tiers are discovered **live** (`queryEvents`, `getEventBySlug`, `queryAvailableTickets`); track `eventIds`/`ticketDefinitionIds` only transiently.
-- **bookings** — *Bookable services.* Recipe: **`setup-bookings.md`**. `intent.bookings.serviceCount` services (name + short description fitting `brand`, a simple duration and price); keep the schedule minimal. **Keep:** `serviceIds[]` as **seed-time state** (pricing-plans' coverage step keys on them, below); nothing for the handoff — services are discovered **live** (`queryServices`).
-- **rentals** — *Rentable resources.* Recipe: **`setup-rentals.md`**. A resource **type** per kind of thing rented (rooms, vans, cameras), then `intent.rentals.resourceCount` **resources** inside it (Room A / Room B — parallel capacity comes from more resources, not higher capacity), then `intent.rentals.serviceCount` **rental services**, each carrying the Wix Rentals `appId`, `serviceResources` naming its resource type, a `primaryResourceType`, and a `durationRange` (`HOUR` or `DAY`) with the min/max the request implies — defaulting to **60/480 minutes** hourly and **1/5 days** daily when the brief doesn't say — and a **per-unit** price. **No category** — unlike bookings, rental services don't use one; don't create or assign one. **Order is load-bearing: resource type → resources → services** — a service whose resource type holds no resources has permanently empty availability. Seed resources **24/7** (no working-hours schedule) unless the request names opening hours; that keeps a multi-day rental to a single booking. **Keep:** `resourceTypeIds[]` as seed-time state (services key on them); nothing for the handoff — rentals are discovered **live** (`queryServicesByFilters` filtered by the rentals `appId`).
-- **pricing-plans** — *Membership tiers.* Recipe: **`setup-pricing-plans.md`**. `intent.pricing-plans.planCount` recurring plans (name, price, a monthly billing cycle) fitting `brand`. **When bookings is also in this run and the intent is a membership that covers services** (a studio/gym/class pass), also **attach the covered bookings services to the plan** — seed the bookings services first, since coverage keys on their service ids (see the recipe). **Keep:** the bookings coverage only transiently, to wire it during seeding; nothing for the handoff — plans are discovered **live** (`queryPlans`) and plan→service coverage is read **live** at checkout, never from a frozen map (see `how-to-code-pricing-plans.md`).
-- **restaurants** — *A menu.* Recipe: **`setup-restaurants.md`** (add-ons have their own recipes, below). Create the `itemCount` items per section first (name, description, price fitting `brand`), then the `intent.restaurants.sections` referencing those item ids, then the menu referencing the section ids — **items → sections → menu** (build bottom-up: a section is created with its `itemIds`, a menu with its `sectionIds`, so each child must exist before its parent — see `setup-restaurants.md` STEP 1–3). Text-only. **Keep (seed-time only):** `menuId`, `sectionIds[]`, `itemIds[]` to build the tree; nothing goes to the handoff — the frontend reads menus **live** (`listMenus`/`listSections`/`listItems`). **Online ordering (add-on, on demand)** — only when the request calls for ordering (not just a displayed menu): install the Orders app (per `SETUP.md` §2) and follow **`setup-restaurant-orders.md`**; **seed the menu FIRST, then ordering, in the same unit** (ordering auto-provisions per menu either way — see the concurrency note above — but keeping them one unit gives the ordering verify a menu to confirm against). **Configure the business-location address (`setup-restaurant-orders.md` STEP 0) — required for ordering to work end-to-end; without it Wix limits ordering to "testing only" and checkout breaks.** If the brief gives no address, set a placeholder and flag the owner in the handoff. Completing a *paid* order additionally needs premium + a payment method (dashboard/premium — surface, don't fail). **Keep:** nothing for the handoff — read **live** (`listOperations`/`listFulfillmentMethods`); track `operationId`/`fulfillmentMethodIds[]` transiently. **Table reservations (add-on, on demand, INDEPENDENT of ordering/menu)** — only when the request calls for reservations: install the Table Reservations app (per `SETUP.md` §2) and follow **`setup-restaurant-reservations.md`**; **no menu dependency** (reservations bind to a location, not a menu — do NOT apply the menu-first rule) and **nothing to bulk-seed** (visitors create reservations at runtime); **configure the business-location address (`setup-restaurant-reservations.md` STEP 0)** — the reservation location is the site's business location, so set a real address (placeholder + owner flag if the brief names none; shared with ordering if both are present); enabling online reservations is **premium-gated** (record the precondition, don't fail). **Keep:** nothing for the handoff — read **live** (`listReservationLocations`); track `reservationLocationId` transiently. **Experiences (add-on within Table Reservations, on demand)** — only when the request names **special dining occasions guests reserve** (chef's table, tasting menu, tasting-menu evening — an *experience*, not a `bookings` service; see `CAPABILITIES.md`): they need the **Table Reservations app** (no extra install) and a configured **business-location address** (`setup-restaurant-reservations.md` STEP 0, same as reservations) and, unlike plain reservations, they **are** seeded — create one Experience per named occasion on the default reservation location, following **`setup-restaurant-experiences.md`**. Booking an experience is **premium-gated** like online reservations (record the precondition, don't fail). **Keep:** nothing for the handoff — experiences are read **live** (`queryExperiences`); track `experienceId`(s) transiently.
-- **portfolio** — *A project showcase.* Recipe: **`setup-portfolio.md`**. Create the `intent.portfolio.collections` (title + short description fitting `brand`), then `intent.portfolio.projectCount` projects assigned to them — **collections before projects** (a project's `collectionIds` must hold real collection ids; see the recipe). Text-only by default (omit `coverImage`; images only when `imagery` is on — §1, §4). **Keep (seed-time only):** `collectionIds{<name>}` to assign projects into their collections; nothing goes to the handoff — the frontend lists collections and projects **live** (`collections.queryCollections` / `projects.queryProjects`), so owner-added content appears with no code change.
-
-> **Cross-cutting (on demand).** `coupons` is not a standalone capability (`CAPABILITIES.md` § "Cross-cutting capabilities") — there's no app to install and it's not in `verticals[]`. If intent calls for discounts **and** a parent vertical (stores / bookings / events / pricing-plans) is in this run, create coupons scoped to that parent and add the coupon to the `seeded` map (`seeded.coupons = { couponIds[] }`). **Coupons has no inline recipe** — read the create shape from the docs (`DOC_DISCOVERY.md` is the fallback): every coupon needs a scope with a namespace and its parent vertical's app installed (<https://dev.wix.com/docs/api-reference/business-solutions/coupons/about-wix-coupons.md>), and the create-coupon spec needs name/code/start + a scope namespace + exactly one coupon-type field (<https://dev.wix.com/docs/api-reference/business-solutions/coupons/coupons/create-a-coupon.md>). eCommerce needs no seeding — it's the runtime checkout layer that rides along.
-
-> **members — nothing to seed.** Member login is the identity layer (`CAPABILITIES.md`): members **self-register** through the Wix login page, so there is **no member to create** at seed time and nothing lands in `seeded`. The frontend wiring is the `how-to-code-members-*.md` recipes (pick per `SDK_HANDOFF.md`), surfaced via the Handoff. *Optionally* — and **only** if a run's prompt explicitly asks to exercise the pricing-plans purchase path end-to-end — seed one test member; keep this **off by default** so headless runs stay deterministic and don't stall on an interactive login. Do **not** seed a member just because pricing-plans is present.
-
-> **Simple seeds (experiment).** For these newer capabilities, create the minimum that demonstrates the shape — a couple of entities with required fields only. The recipe (§2) says which fields are *required* — stop there; don't seed optional structure (variants, multi-session schedules, perks) the host's app won't exercise.
-
-## 3 · Enable the backend-backed required features
-
-A capability's **Required site features** (`references/CAPABILITIES.md`) are part of a complete site, and some of them need a backend feature switched on — not just content created. The clearest case — **only when the brief asks for it** — is **blog comments** (readers commenting on posts): comments are intent-gated, not a baseline blog feature (`CAPABILITIES.md` blog entry), but when requested they need their backend feature available. For each loaded capability, check its *Required site features*:
-
-- If one depends on a backend feature that isn't on by default, enable it via the method its recipe documents (or `DOC_DISCOVERY.md` if the recipe doesn't cover it).
-- If it's already on by default, there's nothing to seed — but record it as **available** so the Handoff tells the host to surface it.
-- If it genuinely can't be enabled, note that, so the Handoff doesn't imply the site is complete.
-
-Don't silently skip a required feature — a bare list-and-detail with none of its required features is the "half-built site" this is meant to prevent. (Purely presentational items — showing the author, the date — need no backend and belong to the Handoff's *Implementation checklist*, not here.)
-
-## 4 · Entity images (opt-in)
-
-**Only if `imagery` is on** (from `DISCOVERY.md`). For each seeded image-bearing capability — stores products, blog covers, CMS items, **bookings services**, **rental services**, restaurant items, **portfolio projects + collection covers**, event heroes — generate a brand-contextual image per entity and **attach it as a required pass-2 step** (the seeder created the entity text-first in §2; this writes the image onto it), following `references/IMAGE_GENERATION.md` (generate → import to Wix Media → attach). **The per-entity attach shape lives in that capability's own seed recipe** (`setup-<capability>.md`), next to its create shape — read it there; `IMAGE_GENERATION.md` §3 is a navigation table (entity → recipe → step) that carries no shapes. Use the IDs already in the `seeded` map. Image failures never block — skip and continue (the entity stays text-only). When `imagery` is off, skip this step entirely.
-
-## Aggregate
-
-Hold a `seeded` map in scratch — `seeded[<capability>] = { …kept IDs… }` — as **seed-time working state** (it feeds intra-seed steps like image attach in §4 and cross-capability wiring like pricing-plans coverage). **What crosses into the handoff is only the *schema* carve-outs**, not the per-item content ids: **cms** `collectionId` + field keys, and **forms** `formId` + field `target`s (see `SDK_HANDOFF.md` §4). Everything else the frontend rediscovers with a live query, so it need not be surfaced — carrying a per-item id/slug list into the handoff only tempts the host to hardcode it. Whether to also write a sidecar file is a host-preference choice (default: return-only, in the handoff message).
-
-On a per-capability error, keep the other capabilities' results and surface the failing REST-call response verbatim; partial state is fine — a targeted re-run is bounded.
-
-## Proceed to Handoff
-
-With `seeded` populated, continue to **`SDK_HANDOFF.md`** to produce the document the host wires from.

package/skills/wix-headless/references/SETUP.md

@@ -1,60 +0,0 @@
-# Setup — install the business apps
-
-Install the Wix apps the resolved capabilities need, on the given metasite. That is the whole of setup — the frontend toolchain stays with the host.
-
-## 1 · Obtain the token
-
-Obtain `$TOKEN` (a bearer authorized for the metasite) and `$SITE_ID` (the metasite id) **using the provided authentication mechanism** — see `<TYPE_DIR>/AUTHENTICATION.md`. Hold them for the install calls below.
-
-All Wix REST calls in this skill then use the same universal call shape:
-
-```
-Authorization: Bearer $TOKEN
-wix-site-id: $SITE_ID
-Content-Type: application/json
-```
-
-## 2 · Install one app per capability
-
-For each capability in `verticals[]`, install its app by `appDefId` (these are the constants the install call needs):
-
-- **stores** → `215238eb-22a5-4c36-9e7b-e7c08025e04e`
-- **blog** → `14bcded7-0066-7c35-14d7-466cb3f09103`
-- **forms** → `225dd912-7dea-4738-8688-4b8c6955ffc2`
-- **events** → `140603ad-af8d-84a5-2c80-a0f60cb47351`
-- **bookings** → `13d21c63-b5ec-5912-8397-c3a5ddb27a97`
-- **rentals** → `ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e` (Wix Rentals). Rentals provisions the Bookings infrastructure it runs on, so a Rentals-only install is enough — its availability comes back without adding Wix Bookings separately. Rentals has **no APIs of its own**: it is Services V2 with rentals-specific field values (`setup-rentals.md`), and its frontend package is `@wix/bookings` — there is no `@wix/rentals`. Rentals uses no categories; to also offer plain fixed-duration services, install Wix Bookings (`13d21c63-b5ec-5912-8397-c3a5ddb27a97`) as well, seed those with `setup-bookings.md`, and filter every catalog read by `appId` so the two sets stay separate.
-- **pricing-plans** → `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3`
-- **restaurants** → `b278a256-2757-4f19-9313-c05c783bec92` (Wix Restaurants **Menus** — the seedable core). Online ordering and table reservations are **separate optional apps**, install only if intent calls for them: Orders (New) → `9a5d83fd-8570-482e-81ab-cfa88942ee60`, Table Reservations → `f9c07de2-5341-40c6-b096-8eb39de391fb`. **Experiences** (special dining occasions guests reserve — chef's tables, tasting menus; see `CAPABILITIES.md`) are a **feature of the Table Reservations app, not a separate install** — installing Table Reservations is all that's needed to create and book them (`setup-restaurant-experiences.md`).
-- **portfolio** → `d90652a2-f5a1-4c7c-84c4-d4cdcc41f130` (Wix Portfolio; the install ships a default sample collection + projects — `setup-portfolio.md` STEP 0 cleans them)
-- **donations** → `333b456e-dd48-4d6b-b32b-9fd48d74e163` (Wix Donations), plus Checkout & Orders `1380b703-ce81-ff05-f115-39571d94dfcd`. Confirm installed state and authorized changes first; do not reinstall to fix a malformed cart payload.
-- **cms** → **no install** (Wix Data is core) — skip
-
-For any vertical added later, its appDefId is in the docs — "Apps Created by Wix": <https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md>.
-
-> **members — install is conditional on the layer, and only the *profile* layer installs anything.** Members is a cross-cutting capability (`CAPABILITIES.md`), not a `verticals[]` entry, so it has no unconditional row above. Split by layer:
-> - **Identity only** (sign-up / log-in / log-out, "logged-in vs not" gating — the common case, and all that pricing-plans' subscribe flow needs) → **no install.** It's the headless OAuth app; members self-register. Skip, exactly like cms.
-> - **Profile / Members Area** (the site *displays or edits* member data — name / photo / roles / badges, a my-account page) → install the **Wix Members Area app**, `appDefId` **`14cc59bc-f0b7-15b8-e1c7-89ce41d0e0c9`** (via the same `apps-installer-service` call above; it pulls in its Site-Members dependency automatically). **Wrinkle:** Members Area is **not** in the "Apps Created by Wix" table (that table has Stores, Blog, Pricing Plans, Groups… but no Members Area), so the GUID can't be grabbed from there — it comes from the App Market listing (<https://www.wix.com/app-market/web-solution/members-area>). Install it **only when the run genuinely needs profile data**; pure "logged-in vs not" gating (the common case) is the identity layer and needs no install.
-
-Fire one install `curl` per app — `POST /apps-installer-service/v1/app-instance/install`:
-
-```bash
-# TOKEN, SITE_ID from the provided authentication mechanism — see <TYPE_DIR>/AUTHENTICATION.md
-curl -sS -w "\nHTTP_STATUS:%{http_code}" \
-  -X POST "https://www.wixapis.com/apps-installer-service/v1/app-instance/install" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "wix-site-id: $SITE_ID" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "tenant":      { "tenantType": "SITE", "id": "'"$SITE_ID"'" },
-    "appInstance": { "appDefId": "<appDefId>", "enabled": true }
-  }'
-```
-
-The installs are independent — issue them in whatever order is convenient.
-
-A **200** confirms the install. On a non-200, surface the response verbatim and stop.
-
-## 3 · Proceed to Seed
-
-Confirm every required app returned 200 (cms skipped). Then continue to **`SEED.md`**, which seeds from the local inline recipes.