@wix/agent-skills 1.35.1 → 1.36.1

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

@@ -1,178 +0,0 @@
-# AI features — text, chat & embeddings (opt-in, all project types)
-
-Add **generative-AI features** to a headless app using the **Wix AI APIs**: LLM text/chat completions
-and text embeddings. Wix fronts the model providers (OpenAI, Anthropic) and handles auth + billing, so
-you never hold a provider key. **For image generation, see `IMAGE_GENERATION.md`** — same gateway, same
-rules; this file is text + embeddings and the rules that apply to *all* AI calls.
-
-**Opt-in, by intent** — only build AI features when the intent calls for them (a support chatbot, AI
-product descriptions, semantic search, summarization…). Like imagery, it's off by default; there's
-no fixed slot list. **Status: Developer Preview** — the API shape can change; confirm models with
-`/models` (below) rather than trusting a hardcoded list.
-
-## The one hard rule: AI runs server-side only
-
-**Every AI call must be made from server code. Never from the browser.**
-
-- A **visitor / member** identity (what a headless frontend holds in the browser) is **rejected** by
-  the gateway.
-- The `@wix/ai` SDK **throws in browser environments** (*"AI calls from browser code are not supported.
-  Move your AI logic to backend code."*).
-
-So the AI call always sits **behind a server boundary** — a Wix serverless/web-method backend
-(managed), or the app's own server (self-managed/stripe). The browser calls *your* endpoint; your
-endpoint calls Wix. That boundary is also where you enforce credits/abuse controls (see **Credits &
-cost control**) — it's the security and billing perimeter, not optional plumbing.
-
-## Use the SDK (`@wix/ai`) — the path for app code
-
-For the app you build (Astro-on-Wix, Node — any JS/TS server), **use the SDK**. It's built on the
-[Vercel AI SDK](https://ai-sdk.dev) — typed, and auth is handled for you. **Backend only.**
-
-```bash
-npm install @wix/ai "ai@>=6.0.26" "zod@>=4.1.8"
-```
-
-```js
-// Wix-managed backend (Astro-on-Wix serverless / web method): auth is handled automatically.
-import { generateText } from "ai";
-import { openai } from "@wix/ai";              // also: anthropic, runware
-const { text } = await generateText({ model: openai("gpt-5.2"), prompt: "…" });
-```
-
-```js
-// Self-managed / stripe: pass an authenticated WixClient instead.
-import { createOpenAI } from "@wix/ai";
-import { createClient, AppStrategy } from "@wix/sdk";   // or ApiKeyStrategy
-const openai = createOpenAI({ client: createClient({ auth: AppStrategy({ appId, appSecret, instanceId }) }) });
-```
-
-`@wix/ai` exports `openai`, `anthropic`, `runware` (ambient, Wix-managed) and `createOpenAI`,
-`createAnthropic`, `createRunware` (client-injected, self-managed). Methods come from `ai`:
-`generateText` / `streamText`, `embed` / `embedMany`, `generateImage`. **Exact model selectors**
-(verified — don't guess the method names):
-
-- **Text:** `openai("gpt-5.2")` or `openai.responses(id)` / `openai.chat(id)`; `anthropic("claude-…")`.
-- **Embeddings:** `openai.embeddingModel("text-embedding-3-small")` — **not** `textEmbeddingModel` (that
-  method doesn't exist and throws). Returns a `number[]` (1536 dims for `3-small`).
-- **Images:** `runware.image("<air-id>")`. `generateImage` returns `{ image }` with `image.base64` +
-  `image.mediaType` — build a data URL (`data:${mediaType};base64,${base64}`) or import to Wix Media.
-  In `ai` v7 the fn may be exported as `experimental_generateImage`; fall back to it if `generateImage`
-  is undefined.
-
-> **Runware via the SDK — model gotcha (verified):** `google:4@2` (Nano Banana) **fails via the SDK**
-> ("Unknown Runware API error" — the Vercel provider injects params it rejects), even though it works
-> on the raw REST proxy. Use **`bfl:5@1`** (FLUX.2 Pro) or **`runware:100@1`**. Runware is also
-> **intermittently flaky** — wrap image calls in a **retry + model fallback** (`bfl:5@1` → `runware:100@1`)
-> so a transient blip doesn't surface to the user.
-
-**Wiring to the browser:** expose a **server route (or action) that returns plain JSON** and have the
-browser `fetch` it — the AI runs in that route; the browser never touches the gateway.
-
-## Text & chat generation
-
-```js
-import { generateText, streamText } from "ai";
-import { openai, anthropic } from "@wix/ai";
-
-const a = await generateText({ model: openai.responses("gpt-5.2"), prompt: "Invent a holiday." });
-const b = await generateText({ model: anthropic("claude-sonnet-5"), prompt: "Tell me a story." });
-// streamText(...) for token-by-token streaming to the client.
-```
-
-## Embeddings (semantic search, similarity)
-
-```js
-import { embed, embedMany } from "ai";
-import { openai } from "@wix/ai";
-const model = openai.embeddingModel("text-embedding-3-small");
-
-const { embeddings } = await embedMany({ model, values: products.map((p) => p.text) });
-const { embedding } = await embed({ model, value: query });
-// rank by cosine similarity; persist product vectors in a Wix Data collection to avoid re-embedding.
-```
-
-## Models — query, don't hardcode
-
-`GET /{provider}/v1/models` is the **source of truth**. New provider models land on Wix a few days
-after release; some ids are **date-stamped**. Tested-current picks (verify with `/models`):
-
-- **OpenAI text**: `gpt-5.2`, `gpt-5.2-pro`, `gpt-5.1`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-4.1`,
-  `gpt-4.1-mini`, `gpt-4.1-nano`.
-- **OpenAI embeddings**: `text-embedding-3-small` (1536), `text-embedding-3-large`, `text-embedding-ada-002`.
-- **Anthropic**: `claude-opus-4-8`, `claude-sonnet-5`, `claude-opus-4-7`, `claude-sonnet-4-6`,
-  **`claude-haiku-4-5-20251001`** — the *dated* id. **`claude-haiku-4-5` (undated) → `400 Unsupported
-  model`**; use the dated id `/models` returns.
-
-## REST (provider pass-through) — when the SDK doesn't fit
-
-Use REST if your backend **isn't JS/TS**, or when you want the **raw HTTP** API. The gateway is a
-**transparent pass-through**: base URL `https://www.wixapis.com/{provider}/v1/...` with the
-**provider's native request/response bodies** (model params, streaming, tool calls per the provider's
-own docs). Authenticate with the skill's universal call shape (`SETUP.md` §1):
-
-```bash
-curl -sS -X POST "https://www.wixapis.com/openai/v1/chat/completions" \
-  -H "Authorization: Bearer $TOKEN" -H "wix-site-id: $SITE_ID" -H "Content-Type: application/json" \
-  -d '{"model":"gpt-5-nano","messages":[{"role":"user","content":"Write a 1-line product tagline"}]}'
-```
-
-Endpoints: OpenAI `POST /openai/v1/responses` · `/chat/completions` · `/embeddings`; Anthropic
-`POST /anthropic/v1/messages`.
-
-- **Anthropic requires `-H "anthropic-version: 2023-06-01"`.** Omitting it → `400 anthropic-version:
-  header is required` (the public doc's curl example omits it — don't copy that).
-- **Streaming**: set `"stream": true` — response is SSE (`data:` lines), provider-native.
-- `wix-site-id` is accepted-but-not-required for AI calls (the token is already site-scoped) — include
-  it for consistency with every other call in the skill.
-
-## Credits & cost control — the gap you MUST design for
-
-**AI usage is billed to the site *owner's* account, never to the end user.** This is structural, not
-a setting:
-
-- AI credits belong to the **account's Premium plan**, shared across the whole account; monthly
-  allowance by tier, **no rollover** (free plan ≈ 30/day, 120/mo). Each call ≈ **1 credit** (varies
-  by model/size); the platform meters every call and **blocks when the account balance runs out**.
-- Because every AI call runs under the **owner/app identity** (the only identity the gateway accepts),
-  **there is no per-visitor or per-member credit pool.** A visitor who triggers an AI feature spends
-  the *owner's* credits.
-
-**Consequence:** any AI feature exposed to end-users (a public chatbot, "generate my bio", etc.) lets
-anonymous traffic **drain the owner's credits** — and gives you no built-in way to attribute or cap
-usage per end-user. The platform will not solve this for you. **The app must own a metering layer.**
-
-When AI is exposed to end-users, build these into the **server boundary** — don't ship AI to end-users
-without them:
-
-1. **Gate access** — require an authenticated member (or your own key) for anything that costs
-   credits; don't wire AI to a fully-open public route by default.
-2. **Rate-limit & quota per identity** — track calls per member/session/IP in a Wix Data/CMS
-   collection; **check-and-decrement before the AI call**, reject over quota (re-check after, since
-   the credit balance is account-wide).
-3. **Cap inputs** — bound prompt/`max_tokens`/`input` size; large requests cost more credits.
-4. **Cache / dedupe** — memoize identical prompts (product description for the same product, etc.);
-   static AI content is best computed **once, ahead of time** and stored, not regenerated per request.
-5. **Fail soft** — on a rejected/quota/insufficient-credits response, degrade gracefully (cached/canned
-   copy), never hard-error the page; surface cost transparently to the owner.
-
-> If the user wants true **per-end-user AI budgets** (e.g. "each member gets N generations/month"),
-> that is an **applicative feature to build** — a usage-ledger collection keyed by member, enforced
-> server-side — because Wix bills only the owner and offers no per-visitor pool. Call this out to the
-> user rather than implying the platform meters end-users.
-
-## Failure ladder
-
-| Symptom | Cause → fix |
-|---|---|
-| Call rejected from the browser / with a visitor or member identity | **Move the call server-side.** AI never runs in the browser. |
-| `403 Forbidden` (server identity) | Building a Wix **app**: add the `Invoke AI Models` permission to the app (see the AI-APIs doc). |
-| `400 anthropic-version: header is required` | REST only — add `-H "anthropic-version: 2023-06-01"` (the SDK sets it for you). |
-| `400 Unsupported model` | Use the exact id from `/{provider}/v1/models` (Anthropic ids are often date-stamped, e.g. `claude-haiku-4-5-20251001`). |
-| `Unknown Runware API error` (images) | Transient, or the model rejects SDK params (`google:4@2`). Retry + fall back to `bfl:5@1` / `runware:100@1`. |
-| insufficient credits / quota | Account is out of AI credits — degrade soft; tell the owner. |
-
-## See also
-- `IMAGE_GENERATION.md` — image generation (Runware) via the same gateway.
-- Live docs: `dev.wix.com/docs/api-reference/articles/ai-tools/ai-apis/about-the-wix-ai-apis` (+ `…/set-up-the-wix-ai-sdk`).
-- Provider request/response params: OpenAI & Anthropic API references (the gateway is pass-through).

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

@@ -1,117 +0,0 @@
-# Wix vertical index
-
-A catalog of the Wix business verticals. It does two jobs:
-
-1. **Discovery** maps the user's words to the right vertical(s) — read every *Intent* line against what they asked for, and pick each vertical that genuinely fits.
-2. For the verticals this skill builds end-to-end, it also says **what a complete site for that vertical looks like** — the features it must have and the details that make it feel finished.
-
-> **Read this against the operation — `create` vs `connect`.**
-> - **Intent** matching (job 1) always applies — it picks the capabilities to install and seed, no matter the operation.
-> - **Required site features** and **Implementation checklist** (job 2) describe a site **built from scratch** — they are the target for **`create`**, and they tell **backend-only** what to ask the host to build. They are **not a spec to impose on `connect`.** In `connect` the user brought a finished design; **wire only what that design actually needs** (e.g. a single wedding page with an RSVP → set up the RSVP and wire it; do *not* add an events-listing page or per-event pages just because the vertical's required-features list names them). Use the checklist there only as a soft hint for what an already-present surface should show — never to add surfaces the design doesn't have.
-
-This file is **the what, never the how** — plain language only. No endpoints, methods, payloads, appDefIds, or SDK packages. The *how* lives in the live docs (Seed navigates the REST docs; the Handoff navigates the SDK docs); the *which apps to install* lives in `SETUP.md`.
-
-Each built vertical has three parts (the latter two scoped to `create`/backend-only per the note above):
-
-- **Intent** — the words that point to it.
-- **Required site features** — the surfaces and capabilities the site must have to be usable. These are non-negotiable for a complete site; if one needs a backend feature switched on, Seed sets it up, and the Handoff tells the host to build the rest.
-- **Implementation checklist** — the presentation details a finished site shows, so it doesn't feel half-built. The Handoff carries these into the guide it returns.
-
-## Built verticals — installed, seeded, and described in the Handoff
-
-The verticals the skill operates end-to-end today: **stores · blog · cms · forms · events · bookings · rentals · pricing-plans · restaurants · portfolio · donations** (with `forms` as the floor when nothing richer is named).
-
-### donations — accept contributions to a cause
-- **Intent:** donate / fundraising / charitable giving / donation campaign / recurring donation. This is not a generic contact form, merchandise purchase or Pricing Plans membership.
-- **Required site features:** a clear giving entry point; live campaign discovery when there are several causes (a single-cause form otherwise); campaign detail with the configured amount/frequency choices and optional features; a working hosted checkout handoff; an honest return/thank-you state.
-- **Implementation checklist:** design from the cause and supplied content; bound mobile imagery so the giving decision is easy to reach; show configured impact text, custom limits, notes and optional fee coverage; make recurring commitments explicit; progress only when configured/readable; no fabricated tax, donor or impact claims. Read the shared Donations experience reference linked by `how-to-code-donations.md`.
-
-### stores — sell products
-- **Intent:** sell / shop / products / catalog / merch / store.
-- **Required site features:** a homepage that sells (what the store offers, real products, one clear shopping action); a shop / category gallery with sort, the filters the catalog supports, and paging; a page per product; categories to browse by; a cart the shopper can review and edit, opening as a side drawer after every add; checkout reachable directly from that cart.
-- **Implementation checklist:**
-  - *Homepage:* say what the store sells in the first screen; real products from the catalog under truthful headings — never a repeat of the shop page, never a heading like "Best Sellers" without data behind it.
-  - *Gallery:* a real product — image, name, price, link — visible in the first screen before any scrolling; a result count; a filter panel with price, stock, and the option facets the catalog has (required whenever there is something to filter); a way to buy on every card (one click without options, a quick-add picker with options); loading, empty-catalog, no-results-for-these-filters, and error states that look different from each other.
-  - *Product page:* in the first screen, the product image, name, price, the first choice to make, and the buy button — disabled with a plain reason until every choice is made; every ribbon the merchant set; the current price and, when there is one, the labelled original price; a gallery of every product image; options with unavailable choices marked; quantity; the full description and information sections; pre-order, subscriptions, and notify-me only when the catalog has them.
-  - *Cart:* each line's image, name, chosen options, quantity (editable) and price; subtotal and discounts as Wix calculates them; "shipping and taxes calculated at checkout" rather than invented numbers; survives a reload; checkout from the drawer.
-  - *Everywhere:* availability / out-of-stock shown truthfully; each product linked to its category, and each category a page at its own URL linked from the navigation; no reviews, ratings, scarcity, or delivery promises the merchant didn't supply; no Wix IDs or technical words in shopper-facing text.
-
-### blog — publish posts
-- **Intent:** blog / posts / articles / publication / news.
-- **Required site features:** a list of posts; a page per post; categories or tags to browse by topic.
-- **Optional (intent-gated):** reader **comments** on a post — build **only if the brief asks for discussion/interaction.** Comments hard-depend on members/login, so adding them unrequested drags in an unrequested login gate; they are **not** part of the baseline blog surface (see `inline-recipes/how-to-code-a-blog.md` §Comments).
-- **Implementation checklist:** show the **author** (name and photo) on each post; show the publish date and the reading time; show the cover image; render the full formatted content — headings, images, quotes, lists — not flattened to plain text; show the post's category and tags; a clear path back to the full list.
-
-### cms — structured content collections
-- **Intent:** collection / directory / portfolio-as-data / structured content / "persist my app's data".
-- **Required site features:** an index/list view of the collection; a detail page per item. (Visitor reads are public; visitor writes go through a form.) **(Opt-in, with members)** when the brief asks for per-user-private data ("my saved items", a personal list) or member-only content **and** members login is in the run, a collection can instead be **member-scoped** — each member sees/edits only their own rows, or any logged-in member reads shared member-only content. Added only on that intent, never by default; see the members cross-cutting entry and `setup-cms.md`.
-- **Implementation checklist:** show each item's main fields with clear labels; link the list to each item's detail page; show a sensible empty state when there are no items yet.
-
-### forms — any visitor-fillable form
-- **Intent:** contact / enquiry / lead / signup / waitlist / application / feedback / survey /
-  questionnaire / quote request / intake or registration form / "let people reach me" / generic custom
-  data capture — plus the **floor** when nothing dynamic is named. Lead capture is the most common
-  case, **not the boundary**: any form a visitor fills in and submits is this vertical, and whether
-  the submission also becomes a CRM contact is an optional per-field mapping.
-- **Not forms — an RSVP is `events`:** confirming attendance to an event or occasion (a wedding,
-  party, or gathering) is the **events** vertical, which ships a built-in RSVP registration form —
-  route there even for a single occasion with no tickets.
-- **Not forms — a per-service booking form is `bookings`:** the form attached to a bookable service
-  belongs to **bookings**. Use `forms` only when neither an event nor a bookable service is
-  involved.
-- **Required site features:** a visible form; a confirmation after submitting; basic field validation.
-  A site may have **more than one** form, each with its own purpose and field set.
-- **Implementation checklist:** render every field with a clear label; mark which fields are required;
-  a clear submit button; show a thank-you / success state after sending; show a friendly message if
-  the submit fails.
-
-### events — events and registration
-- **Intent:** event / ticket / RSVP / registration / attendees / "confirm attendance" / a wedding, party, or gathering people respond to. **Covers RSVP to a single occasion** (one wedding, one party) — not only multi-event listings, and not only ticketed events. An invitation with an RSVP is this vertical, not `forms`.
-- **Required site features:** the event's details and a way to register or RSVP. **RSVP events come with a built-in registration form** (name + email are always included), so the site needs an RSVP action — *not* a hand-built form with custom fields. For a multi-event site, also a list of events and a page per event.
-- **Implementation checklist:** show the event's title, date and time, and location; show the description; show ticket types where they exist (ticketed events); a register/RSVP action; collect additional-guest names where extra guests are allowed; a confirmation after registering.
-
-### bookings — appointments and classes
-- **Intent:** book / appointment / schedule / class / session / reserve a slot — a **service or appointment with a provider** (a stylist, trainer, tutor, clinic, studio).
-- **Not bookings — route to `restaurants` instead:** a **table at a restaurant** is a Table Reservations concern, not a bookable service; and a **special dining occasion guests reserve** — a chef's table, cheese pairing, or tasting-menu evening at a restaurant — is a **restaurants → Table Reservations *experience*** (see the restaurants entry), **not** a bookings service. Reach for `bookings` only when what's booked is a standalone service/class with a provider, never a seat at a restaurant.
-- **Not bookings — route to `rentals` instead:** when the **customer chooses how long** they want something, and what's booked is a **thing rather than a person** — a room by the hour, a desk for three days, a van for the weekend. The tell is a duration *range* the customer picks within. A 60-minute haircut is `bookings`; a meeting room booked for 1–8 hours is `rentals`.
-- **Required site features:** a list of services; a page per service; a way to pick a time and book it.
-- **Implementation checklist:** show each service's name, duration, and price; show the staff or provider; show the available time slots; a book action; a confirmation after booking.
-
-### rentals — rent a room, vehicle, or piece of equipment
-- **Intent:** rent / rental / hire / lease / "by the hour" / "by the day" / hourly or daily rate / **customer picks how long** — plus the things people rent: meeting room, conference room, co-working desk, hot desk, studio, hall, venue, workspace, vehicle, van, car, boat, bike, equipment, gear, camera, tool. Reach for it whenever what's booked is a **resource** (a room, vehicle, or item) for a **length the customer selects within a range**, not a fixed session with a provider.
-- **Not rentals — route to `bookings` instead:** a session whose length the **business** fixes, delivered by a **person** (a 60-minute massage, a class, a consultation). The word "rent" in a brief sometimes describes the *business model* ("we rent out desks") while the thing being sold is really a fixed session — decide on the **duration model**, not the vocabulary.
-- **Required site features:** a list of rentable items; a page per item; a way to pick a start **and a length** (an end time or an end date) and book it. A rental is priced per hour or per day, so the site must show the **computed total for the chosen length** before the customer commits — a per-unit price alone is not enough.
-- **Implementation checklist:** show each item's name, description, and **per-hour or per-day rate** (say which); show the item's attributes where they exist (capacity, amenities, equipment type); show available start times, then the valid lengths for the chosen start; show the running total for the selected length; a book action; a confirmation after booking.
-- **One unit type per item** — an item is rented by the hour *or* by the day, never both. When a brief wants both for the same room, that's **two** rentals, each with its own rate.
-
-### pricing-plans — memberships and subscriptions
-- **Intent:** membership / subscription / plans / paid tiers.
-- **Required site features:** a plans / pricing page; a way to choose and subscribe to a plan. **Subscribing requires a logged-in member** — the plans grid is public, but the *subscribe* action and any *my subscription* surface need the **members** cross-cutting capability (below); it's a hard dependency, not optional.
-- **Implementation checklist:** show each plan's name, price, and billing cycle; list what each plan includes (the perks); a clear "choose plan" action; highlight a recommended tier where it makes sense.
-
-### restaurants — menus and food
-- **Intent:** menu / restaurant / cafe / food / dish list / order food / dine-in / **reserve a table** / a **special dining occasion guests reserve** (chef's table, cheese pairing, tasting-menu evening).
-- **Required site features:** a menu organized into sections; each item with a name, description, and price. **Add-ons, each on demand (separate apps/features; see `SETUP.md`):** online ordering, table reservations, and — **when the brief names special dining occasions** — **experiences** (a reservation that *is* a curated occasion at the restaurant, e.g. a chef's table), which ride on the Table Reservations app.
-- **Experiences vs bookings — decide here:** an **experience** is a **reservation that is itself a special dining occasion at the restaurant** — it books seats at the restaurant's own location and carries its own name, per-guest price, schedule, and booking form. Use it for pairing sessions, tastings, and chef's tables. Use the separate **`bookings`** vertical only for a **service/appointment/class with a provider** that isn't a seat at the restaurant. For anything a restaurant hosts and seats, prefer an experience.
-- **Implementation checklist:** show the menu grouped into sections in order; each item's name, description, price, and labels (vegan, spicy…) and modifiers / variants where they exist; an order action if online ordering is wired; a reserve-a-table action if reservations are wired; **if experiences are wired, list each experience with its name, description, per-guest price, and schedule, and a reserve-seats action.**
-
-### portfolio — showcase projects
-- **Intent:** portfolio / showcase / gallery of projects / creative work / case studies.
-- **Required site features:** a gallery of projects; projects grouped by collection; a page per project.
-- **Implementation checklist:** show each project's cover, title, and description; group / filter by collection; on the project page show its details (role, year…) and media in order with a viewer / lightbox; a clear path back to the gallery. (Text-only seed shows the structure; media is omitted.)
-
-## Cross-cutting capabilities — usable, but ride on a parent vertical
-
-These are **not standalone verticals** — they aren't seeded on their own and don't go in `verticals[]`. Most have no app to install (eCommerce installs as a dependency; coupons need no install; members' identity layer is the OAuth app). But they **are fully usable**, and the agent should reach for them when a built vertical is present and intent calls for them. They attach to whatever catalog vertical the run already set up. Don't list these as "not-yet-wired" — they're wired *through* their parent. (One conditional install exists: the **members** *profile* layer needs the Wix Members Area app — see its entry and `SETUP.md`.)
-
-- **eCommerce** — the shared cart, checkout, orders, and payments layer. It has no catalog of its own; it's **installed automatically as a dependency** by Stores, Bookings, and Events, and it's how every purchase actually completes. The frontend uses it via `@wix/ecom` (+ `@wix/redirects`) — already carried in the Handoff for those verticals. Reach for the eCommerce Cart/Checkout APIs (find the *how* in the docs) whenever a purchase flow needs to be built or customized. *Intent: checkout / cart / "let people buy".*
-- **coupons** — discount codes and promotions applied at checkout. **No standalone app** — requires a parent already installed (stores / bookings / events / pricing-plans). When intent calls for discounts and such a parent is present, **create coupons on demand** scoped to that parent — find the create method in the docs (`DOC_DISCOVERY.md`) and surface `@wix/marketing` in the Handoff. *Intent: coupon / promo code / discount.*
-- **members** — the **identity layer**: member sign-up / log-in / log-out and member-gated surfaces. **Not seeded, and login needs no app install** (it's the headless OAuth app) — so it doesn't go in `verticals[]`. **Reading member profile data** (name / photo / roles / badges, an editable my-account page), however, needs the **Wix Members Area app installed** (`SETUP.md`) — keep the identity layer and the profile layer separate. Sign-up and log-in are the **same** mechanism (one login page logs in *or* registers). Two things vary. **(1) The frontend axis** — Astro ships built-in `/api/auth/login` routes, non-Astro drives a manual `OAuthStrategy` handshake (the two `how-to-code-members-*.md` recipes). **(2) The login *surface*, chosen by intent — not by project type.** The default is the **Wix-hosted login page** (zero UI to build); reach for a **custom login page** (you build a branded/in-app form, and can collect custom sign-up fields like full name / username / address) **only when the brief explicitly asks for a custom login form or custom sign-up fields** (`how-to-code-members-custom-login.md`). Custom login works on **any** project type (managed or self-managed) — the choice is the user's stated intent, so don't gate it on managed-vs-self-managed. **Hard dependency edge → pricing-plans**: subscribing to a plan requires a logged-in member, so whenever `pricing-plans` is present, members is implied (surface login + my-subscription). **Soft edges** to the other verticals' "my …" surfaces (my orders / my bookings / my registrations) and to **blog comments** (see the blog recipe) — the action runs as an anonymous visitor; only the account view of it needs a member. A logged-in member reading **their own** data needs **no `auth.elevate`** (that's the separate admin/permission axis). *Intent: login / sign up / account / my profile / members area / member-only / gated content / subscriber / paywall — plus any pricing-plans intent (membership / subscription / paid tiers), which can't be purchased without it.*
-
-## Other verticals — recognized for intent, not yet wired
-
-If a user's intent points squarely at one of these, surface it plainly as **not-yet-wired** rather than forcing a poor fit. Extending the skill to one means adding its install in `SETUP.md` and its seed *what* in `SEED.md`, then giving it a full section above. Each entry below names the **blocker** that kept it out — read it before promising anything. Where an API path genuinely exists, the agent **may wire it ad hoc from the live Wix docs** (find the REST create method via `DOC_DISCOVERY.md`, and the SDK module as in `SDK_HANDOFF.md`), but it must state the blocker honestly rather than promise a complete site.
-
-- **forum** — community discussion boards: categories, threads, member posts. **Deprecated** — the Forum APIs are being discontinued and there's no headless create-post path; the Groups replacement exposes no public create-post API. Don't wire; if discussion is essential, suggest blog comments or a custom solution. *Intent: forum / community / discussion board.*
-- **benefit-programs** — Wix Loyalty: points, rewards, and tiers that grant members perks. **Program activation is dashboard-only** — it can't be fully bootstrapped headlessly — but once loyalty is active, rewards/tiers have REST/SDK (`@wix/loyalty`) the agent can seed from the docs. *Intent: loyalty / rewards / member perks / benefits.*
-- **suppliers-hub** — supplier-side B2B product catalog management. **Partner-only** — requires a signed business agreement with Wix and isn't installable on a normal metasite; out of scope unless the user is an approved Wix partner. *Intent: supplier / wholesale / B2B catalog.*

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

@@ -1,36 +0,0 @@
-# Content — default copy quality bar for the built frontend (managed create)
-
-**Applies when this skill writes frontend page copy from scratch** (managed `create`, `CREATE.md` §4) — hero/section headlines, subtitles, kickers, CTA labels, and any image captions the pages include. Same scope as `DESIGN.md`: not `connect`/`iterate` (the copy already exists there).
-
-**Same precedence rule as `DESIGN.md`: fallback, not override.** If the user supplied their own copy, brand voice, or tone direction, use theirs — don't overwrite it to match the conventions below. The one exception is **§1** — a comprehension floor, not a style preference: whatever the voice, a first-time visitor must still be able to tell what the business *is* from the hero.
-
-## 1 · Say what the business is — explicitly, above the fold
-
-- A first-time visitor must know what the site *is* and what they can *do*, straight from the hero — never left to infer from mood or voice alone.
-- The **business category** (e.g. "yoga studio", "restaurant", "construction services") must appear **literally** in at least one of: the H1, a kicker above the H1, or the **first clause of the subtitle**. A witty H1 alone is not enough.
-- The **subtitle leads with the offer**, in plain language, before any flavor — put the verb the visitor actually cares about early ("Book…", "Order…", "Learn…", "Hire…").
-- Voice-driven, evocative H1s are welcome — but only when the category sits explicitly right beside them (kicker or subtitle). When in doubt, name the category in the kicker.
-
-## 2 · Kickers (micro-copy above titles)
-
-- **Cut a kicker that only restates the title** (e.g. "The Courses" above a Courses heading) — it adds nothing.
-- **Keep a kicker that carries real information**: category + location ("Yoga Studio · Downtown"), a feature's proper name, event details, dates, price framing.
-- A kicker is the right place to satisfy §1 when the H1 itself is voice-led rather than literal.
-
-## 3 · Titles, subtitles, paragraphs, CTAs
-
-- **Titles and subtitles end without a period.** Paragraphs (full running sentences) keep theirs.
-- No fluff — every line should move the visitor's understanding forward, the H1 and subtitle most of all.
-- **CTA labels are short and avoid all-caps** unless a specific reason demands it (readability). Word them to the actual action (ties to `DESIGN.md` §2's "one primary CTA, worded to the action" rule) — not generic verbs.
-
-## 4 · Images — the real subject comes first
-
-- **At least one image on the page must show the real story of the business** — the actual thing, not just abstract graphics, dashboards, or decorative art. A climbing outfitter shows mountains and climbers; a clinic shows the room; a workshop shows the tools and hands at work.
-- **Decorative/supporting visuals (illustrations, icons, patterns, textures) layer in *addition to* the real subject, never *instead of* it.** They earn their place by reinforcing the story and mood once the business is genuinely shown — not by standing in for it.
-- Imagery (real or decorative) matches the tone, voice, and era of the business.
-- When the user must supply their own real photos (the business has a specific, particular space/product/person that generated imagery can't stand in for), use a **fillable image slot with a descriptive placeholder** naming exactly what belongs there — not a generic stock image presented as final.
-
-## 5 · Image captions
-
-- A caption describes what is **actually seen** in its image. Tone can vary (serious, playful, informative) but must stay aligned with the image's real content.
-- **No meaningless captions, and no caption that ignores the image.** A slogan or pull-quote overlaid on a photo is not a caption — if a true caption is wanted, write one that describes the scene once the real image is in place.

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

@@ -1,55 +0,0 @@
-# Design — default visual quality bar for the built frontend (managed create)
-
-**Applies when this skill builds the frontend from scratch** (managed `create`, `CREATE.md` §4). It does **not** apply to `connect`/`iterate` — there the design already exists (brought in by the user), and the job is wiring, not designing (`CONNECT.md` §4).
-
-**This is a fallback, not an override.** It fills the gap **only when the user gave no design direction of their own** — no palette, no "make it dark/minimal/playful," no reference site or screenshot, no brand guidelines. The moment the user specifies *any* of that, their explicit intent wins outright — don't apply a rule below just because it's here if it contradicts what they asked for. Two exceptions that hold regardless of what's requested: **§3 (accessibility)** is a hard floor — if a user-requested palette fails contrast, fix the specific pair to comply, don't ship a violation — and the **anti-genericism intent** of §1 (derive tokens from *this* brand, don't reuse the last project's look) still applies even when the user supplied their own palette/theme, since it's about not being lazy with *their* inputs, not about overriding them.
-
-This is the **agent's own design-tokens contract** — it's the thing `IMAGE_GENERATION.md` and `DISCOVERY.md` §4 already assume exists when they say a themed-block fallback "follows the site's own design tokens (palette, radius, spacing)". Decide the tokens below *before* writing the first component; every page and fallback then draws from that one decision instead of improvising per-component.
-
-## 1 · Decide the design tokens once, before any component
-
-A short, explicit decision — a few lines, not a document — derived from `brand.description`/`brand.vibe` (`DISCOVERY.md` §2):
-
-- **Theme polarity** — light, dark, or vivid/tinted. Argue it from the business, never default to dark for "premium" (a light, high-key theme can be just as strong — e.g. healthcare/wellness usually reads better light).
-- **Palette** — 2–4 hex colors, one dominant + accents drawn from **analogous hues** (adjacent on the color wheel, ~30° arc) — not complementary jumps. Functional colors (error/success/warning) sit outside this count.
-- **Type scale** — one heading scale + one body size. Body text floor: **16px, 1.5 line-height** (§3 is non-negotiable, this is where you set it).
-- **Radius + spacing** — pick once (e.g. "12px radius, 24px section padding") and reuse everywhere; don't let each component invent its own.
-
-Hold these as the run's design tokens. Reuse them literally in the themed-block fallback (`IMAGE_GENERATION.md`) and every page — don't re-derive per page.
-
-**Vary this across projects.** Don't reach for the same palette/theme/layout on every build — derive it from *this* brand's vibe each time. Repeating the same look across unrelated projects is a failure mode, not a shortcut.
-
-## 2 · Layout (hard rules)
-
-- **Full-bleed, not boxed.** Don't wrap the page in a narrow centered container (no `max-w-4xl mx-auto` outer shell). Design for the full viewport; use the peripheral space intentionally.
-- **One primary CTA per page**, worded to the page's actual action — `Book a Table`, `Add to Cart`, `Reserve Your Spot`, not generic verbs ("Submit", "Click here", "Go").
-- **Icons never sit on a filled/tinted background shell** — no circle/square/pill behind a nav or card icon. The glyph renders directly on the surface.
-- **Identify the site's 3–4 core pages/sections from its resolved vertical** (`verticals[]`, `DISCOVERY.md` §1) before laying out anything, and design each to its own intent:
-
-  | Vertical | Core pages/sections to get right |
-  |---|---|
-  | stores | Home hero, product grid, product detail, cart |
-  | blog | Post list, post detail |
-  | cms | Collection list, item detail |
-  | forms | The form itself — clear single-column, one obvious submit |
-  | events | Event list, event detail + RSVP |
-  | bookings | Service list, booking widget/flow |
-  | rentals | Rentable-item grid, item detail (rate + attributes), date/length picker showing the running total |
-  | pricing-plans | Plan comparison, checkout/signup |
-  | restaurants | Menu, reservation/ordering flow |
-  | portfolio | Project grid, case-study/project detail |
-
-## 3 · Accessibility (hard rules, no exceptions)
-
-- **WCAG 2.2 AA contrast** — every chosen background/foreground pair must hit **4.5:1** for body text, **3:1** for large text (≥24px or ≥19px bold). Check the actual hex pair against the ratio — don't assume a palette is accessible because it "looks fine."
-- **16px minimum body font**, **1.5 minimum line-height** for body copy.
-
-## 4 · Content & imagery hygiene
-
-- **No emojis** in UI copy, headings, or empty states.
-- **No stock-photo clichés** — generic handshake/lightbulb/laptop-on-desk imagery reads as filler, not a real page.
-- Generated imagery already carries its own purity rule (no text/logos/watermarks/UI-mockups — `IMAGE_GENERATION.md` § Prompts, "no text, no watermarks"); nothing additional to do here beyond following that section as written.
-
-## What this doesn't cover
-
-This is a floor, not a template library — it constrains the *how* (contrast, layout shape, token discipline), not the *what* (that's `verticals[]` + `brand` from Discovery, and the user's intent). Two builds with the same vertical and different brand vibes should still look nothing alike.

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

@@ -1,80 +0,0 @@
-# Discovery — infer, don't interview
-
-The run starts here. **Infer** the Wix capability set, the brand, and per-capability intent from the user's words (and, optionally, the project on disk). Inference is just the first step — its output **drives Setup (install apps) and Seed (create content)**, which are the actual work; flow straight through into them. The host already has the user's buy-in to add Wix, so resolve everything from what's given and keep moving; when something isn't specified, use the defaults below.
-
-Discovery is pure inference — it needs **no authentication** and is **agnostic to the project type**. The token and metasite id are obtained later, at Setup, via the provided authentication mechanism.
-
-## 1 · Resolve the capability set
-
-> **Targeting an existing site with an ambiguous brief? Read the site — don't guess.** When the
-> run points at a site that already exists (connect/iterate, a funnel-created site) and an
-> elevated credential is already available, one documented call returns the site's context —
-> installed apps by name (including the Stores catalog version), status, URL,
-> locale/currency/timezone, and CMS collections — as an agent-ready markdown report:
->
-> ```bash
-> curl -sS -X POST 'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
->   -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
->   -d "{\"siteId\": \"$SITE_ID\"}"
-> ```
->
-> Docs: <https://dev.wix.com/docs/api-reference/tools/dynamic-site-context/get-dynamic-context-markdown.md>
-> (a JSON variant lives at the same path without `/markdown`). With an API key, send it raw as
-> the `Authorization` header value, no `Bearer` prefix.
->
-> The installed business apps map to the vertical set and seed `verticals[]` directly (CMS
-> collections present → cms); inference below then only fills what the site can't answer
-> (brand, per-capability intent). Several verticals installed → prioritize by the user's words
-> and by which holds real (non-sample) content. Nothing relevant installed → **ask the user one
-> short question** ("what do you offer — products, appointments, posts, events?") rather than
-> defaulting to a store. This is the one case where Discovery may use the authentication
-> mechanism early; with no credential at hand yet, skip it and infer from the words as below.
-
-Read the **user intent** (+ optional project signals: `package.json` name, README, visible copy) against the vertical index in `references/CAPABILITIES.md` — each entry there carries the intent signals that point to it. Pick every vertical that genuinely fits → `verticals[]`. Multiple signals → multiple capabilities. On ambiguity, prefer the more specific vertical; if nothing dynamic is named, fall to the **forms** floor (a contact form). **Never return an empty set.**
-
-Resolve to the skill's operational set — **stores · blog · cms · forms · events · bookings · rentals · pricing-plans · restaurants · portfolio · donations** (`CAPABILITIES.md` § "Built verticals"). If intent points squarely at a vertical outside that set, note it plainly as not-yet-wired (per the index) and resolve the rest; don't force an unrelated capability in its place.
-
-## 2 · Infer brand
-
-A short brand object for seeded-content naming: `{ name, description, vibe? }`. Source from the intent text and any project signals (the package name, a README title/tagline, headline copy). If nothing is available, derive a neutral name from the project directory. This is only used to make seeded content read naturally — keep it light.
-
-## 3 · Derive per-capability intent
-
-For each capability, build its `intent.<cap>` block — the inputs the seed step translates into REST calls. Use sensible brand-appropriate defaults when the user didn't specify counts:
-
-| Capability | `intent.<cap>` shape | Defaults when unspecified |
-|---|---|---|
-| stores | `{ productCount, categoriesNamed: [] }` | `productCount: 3`, `categoriesNamed: []` (no categories) |
-| blog | `{ postCount, topics: [] }` | `postCount: 3`, topics derived from `brand.description` |
-| cms | `{ collections: [{ name, purpose, itemCount, fields? }] }` | one collection inferred from intent, `itemCount: 5` |
-| forms | `{ forms: [{ purpose, fields: [...] }] }` | one `contact` form: name, email, message |
-| events | `{ eventCount, titles: [] }` | `eventCount: 2`, titles brand-derived, future dates |
-| bookings | `{ serviceCount, servicesNamed: [] }` | `serviceCount: 2`, brand-derived service names |
-| rentals | `{ unitType, serviceCount, resourceCount, servicesNamed: [] }` | `unitType: "HOUR"` (`"DAY"` if the brief rents by the day), `serviceCount: 2`, `resourceCount: 2`, brand-derived item names |
-| pricing-plans | `{ planCount, tiersNamed: [] }` | `planCount: 2` (e.g. Basic / Pro), monthly billing |
-| restaurants | `{ menuName, sections: [{ name, itemCount }], ordering?, reservations?, experiences?: [{ name }] }` | one menu, 2 sections, `itemCount: 3` each; add-ons only when the brief names them. **`experiences[]`** = special dining occasions guests reserve (chef's table, tasting menu) — a restaurant *reservation that is an experience*, **not** the `bookings` vertical (see `CAPABILITIES.md`). |
-| portfolio | `{ collections: [{ name }], projectCount }` | one brand-derived collection, `projectCount: 3` |
-| donations | `{ campaigns: [{ name, frequencies?, presets?, customAmount?, goal?, comments?, askCoverFee? }] }` | Reuse existing campaigns. For an authorized new setup, one cause; use only approved amounts/impact claims/goals and offered frequencies. Do not invent fundraising facts. |
-
-Counts are deliberately small (the seed shows the shape, not a full catalog).
-
-## 4 · Imagery (opt-in)
-
-Resolve an `imagery` flag — whether to generate AI images for seeded content (and, when building a frontend, for page surfaces). **Default OFF** (text-only): seed with no imagery; the user can add images later.
-
-- If the prompt **signals imagery** ("with photos", "product photos", "AI images", "hero image"), set `imagery: on`.
-- Otherwise **ask one question** — text-only (default) vs AI-generated images, noting it costs ~1 Wix AI credit per image. Default to off on no answer.
-
-**Bound the *cost*, not just the on/off decision.** `imagery: on` authorizes the *feature*, not unlimited *volume* — a single "imagery throughout" phrase can otherwise fan out to dozens of images (≈1 Wix AI credit each) with the spend never surfaced. So when imagery resolves on:
-
-- **Surface the projected cost** in the brief pre-work line (§5): state the plan in credits — *"~N images ≈ N Wix AI credits"* — so the spend is visible even when nobody asked about volume. Always safe, no interactivity.
-- **Apply a per-run image cap** (`imageCap`, default **~12**). Generate up to the cap; for surfaces/entities beyond it, render the **themed-block fallback** instead of generating (see below). Log what was capped so it's not silently dropped.
-- **Confirm only when interactive *and* over the cap** — never a mandatory "always ask" gate. A non-interactive run honors the cap and fills the rest with themed blocks; it never stalls.
-
-**Themed-block fallback (the not-generating path).** Whenever an image is *not* generated — imagery off, over the cap, declined, or a generation failure — a **frontend** image slot renders a **styled `div` that follows the site's own design tokens** (palette, radius, spacing, maybe a label or gradient), *not* an empty slot or a broken `<img>`. The layout stays intentional and on-brand at **zero credits**, and it's deterministic/headless-safe. (This applies to page surfaces; a *seeded entity* with no image simply stays text-only — `SEED.md` § "Entity images".)
-
-When `imagery` is on, `SEED.md` attaches images to seeded entities and `IMAGE_GENERATION.md` is used for any page images a frontend build calls for (including the cap + themed-block mechanics). Hold `imageCap` alongside `imagery` in scratch. This flag is project-type-agnostic.
-
-## 5 · Hold the contract, proceed
-
-Hold in scratch: `verticals[]`, `brand`, `intent.<cap>` per capability, and `imagery`. The metasite id (`SITE_ID`) and the token are obtained at Setup via the provided authentication mechanism. Then **continue to `SETUP.md`** and install the apps — this is the start of the actual work, not a separate decision. A brief plain-prose line stating what will be set up is fine.

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

@@ -1,43 +0,0 @@
-# Doc discovery — the shared fallback (seeding *and* code-writing)
-
-You're here because a **pinned** page or recipe didn't cover what you need — a field, an endpoint,
-an error, or an unpinned method. Doc discovery is the **fallback for both tracks**, never the first
-move:
-
-- **Seeding** → read the capability's **inline recipe** — `inline-recipes/setup-*.md`, mapped in
-  `SEED.md` § "What to seed per capability". Each built capability is a **self-contained local recipe** that inlines the calls
-  and **supersedes** the REST doc pages — seed from it alone. Only a capability with **no** inline
-  recipe (e.g. `coupons`) discovers from the live docs (below).
-- **Code-writing** → try the pinned pages in `astro.md` / `non-astro.md` + `inline-recipes/*`.
-- Only when those fall short, discover from the live docs (below).
-
-The **`wix-docs`** skill is the full playbook (`../wix-docs/SKILL.md` when co-installed). The short
-version:
-
-**1. Find a page — semantic `curl` search (no MCP required):**
-
-```bash
-curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown' \
-  -H 'Content-Type: application/json' \
-  --data-raw '{"search_term":"<what you need, in natural language>","document_type":"WIX_HEADLESS","maximum_results":3}'
-```
-
-`document_type`: `SDK` / `WIX_HEADLESS` for code-writing, `REST` / `BUSINESS_SOLUTIONS` for seeding,
-and `SKILLS` for a **multi-step workflow no pinned recipe covers** — it searches the dedicated recipe
-corpus (step ordering, cross-step gotchas), which a `REST` search does not return (also `VELO` ·
-`WDS` · `BUILD_APPS` · `CLI` · `OVERVIEW`). Drop `/markdown` for JSON hits. Found a recipe → resolve
-its individual calls against `SDK`/`REST` docs; no recipe → assemble the flow from verified
-per-method contracts.
-
-**2. Read a page** — append `.md` to its docs URL. **For an SDK shape, append `.md?apiView=SDK`** —
-the SDK view shows `_id` (what the frontend calls), the bare view shows `id`.
-
-**3. Exact structured schema / enums (no MCP)** — `POST https://mcp.wix.com/api/code-mode/search`
-with `getResourceSchemaByUrl(docsUrl)` (see `wix-docs`'s `API_SPEC_SEARCH.md`).
-
-**If the host has the Wix MCP**, its `SearchWix*` / `SearchWixAPISpec → getResourceSchemaByUrl`
-tools are the same backends without the `curl` boilerplate — prefer them when present, per `wix-docs`
-Lane 2. `getResourceSchemaByUrl` scopes to the URL: a method URL → that method's contract; a
-resource URL → the whole resource (fetch that for sibling operations).
-
-**A page that IS pinned → read it directly; don't re-search for it.**