@wix/agent-skills 1.14.0 → 1.15.0

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

@@ -0,0 +1,178 @@
+# 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

@@ -0,0 +1,84 @@
+# 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 · pricing-plans · restaurants · portfolio** (with `forms` as the floor when nothing richer is named).
+
+### stores — sell products
+- **Intent:** sell / shop / products / catalog / merch / store.
+- **Required site features:** a product list or grid; a page per product; categories to browse by; a cart; a checkout.
+- **Implementation checklist:** show each product's image, name, and price; show options and variants (size, colour…) where they exist; show availability / out-of-stock; a quantity picker and an add-to-cart that updates a visible cart; the product description; link each product to its category.
+
+### 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 — capture leads
+- **Intent:** contact / lead / signup / waitlist / "let people reach me" / generic custom data capture / nothing dynamic named. **Not for RSVP** — confirming attendance to an event or occasion (a wedding, party, or gathering) is the **events** vertical, which has a built-in RSVP registration form; route there even when it's a single occasion with no tickets. Use `forms` only when no event is involved.
+- **Required site features:** a visible form; a confirmation after submitting; basic field validation.
+- **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 / reserve a table.
+- **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.
+
+### 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.
+- **Required site features:** a menu organized into sections; each item with a name, description, and price. (Online ordering and table reservations are optional add-ons — separate apps; see `SETUP.md`.)
+- **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.
+
+### 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/DISCOVERY.md

@@ -1,76 +1,54 @@
-# Discovery
+# Discovery — infer, don't interview
 
-Capture brand + vibe + imagery + the per-vertical intent inferred from the user's prompt, present a slim plan, get approval, hold the captured contract in orchestrator scratch.
+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.
 
-Infer as much as possible from the user's opening message; ask only what's genuinely unknown. Target: **~1:30 of discovery** including user think-time, **≤ 80 s** excluding it.
+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.
 
-This phase owns the *domain* of discovery only. Run FLOW — when background work is dispatched, what waits on what, batching, and the transition into Setup/Seed — is owned by `references/PLAN.md` (pre-approval, which routes on **operation** to `PLAN-create.md` / `PLAN-connect.md`) and `references/BUILD.md` (post-approval, which routes on **framework**).
+## 1 · Resolve the capability set
 
-**This file is the discovery router, and it routes on OPERATION.** It holds the two things every run does regardless of operation — **Wave 0 field resolution** and the **CLI-auth pre-flight** — then opens the operation-specific discovery file. The actual interview/parse + plan content lives in `DISCOVERY-create.md` (create) or `DISCOVERY-connect.md` (connect). Read only the matching one.
+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.**
 
-## Wave 0 — Resolve `operation`, then `frontend` (BEFORE any user-facing question)
+Resolve to the skill's operational set — **stores · blog · cms · forms · events · bookings · pricing-plans · restaurants · portfolio** (`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.
 
-Discovery routes on **operation** — *create* (the skill writes a new site from a prompt) vs *connect* (the user brings a finished design to wire to Wix). Resolve `operation` **first** from the user's prompt AND the working directory, then derive `frontend` (and `frontendBuild`) *within* that operation. Operation and framework are **orthogonal axes**: `frontendBuild` (`wix`/`none`/`own`) is derived inside the chosen operation, not implied by it — *create + framework-keyword* → `own`, *connect + SPA* → `own`, *connect + static HTML* → `none`, *create + default* → `wix`. Resolving operation first (then framework within it) is the seam that keeps the operation router untouched as frameworks are added (the framework-SPA plan; the extend plan).
+## 2 · Infer brand
 
-> **Intent is primary; the directory only confirms.** The bug to avoid: an *empty* CWD does **not** automatically mean create. If the prompt brings a design to connect — even one that will be **fetched into the empty dir** — it's connect. Read the prompt first.
+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.
 
-```
-Read the prompt, then inspect CWD — resolve OPERATION:
+## 3 · Derive per-capability intent
 
-1. CONNECT/IMPLEMENT-AN-EXISTING-DESIGN intent in the prompt → operation: connect,
-   EVEN IF THE CWD IS EMPTY. Signals: "connect this to wix", "implement this design",
-   "host/deploy this site", "this is a working site", or a design-file URL to fetch +
-   implement (Claude Design / v0 / Lovable / any tool). The design arrives by fetch into
-   the empty dir — emptiness at check time does not make it create.
-2. CWD already contains a working frontend (`index.html`, `*.html`, `*.jsx`/`*.tsx`/`*.vue`,
-   a design-handoff bundle) → operation: connect — connect the brought-in site.
-3. CWD contains `wix.config.json` → an existing wix-headless project (resume/extend; see
-   SKILL.md § "When NOT to use this skill" — out of pivot scope for now; the extend plan
-   adds `operation: extend` here, ahead of the emptiness tests).
-4. Otherwise — empty CWD AND a CREATE-A-NEW-SITE prompt ("build me a store", "I want to
-   sell tables online", "make a blog") with no design to connect → operation: create.
-```
+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:
 
-Then derive `frontend` and `frontendBuild` **within** the chosen operation, and capture all three in session scratch (the Plan→Build contract core, `PLAN.md` § "The Plan→Build contract"):
+| 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 |
+| pricing-plans | `{ planCount, tiersNamed: [] }` | `planCount: 2` (e.g. Basic / Pro), monthly billing |
+| restaurants | `{ menuName, sections: [{ name, itemCount }] }` | one menu, 2 sections, `itemCount: 3` each |
+| portfolio | `{ collections: [{ name }], projectCount }` | one brand-derived collection, `projectCount: 3` |
 
-> **Within `create`, branch `frontendBuild` on an explicit framework keyword.** A create prompt that **explicitly names a client-build framework** — `vite`, `react`, `vue`, `svelte`, "SPA", or similar (the same keyword set the connect SPA detector uses) — resolves to **`frontend: custom`, `frontendBuild: own`** (scaffold that framework, then connect via the SPA spine). A create prompt with **no** framework keyword stays **`frontend: astro`, `frontendBuild: wix`** — astro remains the default for a bare *"create a bakery site"*. **Only an explicit keyword flips it** — never infer a framework the user didn't ask for. A framework keyword on a *connect* prompt still routes to connect (the brought-in SPA), per `DISCOVERY-connect.md` § 1.5.
+Counts are deliberately small (the seed shows the shape, not a full catalog).
 
-| `operation` | `frontend` | `frontendBuild` | Wave 0 next |
-|---|---|---|---|
-| `connect` — connect/implement an existing design, OR a working site on disk | `custom` | `none` (static HTML) **or** `own` (framework SPA) — resolved from disk in `DISCOVERY-connect.md` § 1.5 | Pre-flight, then **`DISCOVERY-connect.md`** |
-| `create` — create-a-new-site prompt, **no** framework keyword (the default) | `astro` | `wix` | Pre-flight, then **`DISCOVERY-create.md`** (astro branch) |
-| `create` — create-a-new-site prompt that **explicitly names a client-build framework** (*"…using vite"*) | `custom` | `own` | Pre-flight, then **`DISCOVERY-create.md`** (own branch — minimal scaffold; runs vibe + Designer for brand tokens, but not astro `compose.mjs`) |
+## 4 · Imagery (opt-in)
 
-> **No `AskUserQuestion` for operation/frontend detection.** They are inferred from the prompt + directory, never asked. When intent is unclear, default to `operation: connect` — connecting/implementing what the user brings is the safe interpretation; creating a brand-new site over their intent is the destructive one. **A prompt that fetches or names a design to "connect"/"implement" is `connect` regardless of whether the CWD is empty.**
+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.
 
-These flow into:
-- The **Plan→Build contract** held in orchestrator scratch (`PLAN.md` § "The Plan→Build contract"). `frontend`, `operation`, and `frontendBuild` all live in scratch — **none** is persisted to disk. The conductor reads `frontendBuild` from scratch to decide whether to run `wix build` before release — `wix` builds, `none` doesn't.
-- **Bootstrap is (operation × framework)-keyed** (`BUILD.md` § "Bootstrap cell"): create+astro runs `scaffold.sh --frontend astro`; create+own runs the framework's own create command (`npm create vite`/…) then `init`; connect (own/none) does **not** scaffold — it bootstraps via `npm create @wix/new@latest init` over the brought-in/scaffolded source.
-- Orchestrator session scratch — every downstream branch reads the scratch values. For `connect`, the frontend track runs the connect flow (`references/custom/INSTRUCTIONS.md`); the create-only project-prep (`seed-utilities.sh`) and the Designer/Composer do not run. (Business-track steps — app install, seeders — never read these fields.)
+- 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.
 
-## Pre-flight — Verify CLI auth (BEFORE any user-facing question)
+**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:
 
-The first Wix touch is the post-approval project bootstrap — create/astro: `scaffold.sh` → `npm create @wix/new@latest headless`; connect: `npm create @wix/new@latest init` — which creates a business + project against the user's Wix account and so requires an active CLI session. Without one it fails — and because the bootstrap runs **after** approval (`BUILD-astro.md` run-step 0 / the connect bootstrap cell, `BUILD.md` § "Bootstrap cell"), a logged-out user wouldn't find out until they'd done discovery *and* approved, only to have it fail immediately. Run the auth check foreground here (both operations) so a logged-out user sees the login prompt first.
+- **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.
 
-```bash
-npx @wix/cli@latest whoami >/dev/null 2>&1
-```
+**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".)
 
-- Exit 0 → open the matching operation discovery file (create → `DISCOVERY-create.md` Step 0; connect → `DISCOVERY-connect.md`).
-- Exit non-zero → **run `npx @wix/cli@latest login` yourself; do NOT punt to the user.** Steps:
-  1. `Bash` tool with command `npx @wix/cli@latest login`, `run_in_background: true`. No shell `&`, no `mktemp` redirect, no chaining.
-  2. Read the harness output-file path from the tool reply's `<bash-stdout>` (or use `TaskOutput`).
-  3. Parse line 1 for `{"event":"awaiting_user","userCode":"…","verificationUri":"…"}` (ignore any `TimeoutNaNWarning` on later lines).
-  4. Surface in one plain-prose message — *not* `AskUserQuestion`: *"Open `<verificationUri>` in your browser and enter the code `<userCode>` — I'll continue once you've completed the login."*
-  5. Wait for the harness `task-notification` with `<status>completed</status>`; confirm with `whoami`, then open the matching operation discovery file.
+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.
 
-  Full recovery reference: [`shared/AUTHENTICATION.md`](shared/AUTHENTICATION.md#wix-login-from-a-non-interactive-agent).
+## 5 · Hold the contract, proceed
 
-## Next — open the operation-specific discovery
-
-With `operation` (and the derived `frontend`/`frontendBuild`) resolved and auth confirmed:
-
-- **`create`** → `DISCOVERY-create.md` — the interview (Steps 0–2.5) → plan → approval → hold the contract in scratch.
-- **`connect`** → `DISCOVERY-connect.md` — parse the brought-in site → infer domain → light plan → approval → hold the contract in scratch.
-
-Read only the matching file. The pre-approval funnel (`PLAN-create.md` / `PLAN-connect.md`) names *when* to apply each discovery step.
+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

@@ -0,0 +1,37 @@
+# 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
+(also `VELO` · `WDS` · `BUILD_APPS` · `CLI`). Drop `/markdown` for JSON hits.
+
+**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 richer (whole-resource schema in one payload) — prefer them, per `wix-docs` Lane 2.
+
+**A page that IS pinned → read it directly; don't re-search for it.**

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

@@ -0,0 +1,118 @@
+# 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. 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 substantial friction** — repeated API failures, wrong/missing docs, a tooling dead
+  end, or a workaround you had to invent. When you notice the pattern, offer: *"This tripped us up a
+  few times — want me to send it to Wix as feedback?"*
+
+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.