@wix/agent-skills 1.18.2 → 1.19.1

package/skills/wix-app/scripts/scan-a11y-review.cjs

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+'use strict';
+
+// oxlint-disable no-console preserve-caught-error
+
+/**
+ * Accessibility review for Editor React Components: one command, one JSON report.
+ *
+ *   node <SKILL_ROOT>/scripts/scan-a11y-review.cjs <component-dir | files...>
+ *
+ * Runs the jsx-a11y ESLint scanner and the Babel semantic/contract scanner in
+ * process, spawns the render audit (SSR + jsdom + axe-core) per component
+ * folder, and groups the findings by rule.
+ *
+ * Exit codes: 0 every scanner ran and found nothing, 1 findings, 2 a scanner
+ * could not run or could not load the component (never treat 2 as clean).
+ * Test hook: `A11Y_SKIP_RENDER=1` skips the render audit; the review is then
+ * inconclusive (exit 2) even with no findings.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = process.cwd();
+const RENDER_SCRIPT = path.join(__dirname, 'scan-a11y-render.cjs');
+const RENDER_TIMEOUT_MS = Number(process.env.A11Y_RENDER_TIMEOUT_MS) || 20_000;
+const MAX_LOCATIONS_PER_GROUP = 5;
+const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
+const CONFIDENCE_RANK = { high: 0, medium: 1, low: 2, unknown: 3 };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Arguments and discovery
+// ─────────────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const options = { targets: [], render: process.env.A11Y_SKIP_RENDER !== '1' };
+  for (const arg of argv) {
+    if (arg.startsWith('--')) throw new Error(`Unknown option ${arg}`);
+    options.targets.push(arg);
+  }
+  return options;
+}
+
+const isSource = (name) =>
+  /\.(tsx|jsx)$/.test(name) && !/\.(stories|test|spec)\.[jt]sx$/.test(name);
+
+function listSources(dir, acc = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== 'node_modules') listSources(full, acc);
+    } else if (entry.isFile() && isSource(entry.name)) acc.push(full);
+  }
+  return acc;
+}
+
+function isComponentDir(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return false;
+  const names = fs.readdirSync(dir);
+  return names.includes('component.tsx') || names.some((name) => name.endsWith('.props.ts'));
+}
+
+function findComponentDir(file) {
+  let dir = path.dirname(file);
+  for (let depth = 0; depth < 6 && !isComponentDir(dir); depth++) {
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.dirname(file);
+    dir = parent;
+  }
+  return isComponentDir(dir) ? dir : path.dirname(file);
+}
+
+/** Expand targets (component folders, a components root, or files) into files and component folders. */
+function discoverFiles(targets) {
+  const files = new Set();
+  const componentDirs = new Set();
+  for (const target of targets) {
+    const resolved = path.resolve(target);
+    if (!fs.existsSync(resolved)) throw new Error(`Path not found: ${target}`);
+    if (fs.statSync(resolved).isDirectory()) {
+      if (isComponentDir(resolved)) componentDirs.add(resolved);
+      else {
+        for (const entry of fs.readdirSync(resolved, { withFileTypes: true })) {
+          const child = path.join(resolved, entry.name);
+          if (entry.isDirectory() && isComponentDir(child)) componentDirs.add(child);
+        }
+      }
+      for (const file of listSources(resolved)) files.add(file);
+    } else {
+      files.add(resolved);
+      componentDirs.add(findComponentDir(resolved));
+    }
+  }
+  return { files: [...files].toSorted(), componentDirs: [...componentDirs].toSorted() };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Scanners
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function runScanner(name, load) {
+  const started = Date.now();
+  try {
+    const value = await load();
+    const parseErrors = (value.meta && value.meta.parseErrors) || [];
+    if (parseErrors.length) {
+      throw new Error(parseErrors.map((e) => `${e.file}: ${e.message}`).join('; '));
+    }
+    return { ok: true, ms: Date.now() - started, value };
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    return { ok: false, ms: Date.now() - started, error: `${name}: ${message}` };
+  }
+}
+
+function eslintFindings(report) {
+  return report.findings.map((f) => ({
+    rule: f.rule,
+    source: 'eslint',
+    severity: 'high',
+    confidence: 'high',
+    message: f.message,
+    at: `${f.file}:${f.line}:${f.column}`,
+  }));
+}
+
+function semanticFindings(report) {
+  return report.findings.map((f) => {
+    const contract = f.sourceKind === 'contract';
+    const severity =
+      contract || f.confidence === 'high' ? 'high' : f.confidence === 'medium' ? 'medium' : 'low';
+    return {
+      rule: f.rule,
+      source: contract ? 'contract' : 'semantic',
+      severity,
+      confidence: f.confidence,
+      message: f.message,
+      detail: contract ? null : f.evidence,
+      at: `${f.file}:${f.line}:${f.column}`,
+    };
+  });
+}
+
+function runRenderChild(componentDir) {
+  const relativeDir = path.relative(ROOT, componentDir) || '.';
+  const started = Date.now();
+  const result = spawnSync(process.execPath, [RENDER_SCRIPT, componentDir], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    timeout: RENDER_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
+    maxBuffer: 8 * 1024 * 1024,
+    env: { ...process.env, NODE_ENV: process.env.NODE_ENV || 'development' },
+  });
+  const base = { componentDir: relativeDir, ms: Date.now() - started };
+
+  if (result.error && result.error.code === 'ETIMEDOUT') {
+    return {
+      ...base,
+      ok: false,
+      reason: 'timeout',
+      findings: [
+        {
+          rule: 'render-timeout',
+          source: 'render',
+          severity: 'high',
+          confidence: 'high',
+          message: `Rendering ${relativeDir} did not finish within ${RENDER_TIMEOUT_MS} ms. Rerun once; if it repeats, the first render never settles.`,
+        },
+      ],
+    };
+  }
+
+  let report = null;
+  try {
+    const lastLine = String(result.stdout || '')
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .pop();
+    report = lastLine ? JSON.parse(lastLine) : null;
+  } catch {
+    report = null;
+  }
+  if (!report) {
+    const error = truncate(result.stderr || `exit ${result.status}`, 400);
+    return { ...base, ok: false, reason: 'crash', error, findings: [] };
+  }
+  if (!report.ok) {
+    return {
+      ...base,
+      ok: false,
+      reason: report.reason || 'error',
+      error: report.error || null,
+      findings: [],
+    };
+  }
+  return {
+    ...base,
+    ok: true,
+    entry: report.entry,
+    preview: report.preview,
+    ssr: report.ssr,
+    axeRules: report.axe ? report.axe.rulesRun : null,
+    notChecked: report.notChecked || [],
+    findings: report.findings.map((f) => ({
+      ...f,
+      source: 'render',
+      at: f.target ? `${relativeDir} ${f.target}` : relativeDir,
+    })),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Report
+// ─────────────────────────────────────────────────────────────────────────────
+
+function truncate(text, length) {
+  const compact = String(text || '').replace(/\s+/g, ' ');
+  return compact.length > length ? `${compact.slice(0, length - 1)}…` : compact;
+}
+
+/** One entry per (source, rule, message); repeated nodes become a count plus a few locations. */
+function groupFindings(findings, { capPerGroup = MAX_LOCATIONS_PER_GROUP } = {}) {
+  const groups = new Map();
+  for (const f of findings) {
+    const severity = f.severity in SEVERITY_RANK ? f.severity : 'medium';
+    const confidence = f.confidence in CONFIDENCE_RANK ? f.confidence : 'medium';
+    const key = `${f.source}|${f.rule}|${f.message}`;
+    if (!groups.has(key)) {
+      groups.set(key, {
+        rule: f.rule,
+        src: f.source,
+        sev: severity,
+        conf: confidence,
+        n: 0,
+        at: [],
+        html: f.html || null,
+        msg: f.message,
+        detail: f.detail || null,
+        helpUrl: f.helpUrl || null,
+      });
+    }
+    const group = groups.get(key);
+    group.n++;
+    if (f.at && group.at.length < capPerGroup && !group.at.includes(f.at)) group.at.push(f.at);
+    if (SEVERITY_RANK[severity] < SEVERITY_RANK[group.sev]) group.sev = severity;
+    if (CONFIDENCE_RANK[confidence] < CONFIDENCE_RANK[group.conf]) group.conf = confidence;
+  }
+  return [...groups.values()].toSorted(
+    (a, b) =>
+      SEVERITY_RANK[a.sev] - SEVERITY_RANK[b.sev] ||
+      CONFIDENCE_RANK[a.conf] - CONFIDENCE_RANK[b.conf] ||
+      b.n - a.n ||
+      a.rule.localeCompare(b.rule),
+  );
+}
+
+function renderLabel(result) {
+  if (result.ok) {
+    if (!result.ssr || !result.ssr.ok) return `render: ssr FAILED (${result.entry || '?'})`;
+    return `render ok (${result.entry || '?'}, axe ${result.axeRules ?? '-'})`;
+  }
+  return `render FAILED (${result.reason})`;
+}
+
+function buildSummary(groups, scanners, { renderEnabled = true } = {}) {
+  const counts = { high: 0, medium: 0, low: 0, groups: groups.length, findings: 0 };
+  for (const group of groups) {
+    counts[group.sev] += group.n;
+    counts.findings += group.n;
+  }
+  // A timeout is itself a finding; any other render failure (missing tooling,
+  // a module the audit cannot load) or a skipped render means the audit did
+  // not run, never clean.
+  const staticFailed = !scanners.eslint.ok || !scanners.semantic.ok;
+  const renderBroken =
+    !renderEnabled || scanners.render.some((r) => !r.ok && r.reason !== 'timeout');
+  const status =
+    staticFailed || renderBroken ? 'error' : counts.findings > 0 ? 'findings' : 'clean';
+  const severities = ['high', 'medium', 'low']
+    .filter((level) => counts[level] > 0)
+    .map((level) => `${counts[level]} ${level}`);
+  const line = [
+    `A11Y ${counts.groups} groups/${counts.findings} findings${severities.length ? ` (${severities.join(', ')})` : ''}`,
+    `eslint ${scanners.eslint.ok ? 'ok' : 'FAILED'}`,
+    `semantic ${scanners.semantic.ok ? 'ok' : 'FAILED'}`,
+    renderEnabled
+      ? scanners.render.map(renderLabel).join(' · ') || 'render: no component folder'
+      : 'render SKIPPED (inconclusive)',
+  ].join(' · ');
+  return { status, line, counts };
+}
+
+const computeExitCode = (summary) =>
+  summary.status === 'error' ? 2 : summary.counts.findings > 0 ? 1 : 0;
+
+async function review(options) {
+  const { files, componentDirs } = discoverFiles(options.targets);
+  // A wrong path (a typo, a parent folder) must never read as clean.
+  if (componentDirs.length === 0) {
+    throw new Error(
+      `No component folder under ${options.targets.join(', ')}: expected component.tsx or *.props.ts.`,
+    );
+  }
+
+  // ESLint rejects an empty file list; a folder with no JSX still gets its render audit.
+  const eslint = await runScanner('eslint', () =>
+    files.length ? require('./scan-a11y-eslint.cjs').scan(files) : { findings: [] },
+  );
+  const semantic = await runScanner('semantic', () =>
+    files.length ? require('./scan-a11y-code.cjs').scan(files) : { findings: [] },
+  );
+  const render = options.render ? componentDirs.map(runRenderChild) : [];
+
+  const findings = [
+    ...(eslint.ok ? eslintFindings(eslint.value) : []),
+    ...(semantic.ok ? semanticFindings(semantic.value) : []),
+    ...render.flatMap((r) => r.findings),
+  ];
+  const groups = groupFindings(findings);
+
+  const notChecked = new Set(options.render ? [] : ['render audit (skipped)']);
+  for (const r of render) {
+    for (const item of r.notChecked || []) notChecked.add(item);
+  }
+
+  const scanners = {
+    eslint: { ok: eslint.ok, ms: eslint.ms, error: eslint.error || null },
+    semantic: { ok: semantic.ok, ms: semantic.ms, error: semantic.error || null },
+    render: render.map(({ findings: _findings, notChecked: _notChecked, ...rest }) => rest),
+  };
+  const summary = buildSummary(groups, scanners, { renderEnabled: options.render });
+  return {
+    summary,
+    findings: groups,
+    scanners,
+    files: files.map((file) => path.relative(ROOT, file)),
+    notChecked: [...notChecked],
+    exitCode: computeExitCode(summary),
+  };
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+    if (options.targets.length === 0) throw new Error('No component directory or files specified.');
+  } catch (error) {
+    console.error(
+      `${error.message}\nUsage: node <SKILL_ROOT>/scripts/scan-a11y-review.cjs <component-dir | files...>`,
+    );
+    process.exit(2);
+  }
+  try {
+    const report = await review(options);
+    console.log(JSON.stringify(report));
+    process.exit(report.exitCode);
+  } catch (error) {
+    console.log(
+      JSON.stringify({
+        summary: { status: 'error', line: error.message, counts: { findings: 0 } },
+        findings: [],
+      }),
+    );
+    process.exit(2);
+  }
+}
+
+module.exports = { review, discoverFiles, groupFindings, buildSummary, computeExitCode };
+
+if (require.main === module) main();

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

@@ -47,6 +47,9 @@ management tools, or do both.
 visitor, never the admin connector token. Call Wix directly from the browser through one shared
 visitor client (Write the code, below). Redirect sessions for Wix-hosted flows also require a
 visitor token minted for the headless OAuth app; see Visitor authentication and Wix-hosted flows below.
+**The OAuth app is a one-call prerequisite, not a dead end**: `wx.ensureOAuthApp` returns its
+`clientId`, creating the app when the site has none, so it is a visitor flow's first step — never
+a reason to move the flow onto the admin token or leave it for later.
 Anyone can mint an anonymous visitor token from the
 OAuth app's public `clientId`; no visitor login is required. APIs for the "current visitor"
 use that token to identify whose data and state to access. This applies both to a standalone
@@ -90,6 +93,7 @@ const wx = require(require("path").resolve(P));
 - `wx.bash(cmd)` — shell over saved files (GNU grep/sed; awk is mawk; no rg)
 - `wx.spec(docsUrl | code)` — a method's exact schema, plus the titles of the docs' own request examples saved at `examplesPath`; pass a hit's docsUrl (direct load), or raw code to query the index yourself
 - `wx.mgmtRecipes(q?)` — management-recipe index; no arg → categories, a word → matching recipes
+- `wx.ensureOAuthApp(token, { name, redirectUris, redirectDomains })` — the headless OAuth app, found by name or created, with the redirect lists merged into whatever it already allows; returns `{ clientId, created }`. `clientId` is what the browser mints visitor tokens from. Run it whenever `context` reports no OAuth app, or before any Wix-hosted flow that returns to this app — see Visitor authentication and Wix-hosted flows
 - `wx.installApp(appDefId, siteId, token)` — install a Wix app on the site (Apps Installer). If discovery finds an API whose app isn't installed on the site, install it first — that's a one-call prerequisite, **not** a reason to fall back to a hand-built alternative. `appDefId` from `search` or the Apps-Created-by-Wix table; `siteId` from `context` (the site report)
 
 Search makes one combined request across REST, management recipes, and Headless by default.
@@ -228,7 +232,9 @@ Want to shape the result yourself? Pass raw code against the index (`lightIndex`
 await wx.spec(`
   const url = "<docsUrl from search/browse>";           // API method page, not a skill/article page
   const s = await getResourceSchemaByUrl(url);
-  const m = s.methods.find(x => x.docsUrl === url);
+  // A method URL resolves to exactly that method — take methods[0]. Don't match on docsUrl:
+  // the reader normalizes the url, so equality against the one you passed can miss.
+  const m = s.methods[0];
   return {
     call: m.publicUrl,                                       // callable https://www.wixapis.com/… URL
     body: m.requestBody?.content["application/json"].schema.properties,
@@ -327,13 +333,15 @@ return await wx.post("<a public read from Learn Wix>", { query: {} }, visitorTok
 
 **Any Wix-hosted flow that returns the visitor to your app needs the headless OAuth app's
 redirect config set.** This covers redirect sessions *and* sending a buyer to the Wix-hosted
-checkout `checkoutUrl` and back — any flow where Wix redirects to a URL on your app. Use the
-OAuth app's `clientId` from `wx.context()`; if the report has no OAuth app, create one with the
-admin connector token as shown below, then mint a visitor token from its `clientId` (anonymous
-visitors do not need to log in). **Always set `allowedRedirectUris` and `allowedRedirectDomains`
-when you create it** — an OAuth app created with a name only cannot complete any return, and the
-break is silent (create-checkout and the anonymous token still succeed) until a real buyer is
-redirected and stranded on Wix.
+checkout `checkoutUrl` and back — any flow where Wix redirects to a URL on your app.
+
+**Step one of any visitor flow: `wx.ensureOAuthApp` with this app's own URLs.** It returns the
+`clientId` the frontend mints visitor tokens from (anonymous visitors do not need to log in),
+creating the OAuth app when the site has none and adding your URLs to its lists when it already
+has one. Returns only complete for URLs in those lists, and a missing one breaks silently —
+create-checkout and the anonymous token still succeed — until a real buyer is redirected and
+stranded on Wix. It is idempotent by name: never create a second OAuth app for the same Base44
+app, or the first `clientId`'s returns stop working.
 
 ```js
 // Register BOTH of this app's own URLs — its preview URL and its published URL — so returns work
@@ -353,20 +361,14 @@ const returnDomains = appOrigins.map(origin => new URL(origin).hostname);
 // OAuth redirect configuration: exact login URLs versus domains for other returns.
 // https://dev.wix.com/docs/go-headless/authentication/setup/allow-redirect-uris-and-domains.md
 const { accessToken: adminToken } = await base44.asServiceRole.connectors.getConnection("wix");
-const { oAuthApp } = await wx.post("https://www.wixapis.com/oauth-app/v1/oauth-apps", {
-  oAuthApp: {
-    name: "My App",
-    // Login callbacks: the authorization request's redirect URI must match exactly.
-    allowedRedirectUris: loginCallbacks,
-    // Returns from Wix-hosted flows: hostnames only, allowing URLs under each domain.
-    allowedRedirectDomains: returnDomains,
-  },
-}, adminToken);
-const clientId = oAuthApp.id; // Public visitor client ID, used by the frontend client above.
-
-// If destinations change later, update this OAuth app rather than creating another.
-// Read its existing lists and merge new entries before updating, preserving old entries.
-// https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/update-oauth-app.md
+const { clientId, created } = await wx.ensureOAuthApp(adminToken, {
+  name: "My App",                     // this app's name; the lookup key on later runs
+  redirectUris: loginCallbacks,       // login callbacks: matched exactly by the auth request
+  redirectDomains: returnDomains,     // returns from Wix-hosted flows: hostnames only
+});
+// clientId is the public visitor client id the frontend client above mints from.
+// When destinations change later — a custom domain, a renamed app — call this again with the
+// new URLs: it updates the same OAuth app and preserves the entries already there.
 
 ```
 

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

@@ -353,9 +353,13 @@ async function spec(arg) {
   const code = /^async function/.test(s) ? s
     : /^https:\/\/dev\.wix\.com\/docs\//.test(s) ? "async function(){ return await getResourceSchemaByUrl(" + JSON.stringify(s) + "); }"
     : "async function(){ " + s + " }";
-  const { result } = await post("https://mcp.wix.com/api/code-mode/search", { code });
+  const { result, error } = await post("https://mcp.wix.com/api/code-mode/search", { code });
+  // The envelope is 200 even when the query throws — the cause is in `error`, not the status.
+  // Surfacing it matters: swallowing it turns "your code threw" into "nothing matched".
+  if (error)
+    return { error, note: "the query threw — read the message and fix the code; don't re-send it unchanged" };
   if (result == null || (Array.isArray(result) && !result.length))
-    return { result, note: "empty — the query missed the shape; match your docsUrl against s.methods[].docsUrl" };
+    return { result, note: "the query ran but matched nothing — widen it, or check the url resolves" };
   const text = JSON.stringify(result, null, 1);
   if (text.length <= BUDGET) return result;
   let h = 5381;
@@ -424,4 +428,36 @@ async function installApp(appDefId, siteId, token) {
     { tenant: { tenantType: "SITE", id: siteId }, appInstance: { appDefId } }, token);
 }
 
-module.exports = { req, post, get, patch, put, del, clip, context, browse, search, page, bash, spec, mgmtRecipes, installApp };
+// The headless OAuth app: the visitor client id, and the redirect config every Wix-hosted
+// return needs. Idempotent by name — a site reached by the "connect an existing site" flow
+// has none, and creating a second one for the same app strands the first app's returns.
+// Redirect lists are merged, never replaced: an app that already serves a custom domain
+// keeps it when a preview URL is added.
+async function ensureOAuthApp(token, { name, redirectUris = [], redirectDomains = [] }) {
+  const { oAuthApps = [] } = await post(
+    "https://www.wixapis.com/oauth-app/v1/oauth-apps/query", { query: {} }, token);
+  const existing = oAuthApps.find((a) => a.name === name);
+  const merge = (a = [], b = []) => [...new Set([...a, ...b])];
+  if (!existing) {
+    const { oAuthApp } = await post("https://www.wixapis.com/oauth-app/v1/oauth-apps", {
+      oAuthApp: { name, allowedRedirectUris: redirectUris, allowedRedirectDomains: redirectDomains },
+    }, token);
+    return { clientId: oAuthApp.id, created: true, oAuthApp };
+  }
+  const allowedRedirectUris = merge(existing.allowedRedirectUris, redirectUris);
+  const allowedRedirectDomains = merge(existing.allowedRedirectDomains, redirectDomains);
+  const unchanged =
+    allowedRedirectUris.length === (existing.allowedRedirectUris || []).length &&
+    allowedRedirectDomains.length === (existing.allowedRedirectDomains || []).length;
+  if (unchanged) return { clientId: existing.id, created: false, oAuthApp: existing };
+  // The update docs disagree with themselves on the mask field (prose says `paths`, the
+  // curl example says `path`); send both so the call does not silently no-op.
+  const paths = ["allowedRedirectUris", "allowedRedirectDomains"];
+  const { oAuthApp } = await patch(
+    `https://www.wixapis.com/oauth-app/v1/oauth-apps/${existing.id}`,
+    { oAuthApp: { id: existing.id, allowedRedirectUris, allowedRedirectDomains },
+      mask: { paths, path: paths.join(",") } }, token);
+  return { clientId: (oAuthApp || existing).id, created: false, oAuthApp: oAuthApp || existing };
+}
+
+module.exports = { req, post, get, patch, put, del, clip, context, browse, search, page, bash, spec, mgmtRecipes, installApp, ensureOAuthApp };

package/skills/wix-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-docs
-description: "Look up the Wix API/SDK documentation to confirm an exact endpoint, HTTP method, request/response shape, field, enum, or error before writing Wix code — never guess a Wix API from memory. A lookup is a short flow: find the right page, then read it. Two ways: (1) plain `curl` (zero dependencies) — find a page by **semantic search** (`POST /mcp-docs-search/v1/docs/search`, natural-language `{ search_term, document_type }`, incl. the SKILLS recipe corpus for multi-step workflows) **or by browsing** a docs portal as a menu — a structured, typed, counted browse of the REST, SDK, CLI, Build Apps, and Headless portals (`POST /mcp-docs-search/v1/docs/menu/browse`), or the `.md` menu tree from the `llms.txt` root for any surface — then read the page by appending `.md` to its URL; (2) the Wix MCP doc tools when present. Triggers: look up a Wix API, find the Wix endpoint/method, confirm a Wix request body or field, verify a Wix API shape, explore Wix docs, which Wix API do I call, read a Wix method schema."
+description: "Look up the Wix API/SDK documentation to confirm an exact endpoint, HTTP method, request/response shape, field, enum, or error before writing Wix code — never guess a Wix API from memory. A lookup is a short flow: find the right page, then read it. Two ways: (1) plain `curl` (zero dependencies) — find a page by **semantic search** (`POST /mcp-docs-search/v1/docs/search`, natural-language `{ search_term, document_type(s) }`, incl. the SKILLS recipe corpus for multi-step workflows) **or by browsing** a docs portal as a menu — a structured, typed, counted browse of the REST, SDK, CLI, Build Apps, and Headless portals (`POST /mcp-docs-search/v1/docs/menu/browse`), or the `.md` menu tree from the `llms.txt` root for any surface — then read the page by appending `.md` to its URL; (2) the Wix MCP doc tools when present. Triggers: look up a Wix API, find the Wix endpoint/method, confirm a Wix request body or field, verify a Wix API shape, explore Wix docs, which Wix API do I call, read a Wix method schema."
 ---
 
 # Wix Docs — look up the Wix API/SDK documentation
@@ -15,11 +15,11 @@ or the Wix MCP doc tools if your agent has them (Lane 2). Either way, route by w
 know:
 
 - **You have a docs URL** → just read it (§2). Don't re-search for a page you can already name.
-- **A multi-step workflow** ("take a booking from service setup to payment") → look for a **recipe**
-  first: semantic search with `document_type: "SKILLS"` (§1A). A recipe carries step ordering,
-  cross-step gotchas, and the one bundled endpoint that does the whole job — things no single
-  method page states. No relevant recipe → search the relevant API corpus and assemble the workflow
-  from verified per-method contracts.
+- **A multi-step workflow** ("take a booking from service setup to payment") → include the **recipe**
+  corpus in the search: `document_types: ["SKILLS", …]` alongside the API corpus the steps live in
+  (§1A). A recipe carries step ordering, cross-step gotchas, and the one bundled endpoint that does
+  the whole job — things no single method page states. No relevant recipe comes back → assemble the
+  workflow from the verified per-method contracts in the same result set.
 - **One specific operation, field, or enum** → search its API corpus (`REST` / `SDK`), then read or
   schema-check what you land on.
 
@@ -34,12 +34,21 @@ Three ways to reach the right page — use whichever fits.
 
 **A. Semantic search.** Describe what you want in natural language ("let a customer book an
 appointment"), not just keywords; hits come back ranked by relevance. Same `POST` body for both
-variants: `search_term` (required, 1–500), `document_type` (`REST` default · `SDK` · `SKILLS` ·
-`WIX_HEADLESS` · `BUSINESS_SOLUTIONS` · `VELO` · `WDS` · `BUILD_APPS` · `CLI` · `OVERVIEW`),
-`maximum_results` (1–20, def 15), `lines_in_each_result` (0–200, def 20; `0` = no per-hit line cap).
-`SKILLS` is the dedicated **recipe corpus** — multi-step workflow pages that a `REST` search does
-not return; `OVERVIEW` is platform orientation (which development approach, which API family). Two
-variants — pick by what you're doing:
+variants: `search_term` (required, 1–500), **one** of `document_type` (a single corpus) or
+`document_types` (an array — several corpora in one ranked call); `maximum_results` (1–20, def 15,
+counted across the combined result set), `lines_in_each_result` (0–200, def 20; `0` = no per-hit
+line cap). Corpora: `REST` (default) · `SDK` · `SKILLS` · `WIX_HEADLESS` · `BUSINESS_SOLUTIONS` ·
+`VELO` · `WDS` · `BUILD_APPS` · `CLI` · `OVERVIEW`. `SKILLS` is the dedicated **recipe corpus** —
+multi-step workflow pages a single-API search does not return; `OVERVIEW` is platform orientation
+(which development approach, which API family).
+
+**Search the corpora a question actually spans, in one call.** The service ranks them together and
+interleaves the hits, so they compete on relevance instead of you guessing which to try first —
+and one round trip replaces several. There's no fixed combination: pick by the question. Passing
+both `document_type` and `document_types` is an error (*"Pass either document_type or
+document_types, not both"*), and an unknown corpus name is rejected with the valid list.
+
+Two variants — pick by what you're doing:
 
 **`/docs/search/markdown` → read it (start here).** Returns JSON with a single `content` field
 holding one LLM-ready markdown string (extract it with `jq -r '.content'`) where each hit is a
@@ -58,26 +67,44 @@ curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdow
   | jq -r '.content'      # no jq? → python3 -c 'import sys,json;print(json.load(sys.stdin)["content"])'
 ```
 
-For a workflow, hit the recipe corpus first, then resolve each step's call in `REST`/`SDK`:
+A question that spans a workflow and its individual calls asks for both corpora at once — the
+recipe and the per-method contracts arrive in one ranked list:
 
 ```bash
 curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown' \
   -H 'Content-Type: application/json' \
-  --data-raw '{"search_term":"end to end booking flow","document_type":"SKILLS","maximum_results":2}' \
+  --data-raw '{"search_term":"end to end booking flow","document_types":["SKILLS","REST"],"maximum_results":6}' \
   | jq -r '.content'
 ```
 
 **`/docs/search` (JSON) → route on it.** Returns `{ results: [ { title, url, content,
-relevance_score, … } ] }` — structured hits. Use it when you want to **pick/route programmatically**:
-grab a hit's `url` to read that page (§2) or feed it to the schema query (§C). (Method hits carry a
-`url`; article hits keep their link inside `content`.)
+relevance_score, kb_name, … } ] }` — structured hits. Use it when you want to **pick/route
+programmatically**: grab a hit's `url` to read that page (§2) or feed it to the schema query (§C).
+
+**`kb_name` tells you what each hit is** — every hit carries one, and the kind decides what you can
+do with it: only a method page has a schema to pull (§C); an article or recipe is read as prose (§2).
+
+The request can't make that split for you. **A corpus mixes kinds** — searching the API reference
+returns method pages *and* the prose around them — and no corpus returns method pages alone. So
+pick corpora with `document_types`, then separate the kinds on the way out with `kb_name`. Two
+things not to do instead: don't infer the kind from the presence of a `url` (every hit has one,
+articles and recipes included), and don't infer it from the corpus you asked for.
+
+Most values name their kind (`…_METHODS_…` for method pages, `…_DOCS_…` for prose, `SKILLS_KB_ID`
+for recipes) but not all do — the SDK's method index is `API_REFERENCE_SDK_KB_ID`. So list the
+labels your search actually returned, then act on those, rather than pattern-matching the name or
+hard-coding a list of ids.
 
 ```bash
+# see what came back — label, title, url
 curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search' \
   -H 'Content-Type: application/json' \
-  --data-raw '{"search_term":"create a booking","document_type":"REST","maximum_results":5}' \
-  | jq -r '.results[] | select(.url) | "\(.title)\t\(.url)"'
-# no jq? → python3 -c 'import sys,json;[print(r["title"],r["url"]) for r in json.load(sys.stdin)["results"] if r.get("url")]'
+  --data-raw '{"search_term":"end to end booking flow","document_types":["REST","SKILLS","WIX_HEADLESS"],"maximum_results":10}' \
+  | jq -r '.results[] | "\(.kb_name)\t\(.title)\t\(.url)"'
+# no jq? → python3 -c 'import sys,json;[print(r.get("kb_name"),r["title"],r.get("url")) for r in json.load(sys.stdin)["results"]]'
+
+# then take the kind you need, by the label you just saw
+… | jq -r '.results[] | select(.kb_name == "REST_METHODS_KB_ID") | "\(.title)\t\(.url)"'
 ```
 
 **B. Browse the docs tree as a menu.** Two ways: the **structured browse endpoint** for the