@wix/agent-skills 1.16.1 → 1.16.3

package/skills/wix-manage/references/rich-content/author-ricos-rich-content.md

@@ -1,10 +1,12 @@
 ---
 name: "Author Ricos Rich Content"
-description: Hand-authoring valid Ricos rich-content JSON (the richContent/nodes tree) used across Wix Blog posts, Stores product descriptions, Events, and CMS rich-text fields. 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.
+description: Authoritative recipe for hand-authoring valid Ricos rich-content JSON (the richContent/nodes tree) used across Wix Blog posts, Stores product descriptions, Events, and CMS rich-text fields. Use whenever a user asks to create, output, or return Ricos, richContent, or nodes-tree JSON; retrieve and read this full recipe before API schema search or constructing the JSON. Covers paragraphs, headings, lists, blockquotes, dividers, tables, code blocks, images, buttons, audio, video, galleries, collapsible lists, HTML embeds, inline decorations, and nesting rules.
 ---
 
 # Author Ricos Rich Content
 
+> **Routing rule (READ FIRST).** When hand-authoring or returning Ricos / `richContent` JSON, use **this recipe** — the shapes, nesting rules, spacer paragraphs, and plugin nodes below. Do not rely on API schema search alone; it misses those details. After this recipe loads, do not perform additional schema or documentation searches for node types covered here; compose and self-audit the JSON from this file. When the user only wants JSON output, **do not** call Ricos convert/validate APIs.
+
 Ricos is Wix's rich-content format — a tree of typed nodes serialized as JSON. The same structure is embedded by many products: a Blog post's `draftPost.richContent`, a Store product's rich description, an Events description, and CMS rich-text fields all expect a Ricos document. This recipe is the **authoring reference for that node tree**: the valid shape of each node, how nodes nest, and how to format text. It is intentionally product-agnostic — the consuming API decides *where* the document goes; this recipe governs *what a valid document looks like*.
 
 > A Ricos document is an object with a `nodes` array: `{ "nodes": [ /* block nodes */ ] }`. Whatever field the consuming API exposes (e.g. `richContent`), it holds this object. For validating or converting an existing document to/from HTML/Markdown, see [Ricos Converter Service](ricos-converter-service.md).
@@ -15,10 +17,58 @@ Ricos is Wix's rich-content format — a tree of typed nodes serialized as JSON.
 - Every node carries a `type`, an optional `id`, and (for container nodes) a `nodes` array of children. Node `id`s are optional when authoring for a create request — the API generates them; the examples below omit `id` for brevity.
 - **TEXT is a leaf.** A TEXT node only ever lives inside a `PARAGRAPH`, `HEADING`, or `CODE_BLOCK`. It must **never** sit directly in the root `nodes` array or inside a `LIST_ITEM`, `BLOCKQUOTE`, or `TABLE_CELL` — those must contain a `PARAGRAPH` (or `HEADING`) that then contains the TEXT. See [Nesting rules](#nesting-rules).
 - Failing to wrap TEXT correctly produces the parse error **"Expected a paragraph node but found TEXT"**.
+- **Block nodes do not get automatic vertical gap when rendered** — insert empty `PARAGRAPH` spacer nodes between sibling blocks when you need breathing room. See [Vertical spacing between blocks](#vertical-spacing-between-blocks).
+
+## Required plugin shape checklist
+
+Use this checklist while composing and again before returning JSON. Treat every path below as required for the described request:
+
+- **Button CTA:** emit a root-level `BUTTON`, never a `PARAGRAPH` with an inline `LINK`. Include `buttonData.type: "LINK"`, `buttonData.text`, `buttonData.link.url`, `buttonData.link.target`, and `buttonData.containerData`.
+- **Hosted audio:** emit `{ "type": "AUDIO", "nodes": [], "audioData": { ... } }`. The empty `nodes` array is on the AUDIO node beside `audioData` — never inside `audioData`. Include `audioData.containerData.alignment`, `width`, and `textWrap`, plus `audioData.audio.src.id`.
+- **Video with thumbnail:** place `videoData.video.src` and `videoData.video.duration` inside `video`; place `videoData.thumbnail` beside `video`, with `src.id`, `width`, and `height`.
+- **Gallery:** emit one root-level `GALLERY`. Put images in `galleryData.items`, not as child IMAGE nodes. Every item uses `image.media` with `src`, `width`, and `height`; include `galleryData.options.layout.type` and `numberOfColumns`.
+- **Collapsible FAQ:** use `COLLAPSIBLE_LIST → COLLAPSIBLE_ITEM → COLLAPSIBLE_ITEM_TITLE | COLLAPSIBLE_ITEM_BODY → PARAGRAPH → TEXT`. Every PARAGRAPH includes `paragraphData`, and every item includes both title and body.
+- **HTML embed:** emit a root-level `HTML` with `htmlData.source`, either `url` or `html`, and `htmlData.containerData.width`, `height`, and `alignment`.
+
+## Vertical spacing between blocks
+
+The renderer does **not** add margin between stacked block nodes. Adjacent paragraphs, headings, images, videos, tables, collapsible lists, buttons, galleries, and other blocks will sit flush against each other unless you separate them explicitly.
+
+**Use an empty `PARAGRAPH` as a spacer** — a paragraph with no `nodes` (no TEXT children):
+
+```json
+{ "type": "PARAGRAPH" }
+```
+
+Place spacer paragraphs at the root `nodes` level (or inside a `CARD` page) wherever layout needs vertical rhythm:
+
+- **After headings** — before the following body copy or media block.
+- **Between paragraphs** — when two text blocks should not run together visually.
+- **After block plugins** — images, videos, audio, galleries, tables, collapsible lists, HTML embeds, buttons, dividers, and lists often need a spacer before the **next distinct section** (not between every adjacent block in a minimal snippet the user enumerated).
+- **After blockquotes** — only when the following block is a separate section; skip the spacer when the user asked for a blockquote immediately followed by a specific paragraph in one compact output.
+- **Before major sections** — optional extra spacer when transitioning from one content group to another.
+
+When the user requests **only** specific nodes in one JSON output (e.g. "a blockquote and then a paragraph"), include exactly those nodes — do not add spacer paragraphs they did not ask for.
+
+Do **not** rely on `\n` inside `textData.text` for spacing — that does not create a real line break between blocks. Do **not** expect `paragraphData` margins or `containerData` alone to separate unrelated sibling nodes; the empty paragraph is the supported spacing mechanism.
+
+**Example — spacer after an image and before a table:**
+
+```json
+{
+  "nodes": [
+    { "type": "IMAGE", "imageData": { /* … */ } },
+    { "type": "PARAGRAPH" },
+    { "type": "TABLE", "nodes": [ /* … */ ], "tableData": { /* … */ } },
+    { "type": "PARAGRAPH" },
+    { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Next section.", "decorations": [] } } ], "paragraphData": {} }
+  ]
+}
+```
 
 ## Block node shapes
 
-**PARAGRAPH** — the base text container. An empty paragraph — `{ "type": "PARAGRAPH" }` — acts as a vertical spacer. `paragraphData.textStyle.textAlignment` accepts `AUTO`·`LEFT`·`CENTER`·`RIGHT`·`JUSTIFY`:
+**PARAGRAPH** — the base text container. An empty paragraph — `{ "type": "PARAGRAPH" }` — is the **vertical spacer** between block nodes (the renderer adds no gap on its own). See [Vertical spacing between blocks](#vertical-spacing-between-blocks). `paragraphData.textStyle.textAlignment` accepts `AUTO`·`LEFT`·`CENTER`·`RIGHT`·`JUSTIFY`:
 
 ```json
 {
@@ -142,6 +192,122 @@ Ricos is Wix's rich-content format — a tree of typed nodes serialized as JSON.
 }
 ```
 
+**BUTTON** — a standalone call-to-action block. **Not the same as an inline `LINK` decoration** on TEXT (that is hyperlinked body copy; this is a labeled button control). **`buttonData.type` is required** on every BUTTON node — use `"LINK"` for URL navigation or `"ACTION"` for viewer click handlers (never omit `type` even when `link` is present). Two `buttonData.type` values:
+
+- **`LINK`** — navigates to a URL when clicked (`link.url`, `link.target`: `BLANK`·`SELF`, optional `link.rel`).
+- **`ACTION`** — triggers a viewer `onClick` handler (store the node in JSON; behavior is configured in the Ricos viewer, not in the document body).
+
+```json
+{
+  "type": "BUTTON",
+  "buttonData": {
+    "type": "LINK",
+    "text": "Get Started",
+    "link": { "url": "https://example.com", "target": "BLANK", "rel": { "nofollow": true } },
+    "containerData": { "alignment": "CENTER", "width": { "size": "ORIGINAL" }, "textWrap": true },
+    "styles": { "borderRadius": 4, "borderWidth": 0, "backgroundColor": "#116DFF", "textColor": "#FFFFFF" }
+  }
+}
+```
+
+**AUDIO** — uploaded audio via Wix Media `src.id`, or an embed variant whose `audioData.html` holds an iframe (SoundCloud, Spotify). Include `audioData.containerData` with `alignment` and width settings, and use an empty `nodes: []` array because AUDIO has no child nodes. Optional fields include `coverImage` (`src.id`, `width`, `height`), `name`, `authorName`, and `disableDownload`:
+
+```json
+{
+  "type": "AUDIO",
+  "nodes": [],
+  "audioData": {
+    "containerData": { "alignment": "CENTER", "width": { "size": "CONTENT" }, "textWrap": true },
+    "audio": { "src": { "id": "mp3/f0f74f_48772df0375c41cd88e8e29370ccf899" } },
+    "disableDownload": true,
+    "coverImage": { "src": { "id": "f0f74f_2973832f552e4002b58ec6abbe7fce71~mv2.png" }, "width": 436, "height": 524 },
+    "name": "Track title",
+    "authorName": "Artist name"
+  }
+}
+```
+
+**VIDEO** — Wix Media `video.src.id`, `duration` (seconds), and a `thumbnail` (`src.id`, `width`, `height`). YouTube and other embeds use the same `VIDEO` node shape with the appropriate media id:
+
+```json
+{
+  "type": "VIDEO",
+  "videoData": {
+    "containerData": { "width": { "size": "CONTENT" }, "alignment": "CENTER" },
+    "video": { "src": { "id": "video/11062b_a552731f40854d16a91627687fb8d1a6/1080p/mp4/file.mp4" }, "duration": 14.08 },
+    "thumbnail": { "src": { "id": "media/11062b_a552731f40854d16a91627687fb8d1a6f000.jpg" }, "width": 1920, "height": 1080 }
+  }
+}
+```
+
+**GALLERY** — multiple images in one block. Each `items[]` entry wraps `image.media` with `src` (`id` or `url`), `width`, and `height`. `galleryData.options` controls layout (`layout.type`: `GRID`, `numberOfColumns`, `orientation`; `item.ratio`, `item.crop`; `thumbnails.placement`):
+
+```json
+{
+  "type": "GALLERY",
+  "galleryData": {
+    "containerData": { "width": { "size": "CONTENT" }, "alignment": "CENTER", "textWrap": true },
+    "items": [
+      { "image": { "media": { "src": { "id": "8bb438_36726a2d14ec44ee9edc5693bade1092.jpg" }, "width": 3648, "height": 5472 } } },
+      { "image": { "media": { "src": { "id": "8bb438_6bbf8e82fe8f4b79b6e03ee79b66fd6a.jpg" }, "width": 1920, "height": 1280 } } }
+    ],
+    "options": {
+      "layout": { "type": "GRID", "horizontalScroll": false, "orientation": "COLUMNS", "numberOfColumns": 3 },
+      "item": { "ratio": 1, "crop": "FILL" },
+      "thumbnails": { "placement": "NONE" }
+    }
+  }
+}
+```
+
+**COLLAPSIBLE_LIST** — FAQ-style expandable items. Nesting is `COLLAPSIBLE_LIST → COLLAPSIBLE_ITEM → COLLAPSIBLE_ITEM_TITLE | COLLAPSIBLE_ITEM_BODY → PARAGRAPH → TEXT` (body cells may also contain other supported block plugins such as IMAGE or VIDEO). The item wrapper type is **`COLLAPSIBLE_ITEM`** — not `COLLAPSIBLE_LIST_ITEM` or other variants:
+
+```json
+{
+  "type": "COLLAPSIBLE_LIST",
+  "nodes": [
+    {
+      "type": "COLLAPSIBLE_ITEM",
+      "nodes": [
+        {
+          "type": "COLLAPSIBLE_ITEM_TITLE",
+          "nodes": [
+            { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Question?", "decorations": [] } } ], "paragraphData": { "textStyle": { "textAlignment": "AUTO" } } }
+          ]
+        },
+        {
+          "type": "COLLAPSIBLE_ITEM_BODY",
+          "nodes": [
+            { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Answer text.", "decorations": [] } } ], "paragraphData": { "textStyle": { "textAlignment": "AUTO" } } }
+          ]
+        }
+      ]
+    }
+  ],
+  "collapsibleListData": {
+    "containerData": { "alignment": "CENTER", "textWrap": true },
+    "expandOnlyOne": false,
+    "initialExpandedItems": "FIRST",
+    "direction": "LTR"
+  }
+}
+```
+
+`initialExpandedItems`: `NONE`·`FIRST`·`ALL`. Set `isQapageData: true` in list metadata when the list should render as FAQ structured data in search results.
+
+**HTML** — embeds external content in an iframe. Provide either `url` (page URL) or inline `html` markup; `source` is typically `"HTML"`. Size via `containerData.width` / `height` (`custom` pixel strings or `size`):
+
+```json
+{
+  "type": "HTML",
+  "htmlData": {
+    "containerData": { "width": { "custom": "550" }, "height": { "custom": "550" }, "alignment": "CENTER" },
+    "url": "https://example.com/embed",
+    "source": "HTML"
+  }
+}
+```
+
 ## Inline text formatting (decorations)
 
 Apply formatting with the `decorations` array on a TEXT node. Each decoration is an object with a `type` and (for some types) a data field:
@@ -169,6 +335,7 @@ Apply formatting with the `decorations` array on a TEXT node. Each decoration is
 | `COLOR`                                    | `colorData: { foreground: "#hex" }` (add `background` for highlight) |
 | `LINK`                                     | `linkData: { link: { url, target: "BLANK" } }`             |
 | `FONT_SIZE`                                | `fontSizeData: { unit: "PX", value: 24 }`                  |
+| `SPOILER`                                  | _(none — `{ "type": "SPOILER" }` hides text behind a reveal control)_ |
 
 - **Mixed formatting in one paragraph → split into multiple TEXT nodes** (one per style run) inside the same PARAGRAPH. A single TEXT node carries one consistent set of decorations.
 - Use a plain hex string in `foreground` for colors.
@@ -229,12 +396,16 @@ Note the mixed-run paragraph at the end: the linked words are their own TEXT nod
 
 | Parent | Valid children |
 | ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| Root `nodes`                         | PARAGRAPH, HEADING, BULLETED_LIST, ORDERED_LIST, BLOCKQUOTE, DIVIDER, IMAGE, TABLE, CODE_BLOCK         |
+| Root `nodes`                         | PARAGRAPH, HEADING, BULLETED_LIST, ORDERED_LIST, BLOCKQUOTE, DIVIDER, IMAGE, TABLE, CODE_BLOCK, BUTTON, AUDIO, VIDEO, GALLERY, COLLAPSIBLE_LIST, HTML |
 | PARAGRAPH / HEADING / CODE_BLOCK     | TEXT                                                                                                  |
 | BULLETED_LIST / ORDERED_LIST         | LIST_ITEM                                                                                             |
 | LIST_ITEM / BLOCKQUOTE               | PARAGRAPH (which then contains TEXT)                                                                  |
 | TABLE → TABLE_ROW → TABLE_CELL       | cell contains PARAGRAPH / HEADING / IMAGE                                                              |
-| IMAGE                                | CAPTION (optional)                                                                                    |
+| IMAGE / VIDEO                        | CAPTION (optional)                                                                                    |
+| COLLAPSIBLE_LIST                     | COLLAPSIBLE_ITEM                                                                                      |
+| COLLAPSIBLE_ITEM                     | COLLAPSIBLE_ITEM_TITLE, COLLAPSIBLE_ITEM_BODY                                                        |
+| COLLAPSIBLE_ITEM_TITLE / _BODY       | PARAGRAPH (and other plugins supported inside collapsible cells — see COLLAPSIBLE_LIST above)           |
+| BUTTON / AUDIO / GALLERY / HTML      | _(leaf — `nodes: []` or omit)_                                                                        |
 
 ## Self-audit before returning the document
 
@@ -246,4 +417,10 @@ All decidable from the JSON itself — check before handing the document to a co
 4. **Headings carry a `level`** (1–6) and nest logically (don't jump H2 → H4).
 5. **No `\n` inside `textData.text`** — split into sibling nodes; mixed inline formatting → split into multiple TEXT runs.
 6. **Images** use a Wix Media `id` (not a raw URL), with `width`, `height`, and meaningful `altText`.
-7. **Links** — every `LINK` decoration has a valid `url` and `target`.
+7. **Links** — every `LINK` decoration has a valid `url` and `target`. Use a `BUTTON` block with `buttonData.type: "LINK"` for CTAs — not an inline `LINK` decoration styled to look like a button.
+8. **Buttons** — every BUTTON includes **`buttonData.type`** (`LINK` requires `link.url`; `ACTION` has no URL). Omitting `type` is invalid even when `link` is set. `LINK` buttons and inline `LINK` decorations serve different purposes.
+9. **Media blocks** — AUDIO has root-level `nodes: []` and `audioData.containerData`; VIDEO keeps `thumbnail` beside `video` under `videoData`; every GALLERY item is under `galleryData.items` and carries `image.media.src`, `width`, and `height`.
+10. **Collapsible lists** — every item has both `_TITLE` and `_BODY`, each wrapping content through `PARAGRAPH → TEXT`, and every PARAGRAPH has `paragraphData`.
+11. **HTML embeds** — `htmlData` includes `source`, `containerData.width`, `containerData.height`, and either `url` or `html` (not both empty).
+12. **Spoiler** — `SPOILER` is a decoration on `TEXT` (or `containerData.spoiler` on some block plugins in editor output); preserve it verbatim on edit.
+13. **Vertical spacing** — stacked block nodes that should not appear cramped are separated by empty `{ "type": "PARAGRAPH" }` spacers — especially after images, videos, tables, collapsible lists, galleries, buttons, and between consecutive paragraphs. Missing spacers produce a wall-of-blocks layout with no renderer-added margin.

package/skills/wix-manage/references/sites/create-headless-site.md

@@ -50,3 +50,4 @@ To provision headless onto an existing site, pass `"existingMetasite": {}` inste
 After creating the site:
 - Install additional apps using [Install Wix Apps](../app-installation/install-wix-apps.md)
 - Add content (products, services, blog posts, etc.)
+- Use the `appId` as the `client_id` to mint visitor tokens and make buyer-facing API calls — see [Manage OAuth Apps](manage-oauth-apps.md)

package/skills/wix-manage/references/sites/manage-oauth-apps.md

@@ -0,0 +1,154 @@
+---
+name: "Manage OAuth Apps"
+description: Create, read, update, and query OAuth apps for a Wix headless site. Each OAuth app's id is the client_id a frontend uses to mint anonymous visitor tokens and call Wix APIs.
+---
+# Manage OAuth Apps
+
+An OAuth app is a site-level credential holder. Its `id` is the `client_id` (the two terms are interchangeable — Wix uses `appId` in provisioning responses, `clientId` in token requests, and `id` in the OAuth Apps API; they all refer to the same value).
+
+When a headless site is provisioned it gets one OAuth app automatically (see [Create Headless Site](create-headless-site.md)); use this recipe to create additional apps, inspect existing ones, or update their redirect configuration.
+
+> **`client_id` is not a secret** — it is a public identifier safe to embed in frontend code. The visitor token it mints is also non-privileged: it represents an anonymous visitor, not an admin. The `client_secret` is different — shown once in the Headless Settings dashboard, never returned by the API, and rotation is dashboard-only.
+
+---
+
+## Create an OAuth App
+
+**Endpoint**: `POST https://www.wixapis.com/oauth-app/v1/oauth-apps`
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/oauth-app/v1/oauth-apps' \
+  -H 'Authorization: <AUTH>' \
+  -H 'wix-site-id: <metaSiteId>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "oAuthApp": {
+      "name": "My Storefront",
+      "loginUrl": "https://example.com/login",
+      "allowedRedirectUris": ["https://example.com/callback"],
+      "allowedRedirectDomains": ["example.com"]
+    }
+  }'
+```
+
+**Response**:
+```json
+{
+  "oAuthApp": {
+    "id": "<clientId>",
+    "name": "My Storefront",
+    "loginUrl": "https://example.com/login",
+    "allowedRedirectUris": ["https://example.com/callback"],
+    "allowedRedirectDomains": ["example.com"],
+    "createdDate": "2026-08-18T10:00:00Z"
+  }
+}
+```
+
+`id` is the OAuth `client_id`. After creating the app, retrieve the `client_secret` from the Headless Settings dashboard.
+
+---
+
+## Get an OAuth App
+
+**Endpoint**: `GET https://www.wixapis.com/oauth-app/v1/oauth-apps/{id}`
+
+```bash
+curl 'https://www.wixapis.com/oauth-app/v1/oauth-apps/<clientId>' \
+  -H 'Authorization: <AUTH>' \
+  -H 'wix-site-id: <metaSiteId>'
+```
+
+---
+
+## Query OAuth Apps
+
+**Endpoint**: `POST https://www.wixapis.com/oauth-app/v1/oauth-apps/query`
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/oauth-app/v1/oauth-apps/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'wix-site-id: <metaSiteId>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "query": {} }'
+```
+
+Returns all OAuth apps for the site.
+
+---
+
+## Update an OAuth App
+
+**Endpoint**: `PATCH https://www.wixapis.com/oauth-app/v1/oauth-apps/{id}`
+
+Update requires an explicit `mask.paths` — omitting it silently updates nothing.
+
+Updatable fields: `name`, `description`, `loginUrl`, `logoutUrl`, `allowedRedirectUris`, `allowedRedirectDomains`, `technology`.
+
+```bash
+curl -X PATCH \
+  'https://www.wixapis.com/oauth-app/v1/oauth-apps/<clientId>' \
+  -H 'Authorization: <AUTH>' \
+  -H 'wix-site-id: <metaSiteId>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "oAuthApp": {
+      "allowedRedirectUris": ["https://example.com/callback", "https://example.com/auth"]
+    },
+    "mask": { "paths": ["allowedRedirectUris"] }
+  }'
+```
+
+---
+
+## Key Fields
+
+| Field | Notes |
+|---|---|
+| `id` | The OAuth `client_id`. Read-only. |
+| `name` | Required on create. 2–256 chars. |
+| `loginUrl` | External login redirect. Defaults to Wix login if omitted. |
+| `logoutUrl` | Called when the user logs out at Wix. |
+| `allowedRedirectUris` | Exact-match URIs for post-authentication redirect. Max 20. |
+| `allowedRedirectDomains` | Domain-level allow-list for non-auth redirects (e.g. checkout). Max 20. |
+| `applicationType` | `WEB_APP`, `MOBILE`, `OTHER` |
+
+---
+
+## Minting a Visitor Token
+
+Once you have a `client_id`, frontends use it to mint an anonymous visitor token for buyer-facing API calls.
+
+**Endpoint**: `POST https://www.wixapis.com/oauth2/token`
+
+```bash
+# Initial anonymous mint
+curl -X POST 'https://www.wixapis.com/oauth2/token' \
+  -H 'Content-Type: application/json' \
+  -d '{ "clientId": "<clientId>", "grantType": "anonymous" }'
+
+# Response: { "access_token": "...", "refresh_token": "...", "expires_in": 14400 }
+```
+
+```bash
+# Refresh (use this instead of re-minting)
+curl -X POST 'https://www.wixapis.com/oauth2/token' \
+  -H 'Content-Type: application/json' \
+  -d '{ "clientId": "<clientId>", "grantType": "refresh_token", "refreshToken": "<refreshToken>" }'
+```
+
+Use the `access_token` as the `Authorization` header on subsequent API calls.
+
+> **Never re-mint anonymous on every load.** The visitor token is the cart/session identity — a fresh anonymous mint creates a new visitor and silently empties the cart. Persist the `refresh_token` and use it to renew.
+
+---
+
+## API Reference
+
+- [OAuth Apps — Create](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/create-o-auth-app)
+- [OAuth Apps — Get](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/get-o-auth-app)
+- [OAuth Apps — Query](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/query-o-auth-apps)
+- [OAuth Apps — Update](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/update-o-auth-app)
+- [Retrieve Tokens — `/oauth2/token` contract, all grant types](https://dev.wix.com/docs/api-reference/business-management/headless/authentication/retrieve-tokens)

package/skills/wix-manage/references/sites/read-site-context.md

@@ -0,0 +1,125 @@
+---
+name: "Read Account or Site Context"
+description: Probe a Wix site or account for full context in one call — installed apps by display name, locale, currency, timezone, and status. Account token + siteId targets one site; account token alone returns up to 10; site-scoped token alone returns the site it is scoped to.
+---
+# Read Account or Site Context
+
+Returns a site's name, URL, status, locale/region, and all installed apps with human-readable display names.
+
+---
+
+## Markdown endpoint (recommended)
+
+**Endpoint**: `POST https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown`
+
+Returns `{ "markdown": "..." }`.
+
+### Account token + siteId — one specific site
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{"siteId": "<metaSiteId>"}'
+```
+
+Response:
+
+```
+## 1. Acme Store
+
+**ID**: `<metaSiteId>`
+**URL**: [https://example.wixsite.com/acme](https://example.wixsite.com/acme)
+**Status**: Published
+**Editor Type**: Editorless
+**Created**: Aug 14, 2026, 05:21 · **Updated**: Aug 17, 2026, 20:44
+**Velo**: Enabled
+
+### Properties
+
+**Locale & Region**
+- Language: **en**
+- Country: **US**
+- Timezone: **America/New_York**
+- Currency: **USD**
+
+### Apps
+
+- **Wix Stores** (ID: `215238eb-22a5-4c36-9e7b-e7c08025e04e`) — Catalog app version: **V3**
+- **Wix Bookings** (ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`)
+- **Wix Blog** (ID: `14bcded7-0066-7c35-14d7-466cb3f09103`)
+```
+
+### Without siteId
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+- **Account token**: returns up to 10 sites. If the account has more: `_Showing 10 sites (more available)_` — call again with a specific `siteId`.
+- **Site-scoped token** (e.g. the Wix connector in Base44): returns the one site the token is scoped to.
+
+---
+
+## JSON endpoint
+
+**Endpoint**: `POST https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context`
+
+Same request shape. `installedApps` contains raw `appId` UUIDs — extract only what you need:
+
+```javascript
+const res = await fetch(
+  "https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context",
+  {
+    method: "POST",
+    headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ siteId: metaSiteId }),
+  }
+);
+const { sites } = await res.json();
+const site = sites[0];
+
+const KNOWN_APPS = {
+  stores:       "215238eb-22a5-4c36-9e7b-e7c08025e04e",
+  bookings:     "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
+  blog:         "14bcded7-0066-7c35-14d7-466cb3f09103",
+  events:       "140603ad-af8d-84a5-2c80-a0f60cb47351",
+  pricingPlans: "1522827f-c56c-a5c9-2ac9-00f9e6ae12d3",
+  restaurants:  "13e8d036-5516-6f75-e025-2aca3b5d7930",
+};
+
+const appById = Object.fromEntries(
+  (site.installedApps ?? []).map((a) => [a.appId, a])
+);
+
+const context = {
+  id:              site.id,
+  name:            site.displayName,
+  url:             site.url,
+  currency:        site.properties?.paymentCurrency,
+  locale:          `${site.properties?.locale?.languageCode}-${site.properties?.locale?.country}`,
+  timezone:        site.properties?.timeZone,
+  hasStores:       !!appById[KNOWN_APPS.stores],
+  storesCatalogV:  appById[KNOWN_APPS.stores]?.catalogVersion ?? null, // "V3" | "V1" | null
+  hasBookings:     !!appById[KNOWN_APPS.bookings],
+  hasBlog:         !!appById[KNOWN_APPS.blog],
+  hasEvents:       !!appById[KNOWN_APPS.events],
+  hasPricingPlans: !!appById[KNOWN_APPS.pricingPlans],
+  hasRestaurants:  !!appById[KNOWN_APPS.restaurants],
+};
+```
+
+---
+
+## API Reference
+
+- [Get Dynamic Context — markdown](https://dev.wix.com/docs/api-reference/tools/dynamic-site-context/get-dynamic-context-markdown)
+- [Get Dynamic Context — JSON](https://dev.wix.com/docs/api-reference/tools/dynamic-site-context/get-dynamic-context)
+- [Query Sites](https://dev.wix.com/docs/api-reference/account-level/sites/sites/query-sites) — for paginating or filtering the full site list
+- [Get Installed Apps](https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/get-installed-apps) — raw app instances with fields not in the context snapshot
+- [Get Site Properties](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties) — full properties including business description, address, social links