@wix/agent-skills 1.14.0 → 1.15.0

package/skills/wix-headless/references/non-astro.md

@@ -0,0 +1,59 @@
+# Non-Astro — the pinned docs to read *before* wiring a non-Astro frontend to Wix
+
+This is the framework reference for any **non-Astro** frontend — React/Vue/Svelte/Vite SPA or plain static HTML. Astro stays the default (`astro.md`); read this when the user **names a framework** or **brings a non-Astro design**. Like `astro.md`, it's an **index of doc pages** with one-line "what it settles" notes, **then a Caveats section**. It carries **no design, templates, payloads, or per-framework code** — the model designs and writes the whole frontend; this file says only *how it connects*.
+
+**This file is framework-axis only — it is mode-agnostic.** It is read in **both** the managed and self-managed flows, so it contains **no managed-vs-self-managed branching**: no `init` vs OAuth-app, no `wix release` vs external host, no `outputDirectory`, no `wix.config.json`. Anything that differs by *who hosts* lives in the project-type files (`managed/`, `self-managed/`) — you're already reading those in a known mode. Here is only what's **identical across both flows**: a non-Astro frontend talks to Wix through a manual `OAuthStrategy` visitor client + the SDK, the same way no matter who hosts it.
+
+**The auth rule (the cross-skill boundary).** **Astro = auto-auth, no client. Non-Astro = manual client.** Unlike Astro, you create a client — `createClient({ modules, auth: OAuthStrategy({ clientId }) })`. For non-Astro this is the **documented, correct** model (the "Create a Client with OAuth" doc scopes itself to "frameworks other than Astro"). The `clientId` is the project's **public** OAuth client id — **not** a secret. **Where that id comes from is your flow's `AUTHENTICATION.md`** (managed: the `appId` in `wix.config.json`; self-managed: the OAuth app you created) — this file just *uses* it.
+
+**Two sub-shapes, split on build — a framework fact, not a hosting fact:** **bundler SPA** (has a build step → `npm install` + `import`) vs **static HTML** (no build → load the SDK from a CDN). The caveats below split on that.
+
+**How to use it.** Before authenticating or wiring data, read the pinned pages top-to-bottom — read-then-act, never invent a URL or a body from memory.
+
+**URL form & how to read it.** Each link is the **`.md` twin** of a docs article. A page pinned here is **already curated — read it directly; don't re-discover it with search.** The two read paths take **different URL forms** — don't mix them:
+
+- **`curl` the link — first priority. Fetch it as-is (keep the `.md`)** for raw markdown.
+- **MCP doc tools — second priority** (discovery of a page this file doesn't pin, or a fallback if a fetch fails). Pass the URL *without* the `.md` suffix — `ReadFullDocsArticle` for the article pages here, `SearchWixSDKDocumentation` to reach SDK methods this file doesn't pin.
+- **No MCP, or a shape not pinned anywhere → doc discovery** (`DOC_DISCOVERY.md`): a `curl` semantic search (`document_type: SDK`/`WIX_HEADLESS`) plus structured schema lookup, then read the hit's `.md?apiView=SDK`.
+
+---
+
+## 1 — Authenticate (the heart — manual client, identical in both flows)
+
+| Page | What it settles |
+|---|---|
+| <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/oauth/create-a-client-for-authentication-with-oauth.md> | **The model.** Install `@wix/sdk` + the domain packages, then `createClient({ modules, auth: OAuthStrategy({ clientId }) })`. clientId only, **no secret in the frontend**. Explicitly scoped to "frameworks other than Astro." Create the client **once** and reuse it. |
+| <https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md> | **`OAuthStrategy` reference** — visitor sessions (automatic) vs member flows (managed/custom/external); token + session methods; confirms `clientId` only. |
+| <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/visitors/handle-visitors-using-the-js-sdk.md> | **Visitors & members via the JS SDK** — visitor token sessions out of the box, and member login when the site needs it. Members are **first-class** on the non-Astro path (not deferred). |
+| <https://dev.wix.com/docs/go-headless/self-managed-headless/authentication/members/wix-login-page/wix-managed-login-using-the-js-sdk.md> | **Member login (Wix login page)** — the manual `OAuthStrategy` handshake: `generateOAuthData → getAuthUrl → parseFromUrl → getMemberTokens → setTokens`, `logout`, `loggedIn()`. Login *is* sign-up (the Wix page logs in or registers); member tokens are the **same shape** as visitor tokens (`role: member`), so they reuse the visitor session machinery — login just swaps the token set. **`clientId` only (no secret); the connected site must be PUBLISHED and the `redirectUri` must be an exact-match allow-listed URI, or `getAuthUrl` fails; default to the Wix login page** over custom/external. **Full frontend contract → Read `inline-recipes/how-to-code-members-non-astro.md`** (local — Read it, don't curl). **Only if the brief explicitly asks for a custom/branded login form or custom sign-up fields → Read `inline-recipes/how-to-code-members-custom-login.md`** instead (`client.auth.register`/`login`; works on any project type — pick by intent, not project type). |
+| <https://dev.wix.com/docs/sdk/articles/set-up-a-client/about-the-wix-client.md> | **Confirms non-Astro *does* need a client** — the "when you need a client vs not" list; non-Astro (managed or self-managed) is on the "needs a client" side, the mirror of Astro. |
+
+> **clientId source is deferred.** This file uses the `clientId`; it does **not** say where it comes from. That's `{managed,self-managed}/AUTHENTICATION.md` — managed reads `appId` from `wix.config.json`; self-managed uses the OAuth app you created. Don't re-mint or re-fetch it if the flow already provides it.
+
+## 2 — Frontend data access (identical in both flows)
+
+All reads and writes go through the client from §1 — the SDK call shapes are framework-identical (the model adapts the idiom: React effect / Vue `onMounted` / Svelte store). For **which packages** a capability needs and the **SDK module docs** for each call shape, use `SDK_HANDOFF.md` §3 (the package map) — don't restate it here. For **what was seeded** and the IDs to bind, cross-link `SEED.md`; the frontend reads it with the visitor client.
+
+| Page | What it settles |
+|---|---|
+| <https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/install-sdk-packages.md> | Installing `@wix/sdk` + domain packages and their current versions (bundler path). |
+
+## 3 — Build the frontend (framework fact, not hosting)
+
+- **Bundler SPA** — produce the build output with the project's own `npm run build`.
+- **Static HTML** — there is **no build**; the HTML *is* the deployable artifact.
+
+This file **stops at "produce the build output."** *Where that output is deployed and how* — `outputDirectory`, publish, origin registration, the `index.html`-at-root rule — is host-specific and lives in `{managed,self-managed}/DEPLOYMENT.md`, not here.
+
+## 4 — Caveats (framework-invariant only)
+
+These hold regardless of who hosts. Host-specific gotchas (static `outputDirectory`, the `index.html` rename) are filed in `managed/DEPLOYMENT.md`, where you're in a known mode. (Numbering: N2/N3 were retired; the gap is intentional and the remaining IDs are kept stable so inbound references don't shift.)
+
+| Caveat | What it says |
+|---|---|
+| **N1 — No Wix scaffolder for a new non-Astro site** | There is **no** Wix command to scaffold a fresh React/Vue/static site — the non-Astro flow is connect-only. To *create* from scratch, the model runs the framework's **own** `npm create …` (e.g. `npm create vite@latest`), then the flow connects it. **Never infer a framework the user didn't name.** |
+| **N4 — No-bundler sites load the SDK from a CDN** | With **no bundler** (static HTML), import the SDK in a `<script type="module">` from `https://esm.sh/@wix/sdk@1` (plus the domain packages the same way) — there's no `npm install` step to bundle it. With a bundler, use normal `npm install` + `import`. |
+| **N5 — Client-only ⇒ no elevation ⇒ public-read** | A pure SPA/static frontend runs with a **visitor** token and **no server**, so there is no `auth.elevate`. CMS collections it reads must be **public-read**; anything member-scoped needs member auth. True regardless of who hosts. (Contrast Astro, which can elevate in a backend `/api` endpoint.) |
+| **N6 — `clientId` is public; inline it** | The OAuth `clientId` is public, not a secret — it's fine to inline it directly in client code/bundle; there's no runtime secret to protect and no env-var indirection required. (Where the value comes from is still the flow's `AUTHENTICATION.md`.) |
+| **N7 — Resolve `wix:image://` URIs with the SDK, never by hand** | SDK media fields (product/blog/CMS images) come back as internal identifiers like `wix:image://v1/<hash>/<file>#originWidth=…`, **not** ready URLs. Convert them with the SDK media module — `import { media } from '@wix/sdk'`, then `media.getScaledToFillImageUrl(uri, w, h, {})` (**returns the URL string directly — do NOT append `.url`; the 4th `options` arg is required, pass `{}`**), or `media.getImageUrl(uri).url` for the original (**that** one returns a `{ url }` object). The two shapes differ — mixing them (`getScaledToFillImageUrl(...).url`) resolves every image to `undefined`. Hand-building a `static.wixstatic.com/.../v1/fit/...` URL gets the format wrong and the image **403s** (or silently fails to load). Only `wix:image://` values need this — an already-absolute `https://` URL (e.g. an Unsplash placeholder) passes straight through. Docs: <https://dev.wix.com/docs/sdk/core-modules/sdk/media>. |
+| **N8 — Member login is a manual `OAuthStrategy` round-trip on the same client** | Login (which *is* sign-up), logout and "am I a member?" run on the visitor client from §1 — don't build a second client. Drive the handshake yourself: `generateOAuthData → getAuthUrl → parseFromUrl → getMemberTokens → setTokens`, `logout`, `loggedIn()`; **persist and renew** member tokens exactly like visitor tokens (`renewToken`, re-hydrate with `setTokens` on boot). Preconditions that bite: **`clientId` only**, **site PUBLISHED**, **`redirectUri` allow-listed exact-match**, **default to the Wix login page**. Read the current member with **`@wix/members` `getCurrentMember`** (not the dev-preview `@wix/site-members`). **No `auth.elevate`** — a member reads their own data under the member token, and a serverless SPA has no elevation anyway (N5). Full contract: `inline-recipes/how-to-code-members-non-astro.md`. |

package/skills/wix-headless/references/self-managed/AUTHENTICATION.md

@@ -0,0 +1,22 @@
+# Authentication — self-managed (TBD)
+
+For a **self-managed** project (self-hosted, where the user manages their own hosting and credential supply), the authentication method is **not yet decided — TBD**.
+
+When defined, this file must specify how `self-managed` obtains, for the rest of the (project-type-agnostic) flow:
+
+- **`$TOKEN`** — a bearer token authorized for the metasite (used as `Authorization: Bearer $TOKEN`).
+- **`$SITE_ID`** — the metasite id (used as the `wix-site-id` header on every site-scoped call).
+- **`clientId`** — the OAuth app's public client id for the frontend's `OAuthStrategy` (the OAuth **app id and client id are the same value** — app-id === client-id).
+
+It then ends at the same universal REST call shape every type uses:
+
+```bash
+curl -sS -w "\nHTTP_STATUS:%{http_code}" \
+  -X POST "https://www.wixapis.com/<endpoint>" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "wix-site-id: $SITE_ID" \
+  -H "Content-Type: application/json" \
+  -d '<body>'
+```
+
+> **TBD.** Until the self-managed auth method is defined, a `self-managed` run can't obtain a token — **stop with a clear error** and tell the user this project type isn't wired yet.

package/skills/wix-headless/references/self-managed/DEPLOYMENT.md

@@ -0,0 +1,7 @@
+# Deployment — self-managed (TBD)
+
+For a **self-managed** project, the deploy/finalize steps are **not yet decided — TBD**.
+
+Because hosting is the user's (not Wix's), this will likely mirror the self-hosted finalize pattern — **publish the metasite** and **register the deployed origin** on the OAuth app once the live URL is known (see `../stripe/DEPLOYMENT.md` for that shape) — but the exact mechanism, and how credentials/URL are supplied, are TBD.
+
+> **TBD.** Until this is defined, tell the user that `self-managed` deployment isn't wired yet, and that the frontend's visitor calls will be rejected until its origin is registered on the OAuth app.

package/skills/wix-headless/references/stripe/AUTHENTICATION.md

@@ -0,0 +1,55 @@
+# Authentication — stripe (Stripe Projects → Wix)
+
+For a **stripe** project (self-hosted, provisioned via Stripe Projects), every Wix call is a plain `curl` against `wixapis.com` with a bearer token. The credentials come from the project's `.env` (synced by Stripe Projects when Wix was connected), and the token is minted directly from the OAuth client-credentials grant. This file is the authority for how `stripe` obtains `$TOKEN`, `$SITE_ID`, and the public `clientId`; the flow files defer here.
+
+## Inputs from `.env`
+
+Stripe Projects namespaces each provider's vars, and Wix's own names already begin with `WIX_`, so a real provision yields a **doubled prefix**:
+
+| Var                     | Role                                                                                              |
+| ----------------------- | ------------------------------------------------------------------------------------------------- |
+| `WIX_WIX_CLIENT_ID`     | the OAuth app `client_id` — also the frontend `OAuthStrategy({ clientId })`                       |
+| `WIX_WIX_CLIENT_SECRET` | the OAuth app `client_secret` — **server-side only**; mints the token, never goes to the frontend |
+| `WIX_WIX_METASITE_ID`   | the metasite id → the `wix-site-id` header on every site-scoped call                              |
+
+The plain `WIX_*` names are accepted as a fallback (in case the provider definition changes). Read them at runtime. If `client_id`/`client_secret` are absent, Wix isn't connected in this project — **stop with a clear error**.
+
+The public `clientId` for the frontend's `OAuthStrategy` is `WIX_WIX_CLIENT_ID` (not secret).
+
+## Minting the token — inline, secret stays out of context
+
+Run this as a **single Bash call**. It sources `.env` *inside the shell*, so the command text references `$WIX_WIX_CLIENT_SECRET` but the secret value is never typed, printed, or returned. The minted token is written to a tmp file so later calls reuse it **without re-minting and without the token entering the model context**:
+
+```bash
+set -a; . ./.env; set +a
+curl -sS -X POST "https://www.wixapis.com/oauth2/token" \
+  -H "Content-Type: application/json" \
+  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"${WIX_WIX_CLIENT_ID:-$WIX_CLIENT_ID}\",\"client_secret\":\"${WIX_WIX_CLIENT_SECRET:-$WIX_CLIENT_SECRET}\"}" \
+  | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])" > /tmp/wix_token \
+  && test -s /tmp/wix_token && echo "token minted" || echo "MINT FAILED — Wix not connected, or app/creds invalid"
+```
+
+That endpoint returns `{ "access_token": "<…>", "token_type": "Bearer", "expires_in": 14400 }`. `instance_id` is **optional and omitted**. The token is a real OAuth token with a **4-hour expiry**.
+
+> **Shell state does not persist between Bash calls** — that is *why* the token goes to `/tmp/wix_token`. Mint once at the start of the run; every later call reads it back. Each mint here returns a *different, equally valid* token; "mint once" is for simplicity, not because re-minting is pointless.
+
+## REST call shape
+
+Every later call re-sources `.env` (for the non-secret metasite id) and reads the token from the tmp file — both cheap, both keep secrets out of context:
+
+```bash
+set -a; . ./.env; set +a
+TOKEN=$(cat /tmp/wix_token)
+SITE_ID="${WIX_WIX_METASITE_ID:-$WIX_METASITE_ID}"
+curl -sS -w "\nHTTP_STATUS:%{http_code}" \
+  -X POST "https://www.wixapis.com/<endpoint>" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "wix-site-id: $SITE_ID" \
+  -H "Content-Type: application/json" \
+  -d '<body>'
+```
+
+- **`Authorization: Bearer $TOKEN`** — the `Bearer` prefix is required.
+- **`wix-site-id: $SITE_ID`** — required by every site-scoped family (Stores v3, CMS v2, Blog v3, Forms v4, Apps-Installer v1, …). Harmless where unread; include it always.
+- **`Content-Type: application/json`** — on every POST/PATCH body.
+- **Parsing the response:** `-w` appends a `HTTP_STATUS:<code>` line *after* the JSON body. `grep` that line for the status, but parse the **body separately** — piping the combined output to a JSON parser (`python3 -m json.tool`, `json.load`, `jq`) chokes on the trailing status line (`Extra data: line 2 …`). Capture the body to a file with `-o body.json` (status still comes from `-w`), or drop the last line, before parsing.

package/skills/wix-headless/references/stripe/DEPLOYMENT.md

@@ -0,0 +1,63 @@
+# Deployment — stripe (self-hosted; publish + register origin)
+
+For a **stripe** project, hosting is the user's, so two one-time backend actions finalize the live site. Both use the token from this folder's `AUTHENTICATION.md`; run them once the deployed site is up.
+
+## 1 · Publish the Wix site
+
+**Always publish the metasite after deploying.** Some Wix-served flows the frontend relies on (redirects to Wix-hosted pages and other features served from the published site) only work once the site has been published. Just publish every time, so a flow that needs it never silently fails. The call is idempotent and takes **no body**:
+
+```bash
+set -a; . ./.env; set +a
+TOKEN=$(cat /tmp/wix_token); SITE_ID="${WIX_WIX_METASITE_ID:-$WIX_METASITE_ID}"
+curl -sS -w "\nHTTP_STATUS:%{http_code}" \
+  -X POST "https://www.wixapis.com/site-publisher/v1/site/publish" \
+  -H "Authorization: Bearer $TOKEN" -H "wix-site-id: $SITE_ID" \
+  -H "Content-Type: application/json" -d '{}'
+# 200 with an empty body `{}` means published — that 200 is the only success signal (no URL is returned).
+```
+
+## 2 · Register the deployed origin on the OAuth app
+
+For the frontend's visitor calls (`OAuthStrategy` with the public `clientId`) to be **accepted from the deployed site**, the site's origin must be on the OAuth app's allowed domains. Otherwise every browser SDK call from the live URL is rejected.
+
+We don't own the hosting, so the deployed URL is unknown until the site is deployed — this is a **post-deploy step performed once the URL is known** (it can't be done during Setup/Seed). The OAuth app's id **is the `clientId`** — `WIX_WIX_CLIENT_ID`.
+
+### Idempotent — register a given URL only once
+
+First **read** the app's current allowed domains; if the deployed origin is already present, the registration is already done — **skip it**. Only ever add a URL that isn't there yet.
+
+```bash
+set -a; . ./.env; set +a
+TOKEN=$(cat /tmp/wix_token); ID="${WIX_WIX_CLIENT_ID:-$WIX_CLIENT_ID}"
+curl -sS -w "\nHTTP_STATUS:%{http_code}" \
+  "https://www.wixapis.com/oauth-app/v1/oauth-apps/$ID" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json"
+# → read oAuthApp.allowedRedirectDomains; if the deployed origin is already in it, you're done.
+```
+
+### Add the deployed origin
+
+`PATCH` the app, sending the **existing** `allowedRedirectDomains` **plus** the new origin (the API replaces the field, so include what's already there), with a field mask:
+
+```bash
+set -a; . ./.env; set +a
+TOKEN=$(cat /tmp/wix_token); ID="${WIX_WIX_CLIENT_ID:-$WIX_CLIENT_ID}"
+curl -sS -w "\nHTTP_STATUS:%{http_code}" -X PATCH \
+  "https://www.wixapis.com/oauth-app/v1/oauth-apps/$ID" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{
+    "oAuthApp": { "id": "'"$ID"'", "allowedRedirectDomains": [ <existing…>, "<deployed-origin>" ] },
+    "mask": { "paths": ["allowedRedirectDomains"] }
+  }'
+```
+
+- `<deployed-origin>` is the live site's domain/URL (what the browser SDK runs on).
+- For the **exact field semantics and format** (domain vs. full URL, member-login redirect URIs vs. allowed domains), read the doc — don't guess: <https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/update-oauth-app.md>. Member-login redirect URIs are a **separate field** (`allowedRedirectUris`) from the origin (`allowedRedirectDomains`): the visitor SDK only needs the origin allowed, but **if this deploy has member login via the Wix login page, the member-login callback must also be registered** in `allowedRedirectUris` — same masked-`PATCH` shape as the origin (add both under one `mask.paths`), and required or login 4xxs. Mechanics + the "not read-only" gotcha: `../managed/DEPLOYMENT.md` → "Member login on a non-Astro frontend". (Custom login — `../inline-recipes/how-to-code-members-custom-login.md` — needs neither, as it has no login-page redirect.)
+
+> **If the live site's visitor token call still 400s after the origin is registered, suspect the bundle — not CORS.** An unregistered origin and an `undefined` `clientId` in the build produce the same browser-side 400. Before chasing CORS/propagation, confirm the real `clientId` value is actually inlined in the deployed bundle (see `../SDK_HANDOFF.md` §2).
+
+## If deployment is NOT part of this agent flow
+
+If the agent isn't the one deploying — the user will deploy the site themselves — the skill **cannot know the deployed URL**, so it cannot register the origin. (It can still publish the site — step 1 doesn't need the URL.) **Flag the origin step to the user clearly**, e.g.:
+
+> *"One required step remains before the frontend can talk to Wix: once your site is live, its URL must be registered on the Wix OAuth app (allowed domains). Give me the deployed URL — or re-run this skill with it — and I'll register it. Until then, Wix SDK calls from the live site will be rejected."*

package/skills/wix-manage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-manage
-description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, rich-content, sites, blog, calendar, domains, site-properties, ecommerce."
+description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, rich-content, sites, blog, calendar, domains, site-properties, ecommerce, marketing, analytics."
 compatibility: Requires Wix REST API access (API key or OAuth).
 ---
 
@@ -31,6 +31,13 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 ---
 
+## Analytics
+
+### [Query Site Analytics](references/analytics/query-site-analytics.md)
+**Technical:** Reads a site's analytics through the Semantic Model API. Covers listing semantic models, inspecting a model's schema (measures, dimensions, parameters), and querying data with a required time interval, filters, sorting, paging, and human-readable formatting. Key endpoints: /analytics/semantic-model/v3/semantic-models, /semantic-models/{id}, /semantic-models/query-data.
+
+---
+
 ## Blog
 
 ### [How to Create Blog Posts](references/blog/how-to-create-blog-posts.md)
@@ -64,6 +71,9 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Create Course Service](references/bookings/create-course-service.md)
 **Technical:** Use when the user wants to create a multi-session course — e.g. "create a 6-week workshop", "set up a training program for $300". Handles group capacity, full-course pricing, and fixed series via bulkCreateServices API.
 
+### [Diagnose Bookings Availability Issues](references/bookings/diagnose-availability-issues.md)
+**Technical:** Use when an appointment-based service has no bookable time slots / "customers can't book". Runs the DiagnoseAvailability endpoint (`POST /v2/time-slots/diagnose`) for ordered, machine-readable reason codes with suggested owner actions, and falls back to ListAvailabilityTimeSlots when the endpoint is inconclusive.
+
 ### [End-to-End Booking Flow](references/bookings/end-to-end-booking-flow.md)
 **Technical:** Complete booking flow from service discovery to payment. Query services, check availability with Time Slots V2, create bookings, and process payment via eCommerce checkout.
 
@@ -184,6 +194,16 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 ---
 
+## Marketing
+
+### [Create and Publish a Social Media Post (with AI generation)](references/marketing/create-and-publish-social-post.md)
+**Technical:** Creates and publishes (or schedules) a social media post to a connected channel (Instagram, Facebook, LinkedIn, TikTok, Pinterest, YouTube, Google Business Profile) via the Publisher API. Optionally generates the whole post from a free-text idea or the site's own assets (products, blog posts, events, bookings, coupons, categories), generates caption/title suggestions, and edits an existing image with AI. Verifies the channel is connected (and runs the OAuth connect flow if not), checks premium publishing quota, creates a draft item, then publishes it immediately or schedules it for a future date. Use when the user wants to create, generate, write, post, or schedule a social post (e.g. "post this to Instagram", "make a post from my product", "write a caption", "schedule a post").
+
+### [Generate a Marketing Plan and Schedule Its Posts](references/marketing/generate-and-publish-marketing-plan.md)
+**Technical:** Generates a site's AI social media marketing plan (a calendar of marketing activities, each with per-channel post drafts) via the Marketing Plan API, then schedules the drafts for publishing. Covers optional marketing settings (goal, channels, tone, frequency, content pillars), asynchronous generation with polling, and generating posts for additional activities. Use for "generate a marketing plan", "create a social media plan/calendar", or "schedule my plan's posts".
+
+---
+
 ## Media
 
 ### [Upload Media to Wix](references/media/upload-media-to-wix.md)
@@ -213,6 +233,9 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Ricos Converter Service](references/rich-content/ricos-converter-service.md)
 **Technical:** Validates and converts content between Ricos documents and HTML/Markdown/plain text using the Ricos Documents API. Covers plugin configuration, format conversion in both directions, and document validation.
 
+### [Author Ricos Rich Content](references/rich-content/author-ricos-rich-content.md)
+**Technical:** Hand-authoring valid Ricos rich-content JSON (the richContent/nodes tree) reused across Blog, Stores, Events, and CMS. Covers every common node shape — paragraphs, headings, lists, blockquotes, dividers, tables with cell fills, code blocks, images — plus inline text decorations and the nesting rules the format enforces.
+
 ---
 
 ## Site Properties

package/skills/wix-manage/references/analytics/query-site-analytics.md

@@ -0,0 +1,241 @@
+---
+name: "Query Site Analytics"
+description: Retrieve a Wix site's analytics through the Semantic Model API. Covers listing semantic models, inspecting a model's schema (measures, dimensions, parameters), and querying model data with a required time interval, filters, sorting, paging, and human-readable formatting.
+---
+# Query Site Analytics
+
+This article shows how to read a site's analytics with the **Semantic Model API**. A semantic model describes one analytics subject area (such as site traffic, revenue, etc.) and defines the **measures**, **dimensions**, and **parameters** you can query.
+
+## Prerequisites
+
+1. The app/caller has the **Site Analytics – read** permission scope (`SCOPE.DC-ANALYTICS-AND-REPORTS.READ-SITE-ANALYTICS`).
+2. A site context is available (the request is authorized against a specific site).
+
+## Required APIs
+
+- **Semantic Model API**: [REST](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/introduction)
+- **Site Properties API** (for the site's time zone): [REST](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties)
+
+Base path: `https://www.wixapis.com/analytics/semantic-model/v3`
+
+| Step | Method | Endpoint |
+|---|---|---|
+| List models | `GET` | `/semantic-models` |
+| Get model schema | `GET` | `/semantic-models/{semanticModelId}` |
+| Query model data | `POST` | `/semantic-models/query-data` |
+
+## Decision flow
+
+Always follow **List → Get → Query**. You cannot construct a valid query without first discovering the model's field names from `Get Semantic Model`.
+
+1. **List Semantic Models** — discover which subject areas exist and their IDs.
+2. **Get Semantic Model** — inspect a model's `measures`, `dimensions`, and `parameters` to find the exact `name` values to query and their supported filters/sorting.
+3. **Query Semantic Model Data** — request specific field names for a time `interval`, with optional filters, sorting, paging, and formatting.
+
+## Before you begin (sharp edges)
+
+- **`interval` is required on every query.** There is no way to query without a date range — omitting it fails.
+- **`interval` is start-inclusive, end-exclusive (`[start, end)`).** `start` is included, `end` is not. To get all of January 2026, query `start: "2026-01-01..."` and `end: "2026-02-01..."` — you get Jan 1–31, and Feb 1 is excluded. Set `end` to the day *after* the last day you want.
+- **Set `interval.timezone` to the site's time zone to match the Wix dashboard.** Analytics in the Wix business manager are bucketed by the site's time zone. If `interval.timezone` is omitted it defaults to **UTC**, so day boundaries shift and your numbers won't match what the owner sees in the dashboard (and the same goes for using a different time zone). Get the site's IANA time zone from `properties.timeZone` via [Get Site Properties](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties) (`GET https://www.wixapis.com/site-properties/v4/properties`) and pass it through.
+- **Field names must come from `Get Semantic Model`.** The `fields`, `filters[].field`, and `sort.fieldName` values must exactly match a `name` returned by the model schema (e.g. `traffic.sessions_count`). Do not guess field names.
+- **Field dependencies.** A field returns data only if at least one of the field names in its `dependencies` array is also included in the same query; otherwise it's **silently omitted** from results (no error). For example, a measure may only return data when a specific dimension is also requested.
+- **Sorting a nullable measure — set `sort.nullsLast: true`.** `nullsLast` defaults to `false` and only affects **descending** (`DESC`) order. If a measure can return null and you sort it `DESC`, the null rows sort *first* — so a "top N" query surfaces nulls before your real values. Set `nullsLast: true` to push nulls to the end.
+- **Result cap: 1,000 rows per query.** `results` is capped at 1,000 rows — paginate with `paging.offset` for larger datasets.
+- **Formatting is opt-in.** Set `formattingEnabled: true` to also receive a human-readable `formattedValue` per cell (e.g. `1500` → `"$1,500.00"` or `1.5K`). Raw typed values are always returned.
+- **Totals are opt-in.** Set `totalsIncluded: true` to get a `totals` row summing numeric fields across the **full (unpaginated)** result set.
+- **Unique fields are not additive.** For `unique` measures (e.g. unique visitors), query the exact time range you want in a **single request** — never sum values from separate date-range queries. Uniques are deduplicated within each queried range, so adding per-range results double-counts anyone who appears in more than one range and overstates the true total.
+
+## Step 1: List semantic models
+
+```bash
+curl -X GET \
+  'https://www.wixapis.com/analytics/semantic-model/v3/semantic-models' \
+  -H 'Authorization: <AUTH>'
+```
+
+Response:
+
+```json
+{
+  "semanticModels": [
+    { "id": "cad7fd34-2c8b-4dda-8296-3f9d47fb484d", "slug": "traffic", "description": "Site traffic", "keywords": ["sessions", "views"] }
+  ]
+}
+```
+
+Pick the model whose subject area matches the request, and keep its `id`.
+
+## Step 2: Get the model schema
+
+```bash
+curl -X GET \
+  'https://www.wixapis.com/analytics/semantic-model/v3/semantic-models/cad7fd34-2c8b-4dda-8296-3f9d47fb484d' \
+  -H 'Authorization: <AUTH>'
+```
+
+Response shape:
+
+```json
+{
+  "semanticModel": {
+    "id": "string<GUID>",
+    "slug": "string",
+    "description": "string",
+    "keywords": ["string"],
+    "measures": [ "Field" ],
+    "dimensions": [ "Field" ],
+    "parameters": [ "Field" ]
+  }
+}
+```
+
+Each `Field` (in `measures`, `dimensions`, and `parameters`):
+
+| Property | Meaning |
+|---|---|
+| `name` | The exact value to use in `fields`, `filters[].field`, and `sort.fieldName`. |
+| `type` | `STRING`, `NUMBER`, `BOOLEAN`, `DATE`, `DATE_TIME`, `OBJECT`, or `ARRAY`. |
+| `filters` | Supported filter `prefixes` (`IS`/`NOT`) and `conditions` (e.g. `EQUAL`, `RANGE_II`, `CONTAINS_ANY`). |
+| `sortable` | Whether the field can be used in `sort`. |
+| `enumerations` | Allowed values, for enumerated fields. |
+| `dependencies` | Other field names this field needs present in the query to return data (see sharp edges). |
+| `groupSlug` | Fields sharing a `groupSlug` are logically related. |
+| `description` | Human-readable description of the field. |
+
+- **Measures** are quantitative fields you aggregate (revenue, page views, order count).
+- **Dimensions** are categorical fields you group by (traffic source, country, product name).
+- **Parameters** are optional inputs that customize query behavior (currency, date granularity).
+
+## Step 3: Query the model data
+
+`POST /semantic-models/query-data` (body requires `Content-Type: application/json`).
+
+Required body fields: `semanticModelId`, `interval`, `fields`.
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/analytics/semantic-model/v3/semantic-models/query-data' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "semanticModelId": "cad7fd34-2c8b-4dda-8296-3f9d47fb484d",
+  "interval": {
+    "start": "2024-06-01T00:00:00.000Z",
+    "end": "2025-06-01T00:00:00.000Z",
+    "timezone": "America/New_York"
+  },
+  "fields": [
+    "traffic.referrer_category_name",
+    "traffic.sessions_count",
+    "traffic.views_count"
+  ],
+  "filters": [
+    {
+      "field": "traffic.sessions_count",
+      "condition": "GREATER_THAN",
+      "values": ["100"]
+    }
+  ],
+  "sort": {
+    "fieldName": "traffic.sessions_count",
+    "order": "DESC",
+    "nullsLast": true
+  },
+  "paging": {
+    "limit": 50,
+    "offset": 0
+  },
+  "formattingEnabled": true,
+  "totalsIncluded": true
+}'
+```
+
+### Request fields
+
+| Field | Required | Notes |
+|---|---|---|
+| `semanticModelId` | Yes | GUID from List/Get. |
+| `interval` | Yes | `{ start, end }` UTC ISO date-times, plus `timezone`. Range is start-inclusive, end-exclusive (`[start, end)`) — set `end` to the day after the last day you want. Set `timezone` to the site's IANA time zone (see Time zone section) so results match the Wix dashboard; defaults to UTC when omitted. |
+| `fields` | Yes | Up to 60 field `name`s from the model schema. |
+| `filters` | No | Array of `{ field, values[], condition, prefix }`. `condition` defaults to `EQUAL`, `prefix` defaults to `IS`. For `RANGE_*` conditions provide exactly 2 values. |
+| `sort` | No | `{ fieldName, order, nullsLast }`. `order` defaults to `ASC`; field must be `sortable`. `nullsLast` (default `false`) applies only to `DESC` order — set it to `true` when the sorted measure can contain nulls, otherwise nulls sort before real values. |
+| `paging` | No | `{ limit, offset }`. Defaults: `limit` 50, `offset` 0. |
+| `formattingEnabled` | No | Default `false`. Adds `formattedValue` per cell. |
+| `totalsIncluded` | No | Default `false`. Adds a `totals` row. |
+
+### Response shape
+
+```json
+{
+  "results": [
+    {
+      "fields": {
+        "traffic.referrer_category_name": { "stringValue": "Search", "formattedValue": "Search" },
+        "traffic.sessions_count": { "numericValue": 1500, "formattedValue": "1.5K" }
+      }
+    }
+  ],
+  "pagingMetadata": { "count": 5, "offset": 0 },
+  "totals": { "fields": { "traffic.sessions_count": { "numericValue": 9000 } } }
+}
+```
+
+Each cell in `results[].fields` is a typed value — one of `numericValue`, `stringValue`, `booleanValue`, `timestampValue`, `arrayValue`, or `objectValue` — plus `formattedValue` when `formattingEnabled` is `true`. `totals` is present only when `totalsIncluded` is `true`.
+
+## Time zone (match the Wix dashboard)
+
+Analytics shown in the Wix business manager are aggregated by the **site's time zone**. To return numbers that match what the site owner sees, pass that time zone in `interval.timezone` on every query. **When `timezone` is omitted, the API defaults to UTC** — which shifts day boundaries and produces totals that don't line up with the dashboard (the same applies to any non-site time zone).
+
+Get the site's time zone from **Get Site Properties**:
+
+```bash
+curl -X GET \
+  'https://www.wixapis.com/site-properties/v4/properties?fields.paths=timeZone' \
+  -H 'Authorization: <AUTH>'
+```
+
+The IANA time zone string is returned in `properties.timeZone`:
+
+```json
+{
+  "properties": {
+    "timeZone": "America/New_York"
+  }
+}
+```
+
+Use that value as `interval.timezone` in `Query Semantic Model Data`. The Site Properties `timeZone` reflects the site's primary business address and requires the `SITE_SETTINGS.VIEW` permission.
+
+## Pagination
+
+To retrieve more than 1,000 rows, page through with `offset`:
+
+1. Request page 1 with `paging: { limit: 1000, offset: 0 }`.
+2. Increment `offset` by the page size until `pagingMetadata.count` is less than the requested `limit`.
+
+## Common Errors
+
+| HTTP | Code | Meaning |
+|---|---|---|
+| 401 | `NO_ACCOUNT_IDENTITY` / `UNAUTHENTICATED` | Caller isn't authenticated; provide valid credentials. |
+| 404 | `SEMANTIC_MODEL_NOT_FOUND` | The `semanticModelId` doesn't exist for this site. |
+
+Silent gap (no error): a requested field returns no data because none of its `dependencies` were included in the query — add a dependency field and re-query.
+
+## Best Practices
+
+1. Always run **List → Get → Query**; never hardcode field names — read them from `Get Semantic Model`.
+2. Pass the site's time zone (`properties.timeZone` from Get Site Properties) in `interval.timezone` so results match the Wix dashboard.
+3. Include a field's `dependencies` in the query, or expect that field to be silently dropped.
+4. Use `formattingEnabled: true` for anything shown directly to a user; keep raw values for calculations.
+5. Use `totalsIncluded: true` to get period totals alongside a paged breakdown in a single call.
+6. Keep `fields` minimal (projection) and paginate large result sets with `offset`.
+
+## Related Documentation
+
+- [Semantic Model API: Introduction](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/introduction)
+- [Semantic Model API: Sample Flows](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/sample-flows)
+- [List Semantic Models](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/list-semantic-models)
+- [Get Semantic Model](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/get-semantic-model)
+- [Query Semantic Model Data](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/query-semantic-model-data)
+- [Get Site Properties](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties) (source of the site's `timeZone`)

package/skills/wix-manage/references/bookings/create-and-update-booking-services.md

@@ -33,7 +33,7 @@ A Bookings service defines a time based offering and includes the following cons
 - When creating an APPOINTMENT service and specifying `staffMemberIds`, ensure you are using the staff member's resourceId, not their primary staff member id.
 - Service Images - the service may have several images - `service.media.mainMedia` - presented in the services list, `service.media.coverMedia` - presented in the service page and `service.media.items` - array of images presented as a gallery in the service page for site visitors.
 - In order to add a media (image) to a service, it should first be defined in Wix Media Manager - search existing ([REST](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/search-files)) or new ([REST](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/bulk-import-file))
-- You should only set the image id (for example `item.id` -> `service.media.mainMedia.id`) there is no need to set the entire object.
+- Set only the image **id**, but nest it inside the media item's `image` object: `service.media.mainMedia.image.id` (likewise `service.media.coverMedia.image.id` and `service.media.items[].image.id`). The `id` is the binding field; `url` and dimensions are descriptive and need not be set. ⚠️ Setting the id directly on the media item (`service.media.mainMedia.id`, without the `image` wrapper) returns HTTP 200 but **silently drops** it — the image reads back empty (`image.id: ""`). Because it's a silent 200, a success status is not proof: always nest under `.image` and confirm with a re-query.
 
 ### Service Type Selection Guide