@wix/agent-skills 1.16.0 → 1.16.2

package/skills/wix-docs/SKILL.md

@@ -7,7 +7,8 @@ description: "Look up the Wix API/SDK documentation to confirm an exact endpoint
 
 Get the **exact** truth about a Wix API — endpoint, HTTP method, request/response body, a field, an
 enum, or an error. **Never invent a Wix endpoint, path, body, or enum from memory** — confirm it
-here first.
+here first. That includes the example endpoints in this skill: they illustrate the mechanics and
+go stale like any snapshot — discover the real contract before you rely on one.
 
 A lookup is a short flow: **find the right page, then read it.** Do it with `curl` (default, below)
 or the Wix MCP doc tools if your agent has them (Lane 2).
@@ -212,6 +213,79 @@ when present, fall back to Lane 1 when not. Optional — skip this lane if the t
 Append `.md` only when `curl`-ing a page directly. The MCP tools and the search endpoint take the
 plain docs URL **without** `.md` — never feed a `.md` URL to an MCP tool.
 
+## From docs to calls
+
+The contract you just read runs under one of two identities — and which one a call wants is part
+of what you read:
+
+| identity | token | for |
+|---|---|---|
+| **admin** | an admin token (API key, connector, or OAuth-app admin grant) | managing the site — ad hoc calls, or the same fetch inside an app's backend function |
+| **visitor** | minted from the site's OAuth app, in frontend code | everything the site's end user does — storefront reads, cart, checkout |
+
+**Admin** — any management or read call, straight from its docs contract:
+
+```bash
+curl -sS -X POST 'https://www.wixapis.com/contacts/v5/contacts/query' \
+  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
+  --data-raw '{"query": {"cursorPaging": {"limit": 10}}}'
+```
+
+In a Wix CLI project, the CLI mints `$ADMIN_TOKEN` — at either scope:
+
+```bash
+TOKEN=$(npx @wix/cli@latest token --site "$SITE_ID")   # site-scoped: this one site's APIs
+TOKEN=$(npx @wix/cli@latest token)                     # account-scoped: account-level APIs (list sites, …)
+```
+
+Mint once per run and cache it — within a run the CLI returns a byte-identical token, so re-minting
+only spends startup time.
+
+**Visitor — minted from the OAuth app's client id.** The client id is a public value, and it is
+usually already on disk before it is in any API: in a managed headless project it is the `appId`
+field of `wix.config.json` — **the OAuth app id and the client id are the same value** — so read it
+from the project's config instead of querying the OAuth-apps API for it. The mint is one
+unauthenticated call, so it belongs in the site's own frontend code:
+
+```bash
+curl -sS -X POST 'https://www.wixapis.com/oauth2/token' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"clientId": "<oauth app client id>", "grantType": "anonymous"}'
+# → { "access_token": "OauthNG.JWS.…", … } — bearer for products, cart, checkout
+```
+
+The cart and checkout APIs act on the *caller's* identity, so they want the visitor token — the
+admin token is for managing the site, the visitor token is for being on it.
+
+The authentication docs (append `.md` to read):
+
+- [`about-identities`](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities) — the identity model
+- [`rest-api-authentication`](https://dev.wix.com/docs/api-reference/articles/authentication/rest-api-authentication) — headers, token kinds
+- [`retrieve-tokens`](https://dev.wix.com/docs/api-reference/business-management/headless/authentication/retrieve-tokens) — the `/oauth2/token` contract, all grant types
+- [`about-authentication`](https://dev.wix.com/docs/go-headless/authentication/about-authentication) — visitor vs member sessions
+- [`create-an-oauth-app-for-visitors-and-members`](https://dev.wix.com/docs/go-headless/getting-started/setup/authentication/create-an-oauth-app-for-visitors-and-members) — where the client id comes from
+- [`set-up-a-headless-client`](https://dev.wix.com/docs/go-headless/authentication/setup/set-up-a-headless-client) — wiring the client
+
+## Special APIs worth knowing
+
+**Dynamic Site Context — "what IS this site?"** One admin call returns a markdown report of the
+whole site — installed apps, status, URL, locale, CMS collections — the same output the Wix MCP's
+site-context tool renders:
+
+```bash
+curl -sS -X POST 'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
+  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
+  --data-raw '{"siteId": "<metasite id>"}' | jq -r '.markdown'
+```
+
+A `200` with `"markdown": ""` means the token or `siteId` is wrong — the endpoint reports an empty
+context instead of an auth error, so treat empty as "check auth", never as "empty site".
+
+For site management, the **`wix-manage`** skill carries per-area recipes. It may already be
+installed at
+`.agents/skills/wix-manage/`; install it with `npx -y skills add wix/skills/skills/wix-manage`,
+or read it straight off the registry: `https://www.wix.com/skills/wix-manage`.
+
 ## Before you write the code
 
 Confirm on the page — not from memory — the endpoint, the HTTP verb, the request body shape,

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

@@ -37,10 +37,23 @@ The verticals the skill operates end-to-end today: **stores · blog · cms · fo
 - **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.
+### 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.
-- **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.
+  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`.

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

@@ -58,7 +58,7 @@ The host binds to **schema**, not to a frozen list of content IDs. **Content is
 
 Carry only the **structural** carve-outs the coding step genuinely reads — the collection/form *names and keys* you must know to query and bind, which do **not** change when an owner adds a row:
 - **cms:** `collectionId` + field keys per collection
-- **forms:** **`formId` only.** The field set, order, labels, `required`, validation format, and dropdown options are **read live from the form schema at render time** (visitor token, no elevate — `how-to-code-forms.md`), so the handoff no longer carries per-field `target` keys. Reading the schema live is the source of truth: it closes the seed↔site drift by construction (a field the owner adds/removes/relabels in the dashboard reflects on the site with no code change) and is the more v2-aligned "host resolves everything else live" shape. (For a bespoke, design-led form where dashboard-editability isn't the value prop, the host may still hardcode inputs from the known `target`s — `how-to-code-forms.md` covers that mode — but the default and the carry is `formId` only.)
+- **forms:** `formId` + each form's field `target` keys (the submission keys the frontend binds `name` = target). Field set, labels, options, and validation (`required`, format, length/pattern) are read live from the schema (`how-to-code-forms.md`).
 
 Everything else the host resolves live from the queries in §3. (Static platform constants — Stores/Bookings app IDs, the Blog appDefId — and the public `clientId` are needed too, but they're identical for every site, not seed output; they're in §2/§3.)
 

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

@@ -34,7 +34,7 @@ Each entry states only the entities, where their count/content comes from, the p
 - **stores** — *A product catalog.* Recipe: **`setup-online-store.md`**. `intent.stores.productCount` products whose names/prices fit `brand`. If `intent.stores.categoriesNamed` is non-empty, create exactly those categories and assign products into them; **if empty, create none** (skill policy — overrides any docs default). **Variant cardinality — keep it small by default:** unless `intent.stores` calls for specific options, give each product **at most one option with ≤3 choices** (so ≤3 variants/product); many products legitimately have **no** options (a single variant). Seeding cost scales with the variant Cartesian product and the field count per variant, so don't manufacture options the brief doesn't need — but **honor a larger/explicit option set when intent names one** (this default is a floor, not a cap). Text-only by default (images only when `imagery` is on — §1, §4). **Keep (seed-time only):** `categoryIds[]` to assign products into their categories; **nothing goes to the handoff** — the frontend lists products and categories **live** (`queryProducts` / `searchProducts` / `queryCategories`), so owner-added products/categories appear with no code change.
 - **blog** — *Initial posts.* Recipe: **`setup-blog.md`**. `intent.blog.postCount` posts on `intent.blog.topics` (or brand-derived topics). Text-only (no covers). **Keep:** nothing for the handoff — posts are discovered **live** (`queryPosts`, `[...slug]` routes). Track created post ids only transiently (to confirm success / assign categories).
 - **cms** — *Content collections.* Recipe: **`setup-cms.md`**. One collection per `intent.cms.collections` entry; `itemCount` items each, content from `brand`. Collections are **public-read** (visitor reads on the frontend) by default. **(Opt-in, members only)** if the brief calls for per-user-private or member-only data **and** members login is in the run, seed that collection **member-scoped** instead (per-user or member-only — see `setup-cms.md`); a per-user collection is seeded **empty** (members populate it), since admin-seeded rows are owned by the admin. **Keep (→ handoff):** `collectionIds{<name>}` + each collection's **field keys** — this is *structural* (the frontend must know the collection name and its fields to query and bind; it doesn't change when an owner adds a row). `itemIds{<name>:[]}` only transiently, for wiring multi-references during seeding.
-- **forms** — *Lead-capture forms.* Recipe: **`setup-forms.md`**. One form per `intent.forms.forms` entry; fields from the entry; `purpose` names the form. **Keep (→ handoff):** `formIds[]` + each form's field **`target`** keys — *structural* (the frontend sets input `name` = target to submit).
+- **forms** — *Visitor-fillable forms.* Recipe: **`setup-forms.md`**. One form per `intent.forms.forms` entry; fields from the entry, `purpose` names the form. **Keep (→ handoff):** `formIds[]` + each form's field **`target`** keys — *structural* (the frontend binds each input's `name` = target to submit; targets are **immutable**, so they don't go stale when an owner relabels a field).
 - **events** — *A ticketed or RSVP occasion, or upcoming events.* Recipe: **`setup-events.md`**. Each event is **either `TICKETING`** (paid — it has ticket tiers) **or `RSVP`** (free — the registration form is built-in, so don't seed form fields) per intent. For an **RSVP occasion** (a wedding, party, gathering): one RSVP event with the occasion's real details (title, a **future** date/time, location). For a **ticketed** event: the event plus its ticket tiers (default a single `"General Admission"` tier if none named). For a **listing** site: `intent.events.eventCount` events with brand-appropriate titles and **future** start dates (a default location/timezone is fine). Text-only. **Keep:** nothing for the handoff — events and tiers are discovered **live** (`queryEvents`, `getEventBySlug`, `queryAvailableTickets`); track `eventIds`/`ticketDefinitionIds` only transiently.
 - **bookings** — *Bookable services.* Recipe: **`setup-bookings.md`**. `intent.bookings.serviceCount` services (name + short description fitting `brand`, a simple duration and price); keep the schedule minimal. **Keep:** `serviceIds[]` as **seed-time state** (pricing-plans' coverage step keys on them, below); nothing for the handoff — services are discovered **live** (`queryServices`).
 - **pricing-plans** — *Membership tiers.* Recipe: **`setup-pricing-plans.md`**. `intent.pricing-plans.planCount` recurring plans (name, price, a monthly billing cycle) fitting `brand`. **When bookings is also in this run and the intent is a membership that covers services** (a studio/gym/class pass), also **attach the covered bookings services to the plan** — seed the bookings services first, since coverage keys on their service ids (see the recipe). **Keep:** the bookings coverage only transiently, to wire it during seeding; nothing for the handoff — plans are discovered **live** (`queryPlans`) and plan→service coverage is read **live** at checkout, never from a frozen map (see `how-to-code-pricing-plans.md`).