@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -1,7 +1,6 @@
-// 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.
+// Wix docs helpers for the Base44 sandbox. Small results return inline; anything over
+// ~4,000 chars (exec results clip at ~5,000) is saved under .agents/skills/wix-base44-connector/tmp 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";
@@ -14,14 +13,13 @@
 // 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.
+// API responses are site data and never saved — post() projects them to facts.
 
 const fs = require("fs");
 const path = require("path");
 
 const BUDGET = 4000;
-const SCRATCH = ".agents/skills/wix-base44-connector/scratch";
+const SCRATCH = ".agents/skills/wix-base44-connector/tmp";
 
 const clip = (out) => {
   if (typeof out === "string")
@@ -33,10 +31,12 @@ const clip = (out) => {
   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),
+// One transport for every JSON call — Content-Type, optional Bearer, ok-guard. One per verb, so a
+// PATCH/GET/PUT/DELETE endpoint is a helper call, never a hand-rolled fetch. Admin calls are these
+// with the connector token: patch(publicUrl, body, accessToken).
+async function req(method, url, body, token) {
+  const r = await fetch(url, { method,
+    ...(body !== undefined && { body: JSON.stringify(body) }),
     headers: { "Content-Type": "application/json", ...(token && { Authorization: `Bearer ${token}` }) } });
   if (!r.ok) {
     const head = (await r.text()).slice(0, 300);
@@ -46,9 +46,14 @@ async function post(url, body, token) {
   }
   return r.json();
 }
+const post  = (url, body, token) => req("POST", url, body, token);
+const get   = (url, token)       => req("GET", url, undefined, token);
+const patch = (url, body, token) => req("PATCH", url, body, token);
+const put   = (url, body, token) => req("PUT", url, body, token);
+const del   = (url, token)       => req("DELETE", url, undefined, token);
 
 function save(name, text) {
-  const dir = path.join(process.cwd(), SCRATCH);
+  const dir = 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 };
@@ -60,15 +65,18 @@ const outlineOf = (lines, cap = 30) => {
   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
+// A ref is a saved 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";
+// two path segments, not one: doc leaves repeat across products (every API has an
+// introduction.md), and a one-segment name makes resolveRef's cache return the WRONG document
+const slugOf = (url) => url.replace(/\?.*$/, "").replace(/\.md$/, "")
+  .split("/").filter(Boolean).slice(-2).join("-") + ".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);
+  const file = path.join(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");
+  if (!isUrl) throw new Error("no such saved 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");
@@ -94,6 +102,40 @@ async function context(token, section) {
   return clip({ total: markdown.length, section: m ? m[0] : "not found — call context(token) for the outline" });
 }
 
+// The wix-manage skill, when it is installed in the sandbox, is these same recipes on disk —
+// a read_file instead of a fetch. Indexed by frontmatter name AND filename slug, because the
+// docs title drifts from the local one ("…Connect a domain" vs "…Connect").
+const RECIPE_ROOT = ".agents/skills/wix-manage/references";
+const rkey = (s) => String(s || "").toLowerCase().replace(/[^a-z0-9]/g, "");
+let LOCAL_RECIPES;
+function localRecipes() {
+  if (LOCAL_RECIPES) return LOCAL_RECIPES;
+  LOCAL_RECIPES = new Map();
+  if (!fs.existsSync(RECIPE_ROOT)) return LOCAL_RECIPES;
+  const walk = (rel) => {
+    for (const e of fs.readdirSync(RECIPE_ROOT + rel, { withFileTypes: true })) {
+      if (e.isDirectory()) { walk(rel + "/" + e.name); continue; }
+      if (!e.name.endsWith(".md")) continue;
+      const file = RECIPE_ROOT + rel + "/" + e.name;
+      const name = (fs.readFileSync(file, "utf8").slice(0, 600).match(/^name:\s*"?(.+?)"?\s*$/m) || [])[1];
+      if (name) LOCAL_RECIPES.set(rkey(name), file);
+      LOCAL_RECIPES.set(rkey(e.name.replace(/\.md$/, "")), file);
+    }
+  };
+  walk("");
+  return LOCAL_RECIPES;
+}
+// title, else the docsUrl slug, else either one as a prefix of the other
+function recipeFile(title, docsUrl) {
+  const idx = localRecipes();
+  if (!idx.size) return undefined;
+  const slug = (docsUrl || "").replace(/\/+$/, "").split("/").pop();
+  for (const k of [rkey(title), rkey(slug)]) if (k && idx.has(k)) return idx.get(k);
+  const t = rkey(title);
+  if (t.length >= 12) for (const [k, v] of idx) if (k.startsWith(t) || t.startsWith(k)) return v;
+  return undefined;
+}
+
 // ── find what to read ─────────────────────────────────────────────────────────
 
 // Browse the docs tree — deterministic. menuUrl alone orients (children + counts);
@@ -108,35 +150,106 @@ async function browse(menuUrl, { include, filter, depth } = {}) {
   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],
+// 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. { type } picks the corpus, one per request:
+// REST (default) · SKILLS · WIX_HEADLESS · SDK · VELO · CLI · WDS · BUILD_APPS · OVERVIEW ·
+// BUSINESS_SOLUTIONS. A REST search also runs SKILLS — the management recipes rank as their own
+// hits, ahead of the methods, and land in the saved file whole. Each method hit lists the worked
+// requests the docs publish for it; every line number reads with read_file(path, offset: <line>).
+async function search(term, { type = "REST", max = 5, lines = 0, recipes = type === "REST" } = {}) {
+  const ask = (document_type, maximum_results) =>
+    post("https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown",
+      // lines_in_each_result 0 skips the server's per-section budget, which otherwise cuts every
+      // code example after the first 30 lines and the rest after 5, and every recipe at 20 —
+      // the saved file would carry stubs instead of the requests and flows the hits point at
+      { search_term: term, document_type, maximum_results, lines_in_each_result: lines });
+  const [main, skills] = await Promise.all([ask(type, max),
+    recipes ? ask("SKILLS", 3).catch(() => null) : null]);   // a recipe corpus miss must not fail the search
+  const recipeText = skills?.content ? skills.content.trimEnd() + "\n" : "";
+  const content = recipeText + main.content;
+  const nl = [];   // newline offsets — a match's char offset becomes its line in the saved file
+  for (let i = content.indexOf("\n"); i >= 0; i = content.indexOf("\n", i + 1)) nl.push(i);
+  const lineAt = (off) => { let lo = 0, hi = nl.length; while (lo < hi) { const m = (lo + hi) >> 1; nl[m] < off ? lo = m + 1 : hi = m; } return lo + 1; };
+  // recipes are articles — no "# Method:" header, no code-example delimiters, and no fixed body
+  // shape. Two things every one of them has: headings, and the endpoints it calls. Those are the
+  // outline — enough to tell whether this is the recipe for the task without reading 400 lines.
+  const recipeHits = !recipeText ? [] : recipeText.split(/\n---\n+(?=#### )/).map(b => {
+    const at = content.indexOf(b), rows = b.split("\n");
+    const steps = [], calls = [];
+    let verb = null;
+    for (const t of rows) {
+      if (/^#{1,4} /.test(t) && !/^#### \[|^## (Resource|Article|Article Link|Article Content):/.test(t))
+        steps.push(t.replace(/^#+ /, "").trim().slice(0, 52));
+      const c = t.match(/curl\s+-X\s+(GET|POST|PATCH|PUT|DELETE)/i);
+      const u = t.match(/https:\/\/www\.wixapis\.com\/[^\s"'`)\\]+/);
+      if (c && !u) { verb = c[1].toUpperCase(); continue; }   // curl -X VERB, url on the next line
+      if (!u) continue;
+      const v = (c && c[1].toUpperCase()) || (t.match(/\b(GET|POST|PATCH|PUT|DELETE)\b/) || [])[1] || verb || "";
+      verb = null;
+      const call = (v + " " + u[0].replace(/\{[^}]*\}|<[^>]*>/g, "{id}")).trim();
+      if (!calls.includes(call)) calls.push(call);
+    }
+    const title = (b.match(/^## Resource: (.+)$/m) || [])[1];
+    const docsUrl = (b.match(/#### \[[^\]]+\]\((https:[^)]+)\)/) || [])[1];
+    return { recipe: title, docsUrl,
+             ...(recipeFile(title, docsUrl) && { file: recipeFile(title, docsUrl) }),
+             line: at < 0 ? 1 : lineAt(at), lines: rows.length,
+             ...(steps.length && { steps: steps.slice(0, 6) }),
+             ...(calls.length && { calls: calls.slice(0, 4) }) };
+  }).filter(h => h.docsUrl && h.recipe);
+  let cursor = recipeText.length;
+  const hits = main.content.split(/\n---\n+(?=#### )/).map(b => {
+    const start = content.indexOf(b, cursor); cursor = start + b.length;
+    const examples = [...b.matchAll(/--- Code Example: (.+?) ---/g)]
+      .map(m => ({ title: m[1].trim(), line: lineAt(start + m.index) }));
+    const docsUrl = (b.match(/#### \[[^\]]+\]\((https:[^)]+)\)/) || [])[1];
+    const method = (b.match(/^# Method: (.+)$/m) || [])[1];
+    // the REST corpus mixes guides in with the methods — an article has no method header, so
+    // name it from its own title rather than returning a row of nulls
+    if (!method) return { article: (b.match(/^## (?:Resource|Article): (.+)$/m) || [])[1], docsUrl,
+                          line: start < 0 ? 1 : lineAt(start) };
+    return {
+    method,
+    endpoint: (b.match(/^# Method API Endpoint: (.+)$/m) || [])[1],   // "VERB url" — read the verb + url; call wx.<verb>(url, body, token)
+    docsUrl,
     gist: ((b.match(/## Method Description:\s*\n([\s\S]{0,400})/) || [])[1] || "")
       .trim().replace(/\s+/g, " ").slice(0, 220),
-  })).filter(h => h.docsUrl);
+    ...(examples.length && { examples }),
+  }; }).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),
+  if (!hits.length && !recipeHits.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 });
+  // one URL, one row: a long article is indexed in chunks that rank separately, and a stray skills
+  // page sits in the REST corpus, so the same page can rank two or three times
+  const seen = new Set();
+  const recipeRows = recipeHits.filter(r => !seen.has(r.docsUrl) && seen.add(r.docsUrl));
+  const uniq = hits.filter(h => !seen.has(h.docsUrl) && seen.add(h.docsUrl));
+  const out = { ...saved, ...(recipeRows.length && { recipes: recipeRows }), hits: uniq };
+  // over budget, shed enrichment rather than structure — clip would drop the whole shape, and
+  // every title, URL and line number stays useful with the outlines gone
+  for (const shed of [() => recipeRows.forEach(r => delete r.calls),
+                      () => recipeRows.forEach(r => delete r.steps),
+                      () => uniq.forEach(h => { if (h.examples) h.examples = h.examples.slice(0, 3); }),
+                      () => uniq.forEach(h => delete h.examples)]) {
+    if (JSON.stringify(out).length <= BUDGET) break;
+    shed();
+  }
+  return clip(out);
 }
 
 // ── 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.
+// Examples come back as their own title+line list, so the outline's cap can never drop them.
 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,
+  const ex = pageExamples(lines);
+  return { path: p, bytes, lines: lines.length, ...(ex.length && { examples: ex }), ...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`
@@ -144,9 +257,21 @@ async function page(url) {
            ] };
 }
 
+// The page's Examples section, as titles + line numbers — listed on their own so the
+// outline's cap can never drop them.
+function pageExamples(lines) {
+  const heads = [];
+  lines.forEach((t, i) => { const m = /^(#{1,6}) (.+)$/.exec(t); if (m) heads.push({ line: i + 1, level: m[1].length, text: m[2].trim() }); });
+  const at = heads.findIndex(h => /^(examples?|method code examples)$/i.test(h.text));
+  if (at < 0) return [];
+  const sec = heads[at], rest = heads.slice(at + 1);
+  const end = (rest.find(h => h.level < sec.level) || { line: lines.length + 1 }).line;
+  return rest.filter(h => h.line < end).map(h => ({ title: h.text, line: h.line }));
+}
+
 // ── shell ─────────────────────────────────────────────────────────────────────
 
-// Compose native pipelines over scratch — grep -n, sed -n, mawk, sort, uniq, wc
+// Compose native pipelines over .agents/skills/wix-base44-connector/tmp — 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) {
@@ -163,35 +288,96 @@ function bash(cmd) {
   }
 }
 
+// ── request examples ──────────────────────────────────────────────────────────
+
+// The docs' own working requests: the code-mode index carries them at
+// methods[].legacyExamples[].content, a doc page under its Examples heading. Both are saved
+// whole and come back as titles + line numbers — read the one you need with read_file.
+const examplesOf = (result) => {
+  const methods = result?.methods?.length ? result.methods : (result?.legacyExamples ? [result] : []);
+  const out = [];
+  for (const m of methods) for (const e of m.legacyExamples || []) {
+    const c = e.content || e;
+    if (c.request) out.push({ title: c.title || "", request: typeof c.request === "string" ? c.request : JSON.stringify(c.request, null, 1) });
+  }
+  return out;
+};
+
+// One file, one heading per example — the returned line is where its body starts.
+const saveExamples = (exs, name) => {
+  const parts = [];
+  let line = 1, index = [];
+  for (const e of exs) {
+    const block = "## " + e.title + "\n\n" + e.request + "\n";
+    index.push({ title: e.title, line: line + 2 });
+    parts.push(block);
+    line += block.split("\n").length;
+  }
+  return { ...save("examples-" + name + ".md", parts.join("\n")), index };
+};
+
 // ── 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} }`;
+// Inspect a method's schema — request body, responses, enums, filterable-fields map — plus the
+// titles of the docs' own request examples, saved together at examplesPath: read the one that
+// matches your task with read_file(examplesPath, offset: <its line>). Pass a docsUrl
+// (from search/browse — a direct load, no scan) and spec returns that method's schema. Or pass raw
+// `async function(){…}` to query the index yourself: lightIndex (RESOURCES with .methods —
+// operationId, summary, httpMethod, publicUrl [callable], docsUrl) and getResourceSchemaByUrl(docsUrl)
+// → s.methods (each with requestBody, responses, legacyExamples,
+// queryMethodData.queryFieldsCapabilitiesMap; $circular via s.components.schemas). A big result is
+// saved as JSON; grep it for the keys you saw in its head.
+async function spec(arg) {
+  const s = String(arg).trim();
+  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 });
   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" };
+    return { result, note: "empty — the query missed the shape; match your docsUrl against s.methods[].docsUrl" };
   const text = JSON.stringify(result, null, 1);
   if (text.length <= BUDGET) return result;
-  return { ...save("spec.json", text),
+  let h = 5381;
+  for (const ch of code) h = ((h * 33) ^ ch.charCodeAt(0)) >>> 0;   // same query → same file
+  const exs = examplesOf(result);
+  const ex = exs.length ? saveExamples(exs, h.toString(36)) : null;
+  return { ...save("spec-" + h.toString(36) + ".json", text),
            shape: Array.isArray(result) ? `Array(${result.length})` : Object.keys(result || {}).slice(0, 15),
+           ...(ex && { examplesPath: ex.path, examples: ex.index }),
            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.
+// ~100 curated multi-step MANAGEMENT (admin) flows across 23 categories — ecommerce,
+// bookings, stores, cms, contacts, sites, get-paid, marketing, pricing-plans, events,
+// blog, forms, restaurants, domains, media, … No arg → categories with counts; a
+// category name → its recipes; any other term → search every recipe's name + gist.
 // 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();
+async function mgmtRecipes(q) {
+  // the recipes ARE the wix-manage skill's references — when that skill is installed, both the
+  // listing and the files come straight off disk; the manifest fetch is only the not-installed path
+  const ROOT = ".agents/skills/wix-manage/references";
+  let files;
+  if (fs.existsSync(ROOT)) {
+    files = [];
+    const walk = rel => {
+      for (const e of fs.readdirSync(ROOT + rel, { withFileTypes: true })) {
+        if (e.isDirectory()) { walk(rel + "/" + e.name); continue; }
+        const file = ROOT + rel + "/" + e.name, head = fs.readFileSync(file, "utf8").slice(0, 1000);
+        files.push({ path: "references" + rel + "/" + e.name, file, size: fs.statSync(file).size,
+                     name: (head.match(/^name:\s*"?(.+?)"?\s*$/m) || [])[1] || e.name,
+                     description: (head.match(/^description:\s*"?(.+?)"?\s*$/m) || [])[1] || "" });
+      }
+    };
+    walk("");
+  } else {
+    const { base, files: manifest } = await (await fetch("https://dev.wix.com/docs/skills/manage.manifest.json")).json();
+    files = manifest.map(f => ({ ...f, url: base + f.path }));
+  }
   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) });
+                      ...(f.file ? { file: f.file } : { url: f.url }), 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; }
@@ -209,4 +395,12 @@ async function recipes(q) {
   return clip(m.map(row));
 }
 
-module.exports = { post, clip, context, browse, search, page, bash, spec, recipes };
+// Install a Wix app on the site (Apps Installer). Use when discovery finds an API but its app is
+// not installed yet — that is a one-call prerequisite, not a dead end. appDefId from search or the
+// Apps-Created-by-Wix table; siteId from context (the site report).
+async function installApp(appDefId, siteId, token) {
+  return post("https://www.wixapis.com/apps-installer-service/v1/app-instance/install",
+    { 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 };

package/skills/wix-headless/entry/bootstrap.mjs

@@ -40,7 +40,14 @@ function checkCli() {
   emit('cli_ok', { version });
 }
 
-// ── 2. Login (human-in-the-loop device code; forward the CLI's own events) ───
+// ── 2. Reuse an existing session, or start device login ──────────────────────
+function hasExistingSession() {
+  const r = capture(WIX[0], [...WIX.slice(1), 'whoami']);
+  if (r.status !== 0) return false;
+  emit('logged_in');
+  return true;
+}
+
 function login() {
   return new Promise((resolve) => {
     const child = spawn(WIX[0], [...WIX.slice(1), 'login'], { shell: isWin, env: AGENT_ENV });
@@ -90,4 +97,4 @@ function login() {
 
 // ── main ────────────────────────────────────────────────────────────────────
 checkCli();
-await login();
+if (!hasExistingSession()) await login();

package/skills/wix-headless/entry/skill.md

@@ -1,6 +1,6 @@
 ---
 name: wix-headless-entry
-description: "Build a complete Wix Managed Headless site from a single prompt, then connect Wix Business Solutions. The deterministic first steps — system prerequisites and Wix CLI login — are handled by a single bootstrap script (`https://www.wix.com/skills/headless/entry/bootstrap.mjs`); the agent then installs the skill and hands the run to it. Triggers: build me a site, create a website, make me a website, new website, online store, I want to sell X, start a business online, launch a site, ecommerce, portfolio, business website, sell online, online shop, connect this to Wix Headless, add Wix Headless to this project, host this on Wix, deploy this to Wix, implement the features of this project using Wix Headless. Use this skill instead of the WixSiteBuilder MCP tool for new-site requests."
+description: "Build a complete Wix Managed Headless site from a single prompt, then connect Wix Business Solutions. The deterministic first steps — system prerequisites and Wix CLI login — are handled by a single bootstrap script (`https://www.wix.com/skills/headless/entry/bootstrap.mjs`); the agent then installs the skill and hands the run to it. Triggers: build me a site, create a website, make me a website, new website, online store, I want to sell X, start a business online, launch a site, ecommerce, portfolio, business website, sell online, online shop, rental site, rentals, connect this to Wix Headless, add Wix Headless to this project, host this on Wix, deploy this to Wix, implement the features of this project using Wix Headless. Use this skill instead of the WixSiteBuilder MCP tool for new-site requests."
 ---
 
 # Wix Headless Skill — cold-start entry

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

@@ -19,7 +19,7 @@ Each built vertical has three parts (the latter two scoped to `create`/backend-o
 
 ## Built verticals — installed, seeded, and described in the Handoff
 
-The verticals the skill operates end-to-end today: **stores · blog · cms · forms · events · bookings · pricing-plans · restaurants · portfolio** (with `forms` as the floor when nothing richer is named).
+The verticals the skill operates end-to-end today: **stores · blog · cms · forms · events · bookings · rentals · pricing-plans · restaurants · portfolio** (with `forms` as the floor when nothing richer is named).
 
 ### stores — sell products
 - **Intent:** sell / shop / products / catalog / merch / store.
@@ -63,9 +63,17 @@ The verticals the skill operates end-to-end today: **stores · blog · cms · fo
 ### bookings — appointments and classes
 - **Intent:** book / appointment / schedule / class / session / reserve a slot — a **service or appointment with a provider** (a stylist, trainer, tutor, clinic, studio).
 - **Not bookings — route to `restaurants` instead:** a **table at a restaurant** is a Table Reservations concern, not a bookable service; and a **special dining occasion guests reserve** — a wine tasting, cheese pairing, chef's table, or tasting-menu evening at a restaurant — is a **restaurants → Table Reservations *experience*** (see the restaurants entry), **not** a bookings service. Reach for `bookings` only when what's booked is a standalone service/class with a provider, never a seat at a restaurant.
+- **Not bookings — route to `rentals` instead:** when the **customer chooses how long** they want something, and what's booked is a **thing rather than a person** — a room by the hour, a desk for three days, a van for the weekend. The tell is a duration *range* the customer picks within. A 60-minute haircut is `bookings`; a meeting room booked for 1–8 hours is `rentals`.
 - **Required site features:** a list of services; a page per service; a way to pick a time and book it.
 - **Implementation checklist:** show each service's name, duration, and price; show the staff or provider; show the available time slots; a book action; a confirmation after booking.
 
+### rentals — rent a room, vehicle, or piece of equipment
+- **Intent:** rent / rental / hire / lease / "by the hour" / "by the day" / hourly or daily rate / **customer picks how long** — plus the things people rent: meeting room, conference room, co-working desk, hot desk, studio, hall, venue, workspace, vehicle, van, car, boat, bike, equipment, gear, camera, tool. Reach for it whenever what's booked is a **resource** (a room, vehicle, or item) for a **length the customer selects within a range**, not a fixed session with a provider.
+- **Not rentals — route to `bookings` instead:** a session whose length the **business** fixes, delivered by a **person** (a 60-minute massage, a class, a consultation). The word "rent" in a brief sometimes describes the *business model* ("we rent out desks") while the thing being sold is really a fixed session — decide on the **duration model**, not the vocabulary.
+- **Required site features:** a list of rentable items; a page per item; a way to pick a start **and a length** (an end time or an end date) and book it. A rental is priced per hour or per day, so the site must show the **computed total for the chosen length** before the customer commits — a per-unit price alone is not enough.
+- **Implementation checklist:** show each item's name, description, and **per-hour or per-day rate** (say which); show the item's attributes where they exist (capacity, amenities, equipment type); show available start times, then the valid lengths for the chosen start; show the running total for the selected length; a book action; a confirmation after booking.
+- **One unit type per item** — an item is rented by the hour *or* by the day, never both. When a brief wants both for the same room, that's **two** rentals, each with its own rate.
+
 ### pricing-plans — memberships and subscriptions
 - **Intent:** membership / subscription / plans / paid tiers.
 - **Required site features:** a plans / pricing page; a way to choose and subscribe to a plan. **Subscribing requires a logged-in member** — the plans grid is public, but the *subscribe* action and any *my subscription* surface need the **members** cross-cutting capability (below); it's a hard dependency, not optional.

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

@@ -34,6 +34,7 @@ Hold these as the run's design tokens. Reuse them literally in the themed-block
   | forms | The form itself — clear single-column, one obvious submit |
   | events | Event list, event detail + RSVP |
   | bookings | Service list, booking widget/flow |
+  | rentals | Rentable-item grid, item detail (rate + attributes), date/length picker showing the running total |
   | pricing-plans | Plan comparison, checkout/signup |
   | restaurants | Menu, reservation/ordering flow |
   | portfolio | Project grid, case-study/project detail |

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

@@ -32,7 +32,7 @@ Discovery is pure inference — it needs **no authentication** and is **agnostic
 
 Read the **user intent** (+ optional project signals: `package.json` name, README, visible copy) against the vertical index in `references/CAPABILITIES.md` — each entry there carries the intent signals that point to it. Pick every vertical that genuinely fits → `verticals[]`. Multiple signals → multiple capabilities. On ambiguity, prefer the more specific vertical; if nothing dynamic is named, fall to the **forms** floor (a contact form). **Never return an empty set.**
 
-Resolve to the skill's operational set — **stores · blog · cms · forms · events · bookings · pricing-plans · restaurants · portfolio** (`CAPABILITIES.md` § "Built verticals"). If intent points squarely at a vertical outside that set, note it plainly as not-yet-wired (per the index) and resolve the rest; don't force an unrelated capability in its place.
+Resolve to the skill's operational set — **stores · blog · cms · forms · events · bookings · rentals · pricing-plans · restaurants · portfolio** (`CAPABILITIES.md` § "Built verticals"). If intent points squarely at a vertical outside that set, note it plainly as not-yet-wired (per the index) and resolve the rest; don't force an unrelated capability in its place.
 
 ## 2 · Infer brand
 
@@ -50,6 +50,7 @@ For each capability, build its `intent.<cap>` block — the inputs the seed step
 | forms | `{ forms: [{ purpose, fields: [...] }] }` | one `contact` form: name, email, message |
 | events | `{ eventCount, titles: [] }` | `eventCount: 2`, titles brand-derived, future dates |
 | bookings | `{ serviceCount, servicesNamed: [] }` | `serviceCount: 2`, brand-derived service names |
+| rentals | `{ unitType, serviceCount, resourceCount, servicesNamed: [] }` | `unitType: "HOUR"` (`"DAY"` if the brief rents by the day), `serviceCount: 2`, `resourceCount: 2`, brand-derived item names |
 | pricing-plans | `{ planCount, tiersNamed: [] }` | `planCount: 2` (e.g. Basic / Pro), monthly billing |
 | restaurants | `{ menuName, sections: [{ name, itemCount }], ordering?, reservations?, experiences?: [{ name }] }` | one menu, 2 sections, `itemCount: 3` each; add-ons only when the brief names them. **`experiences[]`** = special dining occasions guests reserve (wine/cheese pairing, chef's table) — a restaurant *reservation that is an experience*, **not** the `bookings` vertical (see `CAPABILITIES.md`). |
 | portfolio | `{ collections: [{ name }], projectCount }` | one brand-derived collection, `projectCount: 3` |

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

@@ -54,6 +54,7 @@ The pass-2 **write shape is per-entity earned knowledge and lives in each capabi
 | Blog post cover | `setup-blog.md` | **Attach images** |
 | CMS item | `setup-cms.md` | **Attach images** |
 | Bookings service | `setup-bookings.md` | **Attach images** |
+| Rental service | `setup-rentals.md` | **Attach images** |
 | Portfolio project / collection | `setup-portfolio.md` | **Attach images** (cover + gallery) |
 | Restaurant menu item | `setup-restaurants.md` | **Attach images** |
 | Event hero (`mainImage`) | `setup-events.md` | **Attach images** |

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

@@ -32,7 +32,9 @@ For the current `createClient` + auth-strategy shape, link:
 ### 3 · Per-capability packages + API docs (package from the map; recipe for shapes)
 For each loaded capability, give the host the **package(s)** from the map below and point it at the capability's **inline recipe** (`references/inline-recipes/how-to-code-*.md`) — the pinned API shape, methods, version, and failure modes live there; don't re-summarize them here. The map is the source of truth for *which* packages; the recipe is the source of truth for *how* to call them. **The recipes are local — Read them with the file tool, don't curl.**
 
-| Capability | Package(s) | Recipe — the pinned frontend contract |
+Before implementing a capability, Read the local recipe linked in its row.
+
+| Capability | Package(s) | Required recipe |
 |---|---|---|
 | stores | `@wix/stores` (+ `@wix/ecom`, `@wix/redirects` for cart/checkout) | `how-to-code-a-store.md` — Catalog V3 read + cart/checkout. |
 | blog | `@wix/blog` (+ `@wix/ricos` to render `richContent`; **`@wix/comments` + `@wix/members`** when the blog has comments/members; `@wix/blog` `likes` when the site has members) | `how-to-code-a-blog.md` — Blog V3 read/render + member features (likes, comments). Supplement: <https://dev.wix.com/docs/sdk/business-solutions/blog.md>. |
@@ -40,6 +42,7 @@ For each loaded capability, give the host the **package(s)** from the map below
 | forms | `@wix/forms` | `how-to-code-forms.md` — schema-driven render (read the live form schema, visitor token/no elevate) + Form Submissions v4 write contract. |
 | events | `@wix/events` (+ `@wix/redirects` for the ticketed hosted-checkout redirect) | `how-to-code-events.md` — Events V3 read + the `TICKETING`-vs-`RSVP` branch. |
 | bookings | `@wix/bookings` (+ `@wix/auto_sdk_ecom_cart-v-2`, `@wix/redirects` for the cart/checkout that holds the seat; `@wix/forms` for the schema-driven booking form) | `how-to-code-bookings.md` — Services V2 read + `createBooking → ecom Cart V2 → checkout-or-place`. |
+| rentals | **`@wix/bookings`** — the same package set as bookings (`@wix/auto_sdk_ecom_cart-v-2`, `@wix/redirects`, `@wix/forms`). **There is NO `@wix/rentals` package** and its absence is not a missing capability: Wix Rentals ships no APIs of its own and runs on the Bookings APIs with rentals-specific field values. Never report rentals as "not buildable headlessly". | `how-to-code-rentals.md` — a **delta** on `how-to-code-bookings.md`: filter the catalog by the rentals `appId` (`ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e`), two-call hourly availability (start slots → end options), the consecutive-day walk for daily, duration-based `previewPrice`, then the **unchanged** booking/cart/checkout sequence carrying the rentals `appId` on `catalogReference`. |
 | pricing-plans | `@wix/pricing-plans` (+ `@wix/members` — login is a hard dep; and for the Bookings-membership integration `@wix/bookings` + `@wix/ecom` (+ `@wix/redirects`)). **Use `@wix/pricing-plans`, NOT the Wix-site `@wix/site-pricing-plans` (`startOnlinePurchase` is site page-code, not headless).** | `how-to-code-pricing-plans.md` — Plans V3 grid + login-gated order/subscribe + book-with-membership. |
 | restaurants | `@wix/restaurants` (menu display — **no `@wix/ecom`** unless online ordering is in the run; reservations are a separate app) | `how-to-code-restaurants.md` — Menus V1 display-only read. |
 | restaurants — online ordering (add-on; only when the Orders app is in the run) | add `@wix/ecom` + `@wix/redirects` to the row above | `how-to-code-restaurant-orders.md` — ordering cart/checkout on top of the menu display. |
@@ -68,7 +71,7 @@ Everything else the host resolves live from the queries in §3. (Static platform
 - Frontend CMS access is **read**; visitor writes go through **Forms** submissions.
 - **Blog comments are member-gated — read public, write authenticated.** Querying/rendering comments is public, so list them server-side in SSR. **Submitting** needs a logged-in member, so don't gate the form behind an upfront login check (that branch is what burns deliberation): render the form always and resolve identity at submit — POST to a backend endpoint (`src/pages/api/*.ts`) that calls `createComment` with the request session; if the caller isn't a member, redirect to the built-in `/api/auth/login?returnUrl=…`. **Do not build the comment form as a client island** — the API-endpoint + session path is the documented shape and avoids the browser-auth detour. The comment API keys (post `referenceId`, Blog appDefId, author lookup via `post.memberId`) are in `how-to-code-a-blog.md`.
 - **Member auth is one mechanism split on the frontend axis (the §3 members note routes to the right recipe), and orthogonal to elevation.** Sign-up and log-in are the *same* flow (the Wix login page logs in **or** registers); log-out is its inverse. Two layers stay separate: **identity** (logged-in vs not — no app install) vs **profile** (name/photo/roles — needs the **Wix Members Area app** installed, `SETUP.md`). **pricing-plans is a hard dependency**: subscribing requires a logged-in member; for the other verticals, member login is a soft add-on for their "my …" surfaces only. **A member reading their own data (own orders/bookings/subscriptions, plan-gated content) uses the member token with NO `auth.elevate`** — elevation is the separate admin/permission axis (site-wide reads, server-side only), not something member features need.
-- **Gating is a LIVE signal, never a hardcoded id list.** Whenever content is gated (members-only articles, plan-eligible class booking, any "premium" surface), decide eligibility from a signal read **at request time** — a queryable flag carried on the content (a `members-only` blog category/tag or a boolean CMS field) and live coverage/eligibility (`checkout.membershipOptions.eligibleMemberships`, or the member's active-order `planId`s matched against **live** Benefit-Program coverage). **Never** gate on a frozen set of "premium" slugs/ids or a seed-time `plan→service` map: a gated post or a newly-covered service the owner adds later would silently read as public/ineligible. See `how-to-code-a-blog.md` (member features) and `how-to-code-pricing-plans.md` (coverage read).
+- **Gating is a LIVE signal, never a hardcoded id list.** Whenever content is gated (members-only articles, plan-eligible class booking, any "premium" surface), decide eligibility from a signal read **at request time** — a queryable flag carried on the content (a `members-only` blog category/tag or a boolean CMS field) and live coverage/eligibility (Cart V2's `currentCartV2.calculateCurrentCart()` → `summary.paymentSummary.memberships`, or the member's active-order `planId`s matched against **live** Benefit-Program coverage). **Never** gate on a frozen set of "premium" slugs/ids or a seed-time `plan→service` map: a gated post or a newly-covered service the owner adds later would silently read as public/ineligible. See `how-to-code-a-blog.md` (member features) and `how-to-code-pricing-plans.md` (coverage read).
 
 ### 6 · What a complete site must include (per loaded capability)
 For each loaded capability, carry its **Required site features** and **Implementation checklist** from `references/CAPABILITIES.md` into the guide — in plain product language, lightly tailored to what was seeded. **This is the build spec, not optional polish:** the host should build every *required feature* and cover every *checklist* item. For example, a blog must show the **author** (name + photo), the publish date and reading time, the cover image, and the **full formatted content** (not flattened text) — a posts-list-plus-plain-text-body is incomplete. The host maps these onto its own components using the packages/docs in §3 and the seeded schema in §4.

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

@@ -37,6 +37,7 @@ Each entry states only the entities, where their count/content comes from, the p
 - **forms** — *Visitor-fillable forms.* Recipe: **`setup-forms.md`**. One form per `intent.forms.forms` entry; fields from the entry, `purpose` names the form. **Keep (→ handoff):** `formIds[]` + each form's field **`target`** keys — *structural* (the frontend binds each input's `name` = target to submit; targets are **immutable**, so they don't go stale when an owner relabels a field).
 - **events** — *A ticketed or RSVP occasion, or upcoming events.* Recipe: **`setup-events.md`**. Each event is **either `TICKETING`** (paid — it has ticket tiers) **or `RSVP`** (free — the registration form is built-in, so don't seed form fields) per intent. For an **RSVP occasion** (a wedding, party, gathering): one RSVP event with the occasion's real details (title, a **future** date/time, location). For a **ticketed** event: the event plus its ticket tiers (default a single `"General Admission"` tier if none named). For a **listing** site: `intent.events.eventCount` events with brand-appropriate titles and **future** start dates (a default location/timezone is fine). Text-only. **Keep:** nothing for the handoff — events and tiers are discovered **live** (`queryEvents`, `getEventBySlug`, `queryAvailableTickets`); track `eventIds`/`ticketDefinitionIds` only transiently.
 - **bookings** — *Bookable services.* Recipe: **`setup-bookings.md`**. `intent.bookings.serviceCount` services (name + short description fitting `brand`, a simple duration and price); keep the schedule minimal. **Keep:** `serviceIds[]` as **seed-time state** (pricing-plans' coverage step keys on them, below); nothing for the handoff — services are discovered **live** (`queryServices`).
+- **rentals** — *Rentable resources.* Recipe: **`setup-rentals.md`**. A resource **type** per kind of thing rented (rooms, vans, cameras), then `intent.rentals.resourceCount` **resources** inside it (Room A / Room B — parallel capacity comes from more resources, not higher capacity), then `intent.rentals.serviceCount` **rental services**, each carrying the Wix Rentals `appId`, `serviceResources` naming its resource type, a `primaryResourceType`, and a `durationRange` (`HOUR` or `DAY`) with the min/max the request implies — defaulting to **60/480 minutes** hourly and **1/5 days** daily when the brief doesn't say — and a **per-unit** price. **No category** — unlike bookings, rental services don't use one; don't create or assign one. **Order is load-bearing: resource type → resources → services** — a service whose resource type holds no resources has permanently empty availability. Seed resources **24/7** (no working-hours schedule) unless the request names opening hours; that keeps a multi-day rental to a single booking. **Keep:** `resourceTypeIds[]` as seed-time state (services key on them); nothing for the handoff — rentals are discovered **live** (`queryServicesByFilters` filtered by the rentals `appId`).
 - **pricing-plans** — *Membership tiers.* Recipe: **`setup-pricing-plans.md`**. `intent.pricing-plans.planCount` recurring plans (name, price, a monthly billing cycle) fitting `brand`. **When bookings is also in this run and the intent is a membership that covers services** (a studio/gym/class pass), also **attach the covered bookings services to the plan** — seed the bookings services first, since coverage keys on their service ids (see the recipe). **Keep:** the bookings coverage only transiently, to wire it during seeding; nothing for the handoff — plans are discovered **live** (`queryPlans`) and plan→service coverage is read **live** at checkout, never from a frozen map (see `how-to-code-pricing-plans.md`).
 - **restaurants** — *A menu.* Recipe: **`setup-restaurants.md`** (add-ons have their own recipes, below). Create the `itemCount` items per section first (name, description, price fitting `brand`), then the `intent.restaurants.sections` referencing those item ids, then the menu referencing the section ids — **items → sections → menu** (build bottom-up: a section is created with its `itemIds`, a menu with its `sectionIds`, so each child must exist before its parent — see `setup-restaurants.md` STEP 1–3). Text-only. **Keep (seed-time only):** `menuId`, `sectionIds[]`, `itemIds[]` to build the tree; nothing goes to the handoff — the frontend reads menus **live** (`listMenus`/`listSections`/`listItems`). **Online ordering (add-on, on demand)** — only when the request calls for ordering (not just a displayed menu): install the Orders app (per `SETUP.md` §2) and follow **`setup-restaurant-orders.md`**; **seed the menu FIRST, then ordering, in the same unit** (ordering auto-provisions per menu either way — see the concurrency note above — but keeping them one unit gives the ordering verify a menu to confirm against). **Configure the business-location address (`setup-restaurant-orders.md` STEP 0) — required for ordering to work end-to-end; without it Wix limits ordering to "testing only" and checkout breaks.** If the brief gives no address, set a placeholder and flag the owner in the handoff. Completing a *paid* order additionally needs premium + a payment method (dashboard/premium — surface, don't fail). **Keep:** nothing for the handoff — read **live** (`listOperations`/`listFulfillmentMethods`); track `operationId`/`fulfillmentMethodIds[]` transiently. **Table reservations (add-on, on demand, INDEPENDENT of ordering/menu)** — only when the request calls for reservations: install the Table Reservations app (per `SETUP.md` §2) and follow **`setup-restaurant-reservations.md`**; **no menu dependency** (reservations bind to a location, not a menu — do NOT apply the menu-first rule) and **nothing to bulk-seed** (visitors create reservations at runtime); **configure the business-location address (`setup-restaurant-reservations.md` STEP 0)** — the reservation location is the site's business location, so set a real address (placeholder + owner flag if the brief names none; shared with ordering if both are present); enabling online reservations is **premium-gated** (record the precondition, don't fail). **Keep:** nothing for the handoff — read **live** (`listReservationLocations`); track `reservationLocationId` transiently. **Experiences (add-on within Table Reservations, on demand)** — only when the request names **special dining occasions guests reserve** (wine/cheese pairing, chef's table, tasting-menu evening — an *experience*, not a `bookings` service; see `CAPABILITIES.md`): they need the **Table Reservations app** (no extra install) and a configured **business-location address** (`setup-restaurant-reservations.md` STEP 0, same as reservations) and, unlike plain reservations, they **are** seeded — create one Experience per named occasion on the default reservation location, following **`setup-restaurant-experiences.md`**. Booking an experience is **premium-gated** like online reservations (record the precondition, don't fail). **Keep:** nothing for the handoff — experiences are read **live** (`queryExperiences`); track `experienceId`(s) transiently.
 - **portfolio** — *A project showcase.* Recipe: **`setup-portfolio.md`**. Create the `intent.portfolio.collections` (title + short description fitting `brand`), then `intent.portfolio.projectCount` projects assigned to them — **collections before projects** (a project's `collectionIds` must hold real collection ids; see the recipe). Text-only by default (omit `coverImage`; images only when `imagery` is on — §1, §4). **Keep (seed-time only):** `collectionIds{<name>}` to assign projects into their collections; nothing goes to the handoff — the frontend lists collections and projects **live** (`collections.queryCollections` / `projects.queryProjects`), so owner-added content appears with no code change.
@@ -59,7 +60,7 @@ Don't silently skip a required feature — a bare list-and-detail with none of i
 
 ## 4 · Entity images (opt-in)
 
-**Only if `imagery` is on** (from `DISCOVERY.md`). For each seeded image-bearing capability — stores products, blog covers, CMS items, **bookings services**, restaurant items, **portfolio projects + collection covers**, event heroes — generate a brand-contextual image per entity and **attach it as a required pass-2 step** (the seeder created the entity text-first in §2; this writes the image onto it), following `references/IMAGE_GENERATION.md` (generate → import to Wix Media → attach). **The per-entity attach shape lives in that capability's own seed recipe** (`setup-<capability>.md`), next to its create shape — read it there; `IMAGE_GENERATION.md` §3 is a navigation table (entity → recipe → step) that carries no shapes. Use the IDs already in the `seeded` map. Image failures never block — skip and continue (the entity stays text-only). When `imagery` is off, skip this step entirely.
+**Only if `imagery` is on** (from `DISCOVERY.md`). For each seeded image-bearing capability — stores products, blog covers, CMS items, **bookings services**, **rental services**, restaurant items, **portfolio projects + collection covers**, event heroes — generate a brand-contextual image per entity and **attach it as a required pass-2 step** (the seeder created the entity text-first in §2; this writes the image onto it), following `references/IMAGE_GENERATION.md` (generate → import to Wix Media → attach). **The per-entity attach shape lives in that capability's own seed recipe** (`setup-<capability>.md`), next to its create shape — read it there; `IMAGE_GENERATION.md` §3 is a navigation table (entity → recipe → step) that carries no shapes. Use the IDs already in the `seeded` map. Image failures never block — skip and continue (the entity stays text-only). When `imagery` is off, skip this step entirely.
 
 ## Aggregate
 

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

@@ -23,6 +23,7 @@ For each capability in `verticals[]`, install its app by `appDefId` (these are t
 - **forms** → `225dd912-7dea-4738-8688-4b8c6955ffc2`
 - **events** → `140603ad-af8d-84a5-2c80-a0f60cb47351`
 - **bookings** → `13d21c63-b5ec-5912-8397-c3a5ddb27a97`
+- **rentals** → `ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e` (Wix Rentals). Rentals provisions the Bookings infrastructure it runs on, so a Rentals-only install is enough — its availability comes back without adding Wix Bookings separately. Rentals has **no APIs of its own**: it is Services V2 with rentals-specific field values (`setup-rentals.md`), and its frontend package is `@wix/bookings` — there is no `@wix/rentals`. Rentals uses no categories; to also offer plain fixed-duration services, install Wix Bookings (`13d21c63-b5ec-5912-8397-c3a5ddb27a97`) as well, seed those with `setup-bookings.md`, and filter every catalog read by `appId` so the two sets stay separate.
 - **pricing-plans** → `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3`
 - **restaurants** → `b278a256-2757-4f19-9313-c05c783bec92` (Wix Restaurants **Menus** — the seedable core). Online ordering and table reservations are **separate optional apps**, install only if intent calls for them: Orders (New) → `9a5d83fd-8570-482e-81ab-cfa88942ee60`, Table Reservations → `f9c07de2-5341-40c6-b096-8eb39de391fb`. **Experiences** (special dining occasions guests reserve — wine tastings, chef's tables; see `CAPABILITIES.md`) are a **feature of the Table Reservations app, not a separate install** — installing Table Reservations is all that's needed to create and book them (`setup-restaurant-experiences.md`).
 - **portfolio** → `d90652a2-f5a1-4c7c-84c4-d4cdcc41f130` (Wix Portfolio; the install ships a default sample collection + projects — `setup-portfolio.md` STEP 0 cleans them)

package/skills/wix-headless/references/inline-recipes/how-to-code-a-blog.md

@@ -63,7 +63,7 @@ const { items } = await posts
   .limit(20)
   .find();
 ```
-Doc: <https://dev.wix.com/docs/api-reference/business-solutions/blog/posts/query-posts.md?apiView=SDK>
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/query-posts.md?apiView=SDK>
 
 **⚠️ CRITICAL: request the `RICH_CONTENT` fieldset, or `post.richContent` is `undefined`.** `queryPosts` omits the body by default; without `fieldsets: ["RICH_CONTENT"]` the post comes back with no `richContent`, and the detail page renders blank. (Add `"URL"` to get `post.url`/`slug` for links.)
 
@@ -114,7 +114,7 @@ export default function RicosContentViewer({ content }) {
   return <div className="ricos-content"><RicosViewer content={content} plugins={plugins} /></div>;
 }
 ```
-Doc: <https://dev.wix.com/docs/sdk/business-solutions/blog/introduction.md?apiView=SDK> (follow it to the current Ricos viewer API; verify with `SearchWixSDKDocumentation "ricos viewer"`).
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/blog/introduction.md?apiView=SDK> (follow it to the current Ricos viewer API; verify with `SearchWixSDKDocumentation "ricos viewer"`).
 
 **⚠️ CRITICAL (Astro): render the viewer with `client:only="react"`.** `@wix/ricos` is a React component that breaks under SSR. `<RicosViewer client:only="react" content={post.richContent} />` makes it render client-side only. `@wix/ricos` accepts the camelCase `richContent` from the `@wix/blog` SDK directly — no key renaming.