@wix/agent-skills 1.16.1 → 1.16.2

package/skills/wix-base44-connector/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: wix-base44-connector
+description: "Build on Wix from the Base44 builder sandbox — this file is the complete guide (site context, doc discovery, API contracts, who calls Wix from where), and scripts/utils.js is its helper module, loaded from disk per exec. Triggers: build a Base44 app on a connected Wix site, look up a Wix API from the sandbox, decide frontend vs backend for a Wix call."
+---
+
+# Building on Wix from Base44
+
+The Wix connector is connected; this is how the app gets built on it — gather the site's context,
+find the APIs and learn their contracts from the docs, write the code. **Discover everything**: endpoints, paths, doc URLs,
+request and response fields all come from the calls below, never from memory or pattern. 404 or
+empty ⇒ discover, not permute. Examples teach mechanics and go stale — verify before relying.
+
+## What are you building?
+
+The app's audience picks the token, and the token picks the architecture: the **visitor token is
+public** — anyone can mint it from the site's `clientId` — and the **admin token is a secret**,
+the connector's, server-side only.
+
+```
+browser            ──(visitor token)─► wixapis.com   the visitor's own reads & actions
+base44/functions/* ──(admin token)───► wixapis.com   work that needs the owner's identity
+exec_tool          ──(admin token)───► wixapis.com   you: ad hoc probing/managing while building
+```
+
+**A site for visitors** — storefront, blog, booking. Headless means the Wix site has no pages of
+its own: your app IS its frontend. **The complete visitor experience —
+every page, every read, every action a visitor takes — is browser calls on the visitor token;
+none of it needs a backend function.** Public reads
+included (the visitor token queries the catalog directly), and `carts/current/*` + checkout act
+on the CALLER's cart, so only the visitor token reaches the visitor's cart. One file carries it
+all: `src/lib/wixClient.js` (Write the code, below). `base44/functions/*` appear only where work
+needs the owner's identity — elevated-permission ops a visitor triggers, webhooks, scheduled
+jobs — and for the app's non-Wix backend.
+
+**An admin tool for the owner** — dashboard, back office. The pages act as the owner, whose token
+is a secret: `pages → base44/functions/* ──(admin token)──► wixapis.com`.
+
+## The helpers
+
+Research and probing run in exec_tool, and one loader opens every exec (execs share no state —
+reload each round; the module lives on disk next to this file, network only as first-touch
+fallback):
+
+```js
+const fs = require("fs"), P = ".agents/skills/wix-base44-connector/utils.js";
+if (!fs.existsSync(P)) { fs.mkdirSync(".agents/skills/wix-base44-connector", { recursive: true });
+  fs.writeFileSync(P, await (await fetch("https://www.wix.com/skills/wix-base44-connector/scripts/utils.js")).text()); }
+const wx = (() => { const m = { exports: {} };
+  new Function("module", "exports", "require", fs.readFileSync(P, "utf8"))(m, m.exports, require); return m.exports; })();
+```
+
+Results ≤ 4,000 chars come back inline (exec results clip at ~5,000); anything bigger is saved
+under `.agents/skills/wix-base44-connector/scratch/` and returns `{ path, bytes, lines, outline }` —
+the outline is the map. Read a saved file the way you already know how:
+`wx.bash("grep -n 'term' <path> | head -40")` to find (GNU grep/sed, awk is mawk, no rg;
+across everything saved: `grep -rn 'term' .agents/skills/wix-base44-connector/scratch/`), and
+`read_file` to quote — a window via `offset`/`limit` at the lines grep named, or the whole
+file when it fits read_file's 45K cap. **API responses are site data and never land in
+scratch** — project them to facts. Fetch every URL inside exec with `fetch()` — website/browser
+tools clip at 10,000 chars silently. One exec per round; timeout 10s, up to 120 via `{timeout}`.
+
+## Gather context — the dynamic context report
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+return await wx.context(accessToken, "Apps");   // no section arg → the report's outline
+```
+
+One report: installed apps **with ids** (incl. Stores' catalog version — V1 vs V3 decides its
+endpoints), the OAuth app id (**also the visitor `clientId`**), locale, currency, CMS collections.
+An empty report = bad token, never an empty site.
+
+## Learn Wix — find the APIs, learn their contracts
+
+```js
+// know the product? browse is deterministic — menuUrl alone orients (children + counts);
+// filter before listing methods, unfiltered listings clip
+await wx.browse("https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings",
+                { include: ["METHOD"], filter: "resched", depth: 4 });
+
+// don't know where it lives? search ranks, never says "no match" — drop wrong-product hits
+await wx.search("pause a pricing plan subscription and resume it");
+// → { hits: [{ method, endpoint /* callable */, docsUrl, gist }] } — hits often ARE the answer
+```
+
+Go deeper for fields, enums, or absence — only the spec index proves absence.
+
+### Read a doc page
+
+Method pages are 100 KB+, twin REST and SDK halves repeating field names at different types —
+map and window in the SAME exec; coordinates are for your code, not for a second round:
+
+```js
+const pg = await wx.page(docsUrl);   // whole text when small; else { path, bytes, lines, outline }
+// your half, windowed to your term and its Examples (a complete working request — URL, headers,
+// body — usually all you need), one round:
+return wx.bash(`sed -n '/^## REST API/,/^## JavaScript SDK/p' ${pg.path} | grep -B5 -A40 -i 'examples\\|<term>' | head -c 3800`);
+// a giant fenced example → its field vocabulary instead of paging it:
+// wx.bash(`sed -n '<a>,<b>p' ${pg.path} | grep -oE '"[a-zA-Z]+":' | sort -u | head -60`)
+```
+
+`search` also saves its raw content beside the inline hits — grep its `path` when a hit's six
+lines weren't enough.
+
+### The spec index
+
+Answers questions about pages you already found — arrive with a `docsUrl`, match by it. Also the
+only proof an API does NOT exist:
+
+```js
+await wx.spec(`
+  const r = lightIndex.find(x => x.docsUrl === "<docsUrl from browse/search>");
+  return r.methods.map(m => ({ op: m.operationId.split(".").pop(), verb: m.httpMethod,
+                               call: m.publicUrl }));   // publicUrl is callable — path is PARTIAL
+`);
+// request fields next round: getResourceSchemaByUrl(docsUrl) →
+//   m.requestBody.content["application/json"].schema.properties — names and types, drill deeper
+//   per round; $circular stubs resolve via s.components.schemas["<name>"]
+```
+
+### Management recipes — check before composing admin flows
+
+~100 curated multi-step recipes (install apps, seed catalogs, set up whole verticals):
+
+```js
+await wx.recipes();           // categories with counts
+await wx.recipes("stores");   // a category's list — or any task word: wx.recipes("coupon")
+await wx.page(url);           // read the chosen recipe — whole when small, saved + outline when
+                              // big; then grep / read_file windows by the outline's line numbers
+```
+
+A matching recipe beats composing the flow from single endpoints: it carries ordering and
+cross-step gotchas no method page mentions.
+
+## Write the code
+
+**Response shapes obey the discover rule in every lane**: code against fields you saw in a live
+response or the schema — remembered names are often from older versions. Probe one real row first.
+
+### Admin calls — exec ad hoc, backend functions deployed
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+const data = await wx.post("https://www.wixapis.com/contacts/v5/contacts/query",   // spec-index publicUrl
+  { query: { cursorPaging: { limit: 10 } } }, accessToken);
+// let it throw — the thrown message is your result; .catch hides the answer
+return wx.clip({ error: null, count: data.contacts?.length, first: data.contacts?.[0] });
+//  ↑ one real row, whole — the shapes you code against live here, not in key names
+```
+
+The same call deploys as `base44/functions/*` (work the app does as the owner) — shipped code
+carries its own four-line fetch; the helpers are a build tool, not a runtime dependency.
+
+### A visitor client — src/lib/wixClient.js
+
+The "site for visitors" shape (What are you building?), in code — one file pages import. Neither
+`clientId` (from the context report) nor the minted token is a secret; together they are "an
+anonymous visitor", safe in shipped code:
+
+```js
+// src/lib/wixClient.js
+let token;
+const mint = async (body) => {
+  const r = await (await fetch("https://www.wixapis.com/oauth2/token", { method: "POST",
+    headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) })).json();
+  token = r.access_token; sessionStorage.setItem("wixRefresh", r.refresh_token);   // expires_in: 14400s = 4h
+};
+// first visit:  mint({ clientId: WIX_CLIENT_ID, grantType: "anonymous" });
+// on expiry:    mint({ refreshToken: sessionStorage.getItem("wixRefresh"), grantType: "refresh_token" });
+//               a fresh anonymous mint is a NEW visitor — the old one's cart goes with it
+export const wix = (path, opts = {}) => fetch("https://www.wixapis.com" + path, { ...opts,
+  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" } });
+```
+
+Token contract: `…/headless/authentication/retrieve-tokens`. Prove the lane in one exec before
+writing pages — mint a visitor, make one public read with it:
+
+```js
+const { access_token } = await wx.post("https://www.wixapis.com/oauth2/token",
+  { clientId: WIX_CLIENT_ID, grantType: "anonymous" });   // clientId: from the context report
+return await wx.post("<a public read from Learn Wix>", { query: {} }, access_token);
+// 200 ⇒ every visitor-facing page in the app is this same call, no server between
+// a lean default response isn't the whole shape — contracts often define a fields param
+// that opts INTO heavier parts (formatted prices, media); read the contract for it
+```

package/skills/wix-base44-connector/scripts/utils.js

@@ -0,0 +1,212 @@
+// Wix docs helpers for the Base44 sandbox — the scratch-lane set. Small results return
+// inline; anything over ~4,000 chars (exec results clip at ~5,000) is saved under the
+// scratch dir and comes back as { path, bytes, lines, outline } with the read tools
+// pre-pointed at it.
+//
+// Load per exec (execs share no state) — from disk, network only as first-touch fallback:
+//   const fs = require("fs"), P = ".agents/skills/wix-base44-connector/utils.js";
+//   if (!fs.existsSync(P)) { fs.mkdirSync(".agents/skills/wix-base44-connector", { recursive: true });
+//     fs.writeFileSync(P, await (await fetch("https://www.wix.com/skills/wix-base44-connector/scripts/utils.js")).text()); }
+//   const wx = (() => { const m = { exports: {} };
+//     new Function("module", "exports", "require", fs.readFileSync(P, "utf8"))(m, m.exports, require); return m.exports; })();
+//
+// Read a saved file the way you already know how: wx.bash("grep -n 'term' <path> | head -40")
+// to find, read_file(<path>) with offset/limit to window (numbered lines, 45K cap — no exec
+// round needed), pipelines for the rest (GNU grep/sed; awk is mawk; no rg).
+//
+// API responses are site data and stay OUT of scratch (scratch ships with the app):
+// post() never saves — project responses to facts.
+
+const fs = require("fs");
+const path = require("path");
+
+const BUDGET = 4000;
+const SCRATCH = ".agents/skills/wix-base44-connector/scratch";
+
+const clip = (out) => {
+  if (typeof out === "string")
+    return out.length <= BUDGET ? out : { truncated: true, total: out.length, head: out.slice(0, BUDGET) };
+  // absence must be visible: JSON.stringify silently ERASES undefined keys, so a probe like
+  // { lineItems: resp.cart?.lineItems } loses the very field that proves the call failed —
+  // render undefined as null instead
+  const s = JSON.stringify(out, (k, v) => v === undefined ? null : v);
+  return s.length <= BUDGET ? JSON.parse(s) : { truncated: true, total: s.length, head: s.slice(0, BUDGET) };
+};
+
+// One transport for every JSON call — Content-Type, optional Bearer, ok-guard.
+// Admin calls are this with the connector token: post(publicUrl, body, accessToken).
+async function post(url, body, token) {
+  const r = await fetch(url, { method: "POST", body: JSON.stringify(body),
+    headers: { "Content-Type": "application/json", ...(token && { Authorization: `Bearer ${token}` }) } });
+  if (!r.ok) {
+    const head = (await r.text()).slice(0, 300);
+    throw new Error(r.status + " " + head + (r.status < 500
+      ? " — a 4xx means wrong body or reference: read this endpoint's contract before changing the call"
+      : ""));
+  }
+  return r.json();
+}
+
+function save(name, text) {
+  const dir = path.join(process.cwd(), SCRATCH);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, name), text);
+  return { path: SCRATCH + "/" + name, bytes: Buffer.byteLength(text), lines: text.split("\n").length };
+}
+
+const outlineOf = (lines, cap = 30) => {
+  const heads = [];
+  lines.forEach((t, i) => { if (/^#{1,3} /.test(t)) heads.push({ line: i + 1, text: t.trim().slice(0, 80) }); });
+  return { outline: heads.slice(0, cap), outlineOmitted: Math.max(0, heads.length - cap) };
+};
+
+// A ref is a scratch path or the URL it came from — resolve to lines, fetching+saving
+// URLs on first touch (the .md suffix is appended for extensionless docs URLs).
+const slugOf = (url) => url.replace(/\?.*$/, "").split("/").pop().replace(/\.md$/, "") + ".md";
+async function resolveRef(ref) {
+  const isUrl = /^https?:/.test(ref);
+  const name = isUrl ? slugOf(ref) : ref.split("/").pop();
+  const file = path.join(process.cwd(), SCRATCH, name);
+  if (fs.existsSync(file)) return { path: SCRATCH + "/" + name, lines: fs.readFileSync(file, "utf8").split("\n") };
+  if (!isUrl) throw new Error("no such scratch file: " + ref + " — pass a returned path or the source URL");
+  const mdUrl = /\.[a-z]{2,5}$/.test(ref.replace(/\?.*$/, "")) ? ref : ref.replace(/\?.*$/, "") + ".md";
+  const res = await fetch(mdUrl);
+  if (!res.ok) throw new Error(res.status + " on " + mdUrl + " — not a docs page; take URLs from output, don't compose");
+  const text = await res.text();
+  const saved = save(name, text);
+  return { path: saved.path, lines: text.split("\n") };
+}
+
+// ── gather context ────────────────────────────────────────────────────────────
+
+// The dynamic context report — site data, never saved. No section → the whole report
+// when it fits, else its header outline; with one → that section's text. Empty
+// report = bad token, never an empty site.
+async function context(token, section) {
+  const { markdown } = await post(
+    "https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown", {}, token);
+  if (!section) {
+    if (markdown.length <= BUDGET) return markdown;   // most sites: the whole report, one round
+    return { truncated: true, total: markdown.length, head: markdown.slice(0, BUDGET),
+             note: "site data — never saved (no path); narrow: wx.context(token, '<section name>')" };
+  }
+  const m = markdown.match(new RegExp("^#{1,3} .*" + section + "[\\s\\S]*?(?=\\n#{1,3} |$)", "im"));
+  return clip({ total: markdown.length, section: m ? m[0] : "not found — call context(token) for the outline" });
+}
+
+// ── find what to read ─────────────────────────────────────────────────────────
+
+// Browse the docs tree — deterministic. menuUrl alone orients (children + counts);
+// filter before listing methods. An oversized listing is saved with its outline.
+async function browse(menuUrl, { include, filter, depth } = {}) {
+  const { content } = await post("https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse", {
+    menu_url: menuUrl, ...(include && { include }),
+    ...(filter && { name_filter: filter }), ...(depth && { depth }),
+  });   // 404 "No menu node found" ⇒ re-orient a level up
+  if (content.length <= BUDGET) return content;
+  const s = save("browse-" + (menuUrl.replace(/\/+$/, "").split("/").pop() || "root") + ".md", content);
+  return { ...s, next: `wx.bash("grep -in 'term' ${s.path} | head -40")   // one line per node — or re-browse with a filter` };
+}
+
+// Semantic search — ranks, never says "no match". The reduced hits come back inline
+// AND the full raw content is saved for grep/window follow-ups.
+async function search(term, { type = "REST", max = 5, lines = 6 } = {}) {
+  const { content } = await post("https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown",
+    { search_term: term, document_type: type, maximum_results: max, lines_in_each_result: lines });
+  const hits = content.split(/\n---\n+(?=#### )/).map(b => ({
+    method:   (b.match(/^# Method: (.+)$/m) || [])[1],
+    endpoint: (b.match(/^# Method API Endpoint: (.+)$/m) || [])[1],   // callable
+    docsUrl:  (b.match(/#### \[[^\]]+\]\((https:[^)]+)\)/) || [])[1],
+    gist: ((b.match(/## Method Description:\s*\n([\s\S]{0,400})/) || [])[1] || "")
+      .trim().replace(/\s+/g, " ").slice(0, 220),
+  })).filter(h => h.docsUrl);
+  const saved = save("search-" + term.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 40) + ".md", content);
+  if (!hits.length) return clip({ ...saved, head: content.slice(0, 1200),
+    note: `no method blocks parsed — raw head above; wx.bash("grep -in 'term' ${saved.path}") for the rest` });
+  return clip({ ...saved, hits });
+}
+
+// ── read a page (docs pages and recipes alike) ────────────────────────────────
+
+// Fetch + save + map in one round: whole text inline when small, else
+// { path, bytes, lines, outline } — the outline's line numbers feed grep and read_file windows.
+async function page(url) {
+  const { path: p, lines } = await resolveRef(url);
+  const text = lines.join("\n");
+  if (text.length <= BUDGET) return text;
+  const o = outlineOf(lines);
+  const bytes = Buffer.byteLength(text);
+  return { path: p, bytes, lines: lines.length, ...o,
+           next: [
+             `wx.bash("grep -in 'term' ${p} | head -40")`,
+             bytes <= 45000 ? `read_file ${p}   // whole (fits the 45K cap), or a window via offset/limit`
+                            : `read_file ${p} with offset/limit   // window a section by the outline's lines`,
+           ] };
+}
+
+// ── shell ─────────────────────────────────────────────────────────────────────
+
+// Compose native pipelines over scratch — grep -n, sed -n, mawk, sort, uniq, wc
+// (GNU grep/sed; awk is mawk; no rg). Cap your own output (| head -40); the return
+// clips regardless. grep's exit 1 means no match, not failure — the return says so.
+function bash(cmd) {
+  const { execSync } = require("child_process");
+  try {
+    const out = execSync(cmd, { timeout: 15000, encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
+    return out.trim() ? clip(out)
+      : "(no output — a filter may have swallowed the signal; rerun without the reducer)";
+  } catch (e) {
+    const exit = e.status ?? null, err = (e.stderr || "").toString().trim();
+    return { exit, ...(err && { err: err.slice(0, 300) }),
+             out: clip((e.stdout || "").toString()),
+             ...(exit === 1 && !err && { note: "exit 1 with no stderr — a no-match, not a failure" }) };
+  }
+}
+
+// ── the spec index ────────────────────────────────────────────────────────────
+
+// Run a query over the API spec index. In scope: lightIndex (RESOURCES with
+// .methods — operationId, summary, httpMethod, path [PARTIAL — never call it],
+// publicUrl [callable], docsUrl) and getResourceSchemaByUrl(docsUrl). Arrive with
+// a docsUrl and match by it — also the only proof an API does NOT exist.
+// A big result is saved as JSON; grep it for the keys you saw in its head.
+async function spec(code) {
+  if (!/^\s*async function/.test(code)) code = `async function(){ ${code} }`;
+  const { result } = await post("https://mcp.wix.com/api/code-mode/search", { code });
+  if (result == null || (Array.isArray(result) && !result.length))
+    return { result, note: "empty — the query missed the shape, not proof of absence; find the resource by docsUrl on lightIndex" };
+  const text = JSON.stringify(result, null, 1);
+  if (text.length <= BUDGET) return result;
+  return { ...save("spec.json", text),
+           shape: Array.isArray(result) ? `Array(${result.length})` : Object.keys(result || {}).slice(0, 15),
+           head: text.slice(0, 600) };
+}
+
+// ── management recipes ────────────────────────────────────────────────────────
+
+// ~100 curated multi-step admin flows. No arg → categories with counts; a category
+// name → its recipes; any other term → search every recipe's name + gist for it.
+// Read the chosen url with page(url), then grep/window/fields.
+async function recipes(q) {
+  const { base, files } = await (await fetch("https://dev.wix.com/docs/skills/manage.manifest.json")).json();
+  const cat = f => (f.path.match(/^references\/([^/]+)\//) || [])[1];
+  const row = f => ({ name: f.name, cat: cat(f), gist: (f.description || "").slice(0, 120),
+                      url: base + f.path, kb: Math.round(f.size / 1024) });
+  if (!q) {
+    const cats = {};
+    for (const f of files) { const c = cat(f); if (c) cats[c] = (cats[c] || 0) + 1; }
+    return cats;
+  }
+  const inCat = files.filter(f => cat(f) === q);
+  if (inCat.length) return clip(inCat.map(row));
+  const re = new RegExp(q, "i");
+  const m = files.filter(f => re.test(f.name + " " + (f.description || "")));
+  if (!m.length) {
+    const cats = {};
+    for (const f of files) { const c = cat(f); if (c) cats[c] = (cats[c] || 0) + 1; }
+    return { note: `nothing matches "${q}" — the categories:`, categories: cats };
+  }
+  return clip(m.map(row));
+}
+
+module.exports = { post, clip, context, browse, search, page, bash, spec, recipes };

package/skills/wix-design-system/SKILL.md

@@ -95,27 +95,27 @@ Don't read these files fully. Grep for keywords, then read specific sections wit
 
 ## Quick Component Mapping (Design to WDS)
 
-| Design Element | WDS Component | Notes |
-| --- | --- | --- |
-| Rectangle/container | `<Box>` | Layout wrapper |
-| Text button | `<TextButton>` | Secondary actions |
-| Input with label | `<FormField>` + `<Input>` | Wrap inputs |
-| Toggle | `<ToggleSwitch>` | On/off settings |
-| Modal | `<Modal>` + `<CustomModalLayout>` | Use together |
-| Grid | `<Layout>` + `<Cell>` | Responsive |
+| Design Element      | WDS Component                     | Notes             |
+| ------------------- | --------------------------------- | ----------------- |
+| Rectangle/container | `<Box>`                           | Layout wrapper    |
+| Text button         | `<TextButton>`                    | Secondary actions |
+| Input with label    | `<FormField>` + `<Input>`         | Wrap inputs       |
+| Toggle              | `<ToggleSwitch>`                  | On/off settings   |
+| Modal               | `<Modal>` + `<CustomModalLayout>` | Use together      |
+| Grid                | `<Layout>` + `<Cell>`             | Responsive        |
 
 ## Spacing (px to SP conversion)
 
 When designer specifies pixels, convert to the nearest SP token:
 
 | Token | Classic | Studio |
-| --- | --- | --- |
-| `SP1` | 6px | 4px |
-| `SP2` | 12px | 8px |
-| `SP3` | 18px | 12px |
-| `SP4` | 24px | 16px |
-| `SP5` | 30px | 20px |
-| `SP6` | 36px | 24px |
+| ----- | ------- | ------ |
+| `SP1` | 6px     | 4px    |
+| `SP2` | 12px    | 8px    |
+| `SP3` | 18px    | 12px   |
+| `SP4` | 24px    | 16px   |
+| `SP5` | 30px    | 20px   |
+| `SP6` | 36px    | 24px   |
 
 ```tsx
 <Box gap="SP2" padding="SP3">
@@ -130,6 +130,10 @@ import { Button, Card, Image } from "@wix/design-system";
 import { Add, Edit, Delete } from "@wix/wix-ui-icons-common";
 ```
 
+## GUIDELINES
+
+1. Don't ever override WDS CSS tokens. Only if it's not possible otherwise, mention that very clearly to the prompter, that this is an anti-pattern and should be avoided at all costs.
+
 ### Troubleshooting
 
 - **Components render unstyled** (plain HTML look, missing WDS spacing/typography): add `import "@wix/design-system/styles.global.css";` once to the root/main component (e.g. `page.tsx`, modal entry) — not child/tab/helper files.

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-manage/SKILL.md

@@ -166,8 +166,8 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 ## Domains
 
-### [Domain Search and Purchase](references/domains/domain-search-and-purchase.md)
-**Technical:** Search for available domains, get domain suggestions, and generate purchase links using Domain Search V2 API. Covers availability checks, TLD filtering, and connecting domains to Wix sites.
+### [Domain Search, Purchase and Connect](references/domains/domain-search-purchase-and-connect.md)
+**Technical:** Purchase domains, connect domains to Wix sites, search for available domains and get domain suggestions. Covers availability checks, TLD filtering, purchase flow and connecting domains to Wix sites.
 
 ### [Domains Dashboard Navigation](references/domains/domains-dashboard-navigation.md)
 **Technical:** Direct links to the site-level domain settings page and the account-level My Domains page on manage.wix.com, paired with the Domain Search read APIs.
@@ -230,10 +230,10 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ## Events
 
 ### [Create Event](references/events/create-wix-event.md)
-**Technical:** Creates an event with the Wix Events V3 API — required request body, ISO-8601 date and time settings, venue/online/TBD location and street addresses, RSVP vs ticketed registration, guest capacity, and short vs Ricos rich-text descriptions. Distinguishes Wix Events from the Calendar, Marketing Calendar and Automations APIs that share the "events" name. Key endpoint: /events/v3/events.
+**Technical:** Creates an event with the Wix Events V3 API — required request body, ISO-8601 date and time settings, venue/online/TBD location and street addresses, RSVP vs ticketed registration, guest capacity, short vs Ricos rich-text descriptions, ticket tiers and pricing, and recurring series from explicit occurrence dates. Distinguishes Wix Events from the Calendar, Marketing Calendar and Automations APIs that share the "events" name. Key endpoints: /events/v3/events, /events/v3/ticket-definitions.
 
 ### [Manage Events](references/events/manage-wix-events.md)
-**Technical:** Manages existing events with the Wix Events V3 API — ticket definitions and pricing (fixed, free, donation, multiple tiers), publishing a draft, cancelling, deleting, cloning, updating an event's date, counting events, and building recurring series from explicit occurrence dates. Key endpoints: /events/v3/events, /events/v3/ticket-definitions.
+**Technical:** Operates on events that already exist with the Wix Events V3 API — publishing a draft, cancelling, deleting, cloning, updating an event's date, and counting events, plus the draft-event permission that makes those calls fail with 403. Key endpoint: /events/v3/events.
 
 ---
 
@@ -367,9 +367,15 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Create Headless Site](references/sites/create-headless-site.md)
 **Technical:** Creates a Wix Headless site (headless business) with one account-level API call — site, Wix Business Solution apps, and a configured OAuth client.
 
+### [Manage OAuth Apps](references/sites/manage-oauth-apps.md)
+**Technical:** Create, read, update, and query OAuth apps for a Wix headless site. Each OAuth app's `id` is the `client_id` for frontends connecting to the site's Wix APIs. Secret and rotation are dashboard-only.
+
 ### [Query Sites](references/sites/query-sites.md)
 **Technical:** Lists and queries all sites associated with a Wix account using Sites API. Covers pagination with cursor-based navigation.
 
+### [Read Account or Site Context](references/sites/read-site-context.md)
+**Technical:** One call that returns a site's installed apps (by display name), locale, currency, status, and catalog version. Replaces separate query-sites + list-installed-apps + site-properties calls. Use this first on any unfamiliar site to decide which management recipes to follow.
+
 ### [Site Import](references/sites/site-import.md)
 **Technical:** Drives the autonomous Wix Site Import agent over REST (`/site-import/v1/imports`) to migrate a store/site from another platform (Shopify, WooCommerce, Magento, or any URL) into Wix. Covers Start/Poll/Reply/Cancel, relaying agent questions and progress in plain language, handling `DEPLOYED`/`FAILED`/`AUTH_EXPIRED`/`SESSION_EXPIRED` states, and post-deploy follow-up changes. Use when the user wants to import, migrate, or clone an existing store/site into Wix.
 
@@ -383,18 +389,11 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Add Store Pages to Site](references/stores/add-store-pages-to-site.md)
 **Technical:** Adds missing checkout and cart pages to a site when Stores app is installed. Used when store pages are missing after migration or setup issues.
 
-### [Bulk Create Products with Options](references/stores/bulk-create-products-with-options.md)
-**Technical:** Uses bulk products endpoint to create multiple products with inventory in a single request. Handles variant generation from options, media format requirements, and error handling for partial failures.
-
-### [Create Product from Image](references/stores/create-product-from-image.md)
-**Technical:** **MANDATORY entry point** for any "create product from image" or "create product from photo" request. STEP 1 auto-detects the site's catalog version (V1/V3) via the provision endpoint, then runs the matching flow inline — V3 supports up to 3 images, info sections, SEO, options/variants, and atomic creation; V1 supports a single image, simple product, and a separate media-attach call. Combines Media Upload + LLM analysis + Product Creation + (V1 only) Add Product Media in one self-contained recipe.
-
-
 ### [Create Product (Catalog V1)](references/stores/create-product-catalog-v1.md)
 **Technical:** Create products using the Catalog V1 Products API. Use this recipe when the site's catalog version is CATALOG_V1. Covers simple product creation, product with options, and key V1 request structure differences from V3.
 
-### [Create Product with Options (Catalog V3)](references/stores/create-product-with-options-catalog-v3.md)
-**Technical:** Single product creation with options using Catalog V3 Products API. Covers option types (TEXT_CHOICES, SWATCH_CHOICES), choice configuration, and automatic variant generation.
+### [Create Product (Catalog V3)](references/stores/create-product-catalog-v3.md)
+**Technical:** **Mandatory first read for every Catalog V3 create-product request, including vague requests.** Before any other documentation or API tool, load exactly `https://dev.wix.com/docs/api-reference/business-solutions/stores/skills/create-product-catalog-v3`. When no product is identified, that recipe read must be the final tool call; respond only: “What product would you like to create? You can upload up to 3 images and I’ll generate the product information from them, or describe the product in text.” Then stop. **Never replace this with a list or questions for name, price, description, type, images, inventory, SKU, options, SEO, or other fields.** If name or price is missing, ask for it or offer to suggest it, then stop. When name and price are present, create from supplied details without requiring optional enrichment. Never default price to `0`. The recipe owns single/bulk endpoint choice, inventory, physical/digital products, images, options, variants, prices, SKUs, limits, and validation.
 
 ### [Find Products (Query and Search, Catalog V3)](references/stores/find-products-query-and-search-catalog-v3.md)
 **Technical:** Find, search, query, and list products from a Wix Store using Catalog V3 Search Products and Query Products endpoints. Explains when to use each endpoint, correct fields enum values, filtering, sorting, and paging.
@@ -402,9 +401,6 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Query Products (Catalog V1)](references/stores/query-products-catalog-v1.md)
 **Technical:** Query and list products from a Wix Store using the Catalog V1 Query Products endpoint. Use this recipe when the site's catalog version is CATALOG_V1. Covers basic queries, filtering, sorting, and paging.
 
-### [Setup Online Store (Catalog V3)](references/stores/setup-online-store-catalog-v3.md)
-**Technical:** Initializes a Stores catalog with Catalog V3 Products API, bulk products endpoint, and Categories API. Covers product creation, option configuration, variant management, and category assignment.
-
 ### [Update Product Pre-Order](references/stores/update-product-pre-order.md)
 **Technical:** Manages pre-order settings for product variants using V3 Inventory API. Covers enabling/disabling pre-orders, setting messages, configuring limits, and handling trackQuantity requirements.