@wix/agent-skills 1.17.0 → 1.18.0

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

@@ -31,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);
@@ -44,6 +46,11 @@ 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 = SCRATCH;
@@ -95,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);
@@ -109,36 +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. { type } picks the portal:
-// REST (default) · WIX_HEADLESS.
-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`
@@ -146,6 +257,18 @@ 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 .agents/skills/wix-base44-connector/tmp — grep -n, sed -n, mawk, sort, uniq, wc
@@ -165,17 +288,50 @@ 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 ────────────────────────────────────────────────────────────
 
-// Inspect a located method's schema — request body, responses, enums, and the
-// filterable-fields map. In scope: lightIndex (RESOURCES with .methods — operationId,
-// summary, httpMethod, path [PARTIAL — never call it], publicUrl [callable], docsUrl)
-// and getResourceSchemaByUrl(docsUrl) → s.methods (each with requestBody, responses,
-// legacyExamples, queryMethodData.queryFieldsCapabilitiesMap; $circular via
-// s.components.schemas). Arrive with a docsUrl from search/browse — not a discovery
-// tool. 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; match your docsUrl against s.methods[].docsUrl" };
@@ -183,8 +339,11 @@ async function spec(code) {
   if (text.length <= BUDGET) return result;
   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) };
 }
 
@@ -196,10 +355,29 @@ async function spec(code) {
 // 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 mgmtRecipes(q) {
-  const { base, files } = await (await fetch("https://dev.wix.com/docs/skills/manage.manifest.json")).json();
+  // 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; }
@@ -217,4 +395,12 @@ async function mgmtRecipes(q) {
   return clip(m.map(row));
 }
 
-module.exports = { post, clip, context, browse, search, page, bash, spec, mgmtRecipes };
+// 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/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. |

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.
 

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

@@ -54,13 +54,16 @@ A concise contract for writing the **frontend code** of a storefront against a C
 The exact field paths the storefront reads, and the **plausible-wrong sibling** each is mistaken for — the sections below reference these instead of re-describing them. All `amount`s are **strings**. These are **read** shapes; the cart-add body (under *Adding to cart*) is a separate **write** shape, and the `_id` rule applies to read **entities**, not to request params (note the redirect session's `checkoutId`, which is just the cart's `_id`).
 
 ```jsonc
-// productsV3.queryProducts().…find()  →  result.items[]
-// productsV3.searchProducts({...})    →  result.products[]
+// Request CURRENCY and PLAIN_DESCRIPTION on every product read — they populate formattedAmount and plainDescription.
+const PRODUCT_FIELDS = ['CURRENCY', 'PLAIN_DESCRIPTION'];
+// productsV3.queryProducts({ fields: PRODUCT_FIELDS }).…find()  →  result.items[]
+// productsV3.searchProducts({ ..., fields: PRODUCT_FIELDS })    →  result.products[]
 product = {
   _id,                                            // links · cart catalogItemId · variant filter   (NOT .id → empty → HTTP 500)
   slug, name, visible,                            // only visible:true is returned to a visitor token
-  actualPriceRange:    { minValue: { amount } },  // PRICE   (NOT price.actualPrice.amount — that's the seed/WRITE shape → $NaN)
-  compareAtPriceRange: { minValue: { amount } },  // strike-through price
+  currency,                                       // present when CURRENCY is requested
+  actualPriceRange:    { minValue: { amount, formattedAmount } },  // PRICE   (NOT price.actualPrice.amount — that's the seed/WRITE shape → $NaN)
+  compareAtPriceRange: { minValue: { amount, formattedAmount } },  // strike-through price
   inventory: { availabilityStatus },              // product-level stock, "IN_STOCK"
   media: { main: { image } },                     // image is a wix:image:// id → resolve it (see Rendering images)
   plainDescription,                               // plain string; description.nodes is the rich-text form
@@ -90,10 +93,22 @@ Each section below is a **self-contained storefront feature** — implement only
 
 ### Listing products (and the `_id` rule)
 
-Query products with `productsV3.queryProducts()` / `.searchProducts()`.
+Query products with `productsV3.queryProducts()` / `.searchProducts()`. **Every product listing,
+category search, and detail read must request `CURRENCY` and `PLAIN_DESCRIPTION`**. Without `CURRENCY`, `formattedAmount` is omitted
+and a product card renders an unsymbolled number such as `34.99` instead of a localized price. Without `PLAIN_DESCRIPTION`, `product.plainDescription` is absent for cards and detail pages.
 Doc: <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products.md?apiView=SDK>
 
-**⚠️ `queryProducts()` takes NO arguments — it returns a builder, not a Promise.** Chain `.eq(...)`/`.limit(...)`/`.find()` on it (e.g. `await productsV3.queryProducts().limit(50).find()`). Passing a query object (`queryProducts({...})`) does **not** type-check and returns a `Promise` that has no `.limit`/`.eq`/`.find` to chain — if the SDK reference page shows a `(query, options)→Promise` signature, trust the installed no-arg builder over that example. (`searchProducts` is the one that *does* take a query — see category filtering below.)
+**⚠️ `queryProducts()` returns a builder, not a Promise.** Pass requested fields when needed, then chain `.eq(...)`/`.limit(...)`/`.find()` — for example:
+
+```js
+const PRODUCT_FIELDS = ['CURRENCY', 'PLAIN_DESCRIPTION'];
+const { items } = await productsV3
+  .queryProducts({ fields: PRODUCT_FIELDS })
+  .limit(50)
+  .find();
+```
+
+Do not pass a search/filter object to `queryProducts`; use `searchProducts` for that (see category filtering below). Reuse the same `PRODUCT_FIELDS` constant for every product read so home, shop, category, and detail pages cannot drift.
 
 **⚠️ CRITICAL: the entity id is `_id`, NOT `id`.** The SDK normalizes every entity's id to **`_id`**. `product.id` is `undefined` in SDK code. This is the cart-killer: feeding `product.id` into the cart's `catalogItemId` sends an empty string and the add returns **HTTP 500** (`"catalogItemId" has size 0`). Use `product._id` everywhere — in links, as the cart `catalogItemId`, and as the variant-query filter value. (If a field name surprises you, you are probably reading the REST doc view — re-open it with `?apiView=SDK`.)
 
@@ -101,7 +116,7 @@ Doc: <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v
 
 **Visibility:** only `visible: true` products are returned to a visitor token, so a missing product usually means it wasn't seeded visible — not a query bug.
 
-**Price** comes from `actualPriceRange.minValue.amount` (see the cheat-sheet) — **not** `price.actualPrice.amount` (the seed/write shape), which reads `undefined` → `$NaN`.
+**Price:** after requesting `CURRENCY`, render `actualPriceRange.minValue.formattedAmount` (and the matching `compareAtPriceRange` value) directly. Fall back to raw `.amount` only if the formatted value is unexpectedly absent. Never use `price.actualPrice.amount`: that is the seed/write shape and reads `undefined` → `$NaN`.
 
 ### Category navigation — list categories live
 
@@ -114,7 +129,7 @@ const res = await categories.queryCategories({
 }).exists('name', true).find();   // read the returned array per the SDK doc; ids are `_id`; link each to /category/<slug>
 ```
 
-**⚠️ The query MUST carry a filter condition — chain `.exists('name', true)` (as above), do NOT call a bare `.find()`.** A `.find()` with no chained filter serializes an empty `"filter": {}`, which `categories/v1/categories/query` rejects with `400 INVALID_FILTER` ("Filter expression cannot contain an empty condition"). **This is fatal on the visitor/manual-client (non-Astro) path** — the call throws and the nav never renders; managed-Astro's server-side transport happens to tolerate the empty filter, so a bare `.find()` *looks* fine there but breaks the moment the same code runs client-side. `.exists('name', true)` is a tautology (every category has a `name`), so it matches **all** categories and is accepted on **both** paths — use this one shape everywhere. **Do NOT filter on `visible`** (`.eq('visible', true)`): unlike `name`, `visible` is **not declared filterable** on `queryCategories`, so it triggers a silently-swallowed `400` and the nav renders blank; if you ever need to hide a category, filter the returned array **client-side**. (`getCategoryBySlug(slug, { appNamespace: '@wix/stores' })` on the category page is unaffected — it takes no query filter.) This is a **distinct API from bookings' `categoriesV2`** — don't copy that module's query shape here; read the exact result-array key + field names from the `@wix/categories` SDK doc: <https://dev.wix.com/docs/sdk/business-solutions/categories/introduction.md?apiView=SDK>.
+**⚠️ The query MUST carry a filter condition — chain `.exists('name', true)` (as above), do NOT call a bare `.find()`.** A `.find()` with no chained filter serializes an empty `"filter": {}`, which `categories/v1/categories/query` rejects with `400 INVALID_FILTER` ("Filter expression cannot contain an empty condition"). **This is fatal on the visitor/manual-client (non-Astro) path** — the call throws and the nav never renders; managed-Astro's server-side transport happens to tolerate the empty filter, so a bare `.find()` *looks* fine there but breaks the moment the same code runs client-side. `.exists('name', true)` is a tautology (every category has a `name`), so it matches **all** categories and is accepted on **both** paths — use this one shape everywhere. **Do NOT filter on `visible`** (`.eq('visible', true)`): unlike `name`, `visible` is **not declared filterable** on `queryCategories`, so it triggers a silently-swallowed `400` and the nav renders blank; if you ever need to hide a category, filter the returned array **client-side**. (`getCategoryBySlug(slug, { appNamespace: '@wix/stores' })` on the category page is unaffected — it takes no query filter.) This is a **distinct API from bookings' `categoriesV2`** — don't copy that module's query shape here; read the exact result-array key + field names from the `@wix/categories` SDK doc: <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/introduction.md?apiView=SDK>.
 
 ### Filtering products by category
 
@@ -125,6 +140,7 @@ const res = await categories.queryCategories({
 ```js
 const { products } = await productsV3.searchProducts({
   filter: { 'directCategoriesInfo.categories': { $matchItems: [{ id: categoryId }] } },
+  fields: PRODUCT_FIELDS,
 });
 ```
 
@@ -169,6 +185,8 @@ await currentCartV2.addLineItemsToCurrentCart({
 
 **⚠️ CRITICAL: `options.variantId` is MANDATORY for any product that has variants.** Adding by `catalogItemId` alone **fails** — the catalog can't resolve a variant-bearing product without it, and Cart V2 **rejects the add with an explicit error** rather than accepting an invalid line. The cart method's required-params list omits `variantId`, so it's an easy one to miss. Always resolve and include it (part 1 above).
 
+**CRITICAL: `ITEM_NOT_FOUND_IN_CATALOG` for a product that exists is a catalog defect, not a stale id.** A `DIGITAL` product whose variant has no `digitalProperties.digitalFile` is rejected under that code, and one with no stock is rejected as `exceeds available inventory` — both read back `visible: true` and in the catalog. Fix the product (`setup-online-store.md` → digital products); re-reading ids won't help.
+
 **⚠️ CRITICAL: `options.options` is for MODIFIERS, not variant selection.** Product option selections (Size/Color) are resolved to a **variant** and referenced by `variantId`. `options.options` is only for free-text / TEXT_CHOICES add-on **modifiers**. Do **not** encode Size/Color as `options.options` — that is the coffee-grind bug: the variant never resolves, so Cart V2 rejects the add with an explicit error.
 
 ### Checkout — redirect to the hosted checkout page