@wix/agent-skills 1.19.0 → 1.19.2

package/skills/wix-docs/SKILL.md

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

package/skills/wix-headless/SKILL.md

@@ -124,6 +124,7 @@ Compute `<SKILL_ROOT>` from this file (`<SKILL_ROOT>/SKILL.md` — strip `/SKILL
 | Image generation (opt-in; agnostic) | `<SKILL_ROOT>/references/IMAGE_GENERATION.md` |
 | Design — fallback visual quality bar for the built frontend, when the user gave no design direction of their own (managed **create** only) | `<SKILL_ROOT>/references/DESIGN.md` |
 | Content — fallback copy quality bar for the built frontend, when the user gave no copy/voice direction of their own (managed **create** only) | `<SKILL_ROOT>/references/CONTENT.md` |
+| Experience overlays — a vertical's own design + copy bar on top of DESIGN/CONTENT (optional per vertical; read when that vertical is loaded) | `<SKILL_ROOT>/references/inline-recipes/experience-<vertical>.md` (today: `experience-store.md`) |
 | AI features — text/chat + embeddings (opt-in; agnostic) | `<SKILL_ROOT>/references/AI_FEATURES.md` |
 | Feedback — relay the user's headless-experience feedback to Wix (opt-in; user-approved) | `<SKILL_ROOT>/references/FEEDBACK.md` |
 | **Authentication** — obtain `$TOKEN`/`$SITE_ID`/`clientId` (project-type-specific) | `<TYPE_DIR>/AUTHENTICATION.md` |

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

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
-import readline from 'node:readline';
+import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 
 // ── tiny event protocol (one JSON object per line) ───────────────────────────
 const emit = (event, extra = {}) =>
@@ -24,6 +26,12 @@ const WIX = [bin('npx'), '-y', '@wix/cli@latest']; // run the CLI via npx — no
 // Respect an existing value so a known runner (claude, cursor, …) keeps its name.
 const AGENT_ENV = { ...process.env, AI_AGENT: process.env.AI_AGENT || 'wix-headless-skill' };
 
+// Where the detached login parks its output between runs. It has to outlive this
+// process, so it can't be a pipe and can't live in the project.
+const STATE_DIR = join(tmpdir(), 'wix-headless-login');
+const LOG = join(STATE_DIR, 'login.log');
+const PIDFILE = join(STATE_DIR, 'login.pid');
+
 // run a command, capture stdout+stderr (combined), return {status, out}
 function capture(cmd, args, opts = {}) {
   const r = spawnSync(cmd, args, { encoding: 'utf8', shell: isWin, env: AGENT_ENV, ...opts });
@@ -41,60 +49,108 @@ function checkCli() {
 }
 
 // ── 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;
-}
+const hasExistingSession = () => capture(WIX[0], [...WIX.slice(1), 'whoami']).status === 0;
 
-function login() {
-  return new Promise((resolve) => {
-    const child = spawn(WIX[0], [...WIX.slice(1), 'login'], { shell: isWin, env: AGENT_ENV });
-    const rl = readline.createInterface({ input: child.stdout });
-    let loggedIn = false;
-    // Buffer the CLI's own diagnostics (stderr + any non-event stdout chatter) so a
-    // failure reports the REAL cause — network/proxy error, expired code, etc. — not
-    // a guess. Keep only the tail so a chatty CLI can't blow up memory, and draining
-    // stderr also avoids the pipe filling up and stalling the child.
-    let diag = '';
-    const collect = (chunk) => {
-      diag = (diag + chunk).slice(-2000);
-    };
-    child.stderr?.on('data', collect);
-    rl.on('line', (line) => {
-      const t = line.trim();
-      if (!t) return;
-      // In agent mode the CLI emits {event:"awaiting_user"|"success"|"logged_in", ...}
-      // — pass those straight through so the agent can relay the device code.
+function loginEvents() {
+  if (!existsSync(LOG)) return [];
+  return readFileSync(LOG, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => {
       try {
-        const ev = JSON.parse(t);
-        if (ev && ev.event) {
-          process.stdout.write(t + '\n');
-          if (ev.event === 'success' || ev.event === 'logged_in') {
-            loggedIn = true;
-            resolve();
-          }
-          return;
-        }
-        collect(line + '\n'); // JSON, but not an event — keep for diagnostics
+        return JSON.parse(l);
       } catch {
-        collect(line + '\n');
-      } // non-JSON CLI chatter — keep for diagnostics
-    });
-    // Only a success/logged_in event counts as login. On any other exit, surface the
-    // CLI's actual output — do NOT assume a cause (agent mode, etc.).
-    child.on('close', (code) => {
-      if (loggedIn) return;
-      const detail =
-        diag.trim().slice(-1500) ||
-        `wix login exited (code ${code}) before authenticating, with no output.`;
-      fail('login_failed', { code, detail });
-    });
-    child.on('error', (e) => fail('login_failed', { detail: String(e) }));
+        return null; // non-JSON CLI chatter
+      }
+    })
+    .filter((e) => e && e.event);
+}
+
+const alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// A login this machine started earlier may still be waiting on the browser. Reuse
+// its code instead of minting a second one — a new login invalidates nothing, but
+// it hands the user a different code than the one already on their screen.
+function pendingLogin() {
+  if (!existsSync(PIDFILE)) return null;
+  let state;
+  try {
+    state = JSON.parse(readFileSync(PIDFILE, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!state.pid || !alive(state.pid)) return null;
+  const ev = loginEvents().find((e) => e.event === 'awaiting_user');
+  if (!ev) return null;
+  // Don't hand back a code that's about to expire mid-typing.
+  const ageSeconds = Math.round((Date.now() - state.startedAt) / 1000);
+  if (ageSeconds > (ev.expiresInSeconds ?? 600) - 60) return null;
+  return ev;
+}
+
+// Detach so the login keeps polling after this process exits. stdio goes to a
+// file, not a pipe: a pipe dies with the parent, and the CLI would get EPIPE.
+function startLogin() {
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(LOG, '');
+  const out = openSync(LOG, 'a');
+  const child = spawn(WIX[0], [...WIX.slice(1), 'login'], {
+    detached: true,
+    stdio: ['ignore', out, out],
+    env: AGENT_ENV,
+    shell: isWin,
+  });
+  child.on('error', (e) => fail('login_failed', { detail: String(e) }));
+  writeFileSync(PIDFILE, JSON.stringify({ pid: child.pid, startedAt: Date.now() }));
+  child.unref();
+}
+
+async function waitForCode(timeoutMs = 60000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const events = loginEvents();
+    const ev = events.find((e) => e.event === 'awaiting_user');
+    if (ev) return ev;
+    const bad = events.find((e) => e.event === 'login_failed');
+    if (bad) fail('login_failed', bad);
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  const detail = existsSync(LOG) ? readFileSync(LOG, 'utf8').trim().slice(-1500) : '';
+  fail('login_failed', {
+    detail: detail || `wix login produced no device code within ${timeoutMs / 1000}s.`,
+  });
+}
+
+// The next move is the user's, so hand the code back and exit rather than holding
+// the caller open for a browser round-trip. `message` is the sentence to relay.
+function surrenderTo(ev) {
+  emit('awaiting_user', {
+    ...ev,
+    message:
+      `To connect your Wix account, open ${ev.verificationUri} and enter the code ` +
+      `${ev.userCode}. Tell me once you're done and I'll continue.`,
   });
+  process.exit(0);
 }
 
 // ── main ────────────────────────────────────────────────────────────────────
 checkCli();
-if (!hasExistingSession()) await login();
+
+if (hasExistingSession()) {
+  emit('logged_in');
+  process.exit(0);
+}
+
+const pending = pendingLogin();
+if (pending) surrenderTo(pending);
+
+startLogin();
+surrenderTo(await waitForCode());

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

@@ -36,9 +36,9 @@ If that errors (Node not installed) or prints a version below 20.11, install or
 
 ## Phase 1 — Run the bootstrap (deterministic)
 
-Download the bootstrap script, then run it. It verifies the Wix CLI and handles login, emitting **one JSON event per line** on stdout. **Run it as a background/streaming process and relay its events to the user.**
+Download the bootstrap script, then run it — an ordinary foreground command that exits on its own within seconds. It verifies the Wix CLI and handles login, emitting **one JSON event per line** on stdout. **Run it and relay its events to the user.**
 
-The script is safe and inspectable: it only checks the Wix CLI via `npx` and drives `wix login` (a device-code flow) — no other network calls, no filesystem writes. Read it first if your sandbox flags externally-downloaded code — either at the URL below or after downloading; both are the same file.
+The script is safe and inspectable: it only checks the Wix CLI via `npx` and drives `wix login` (a device-code flow) — no other network calls, and the only files it writes are the login's own output and pid under the OS temp dir. Read it first if your sandbox flags externally-downloaded code — either at the URL below or after downloading; both are the same file.
 
 ```bash
 # macOS/Linux:
@@ -56,10 +56,12 @@ The script emits one JSON object per line:
 | Event | What to do |
 |---|---|
 | `cli_ok` | Wix CLI reachable — continue. |
-| `awaiting_user` (`verificationUri`, `userCode`) | Show the URL and code in plain prose; wait for the user to finish the login in their browser. |
+| `awaiting_user` (`verificationUri`, `userCode`, `message`) | The script has exited and the next step is the user's. Send them `message` as-is; the login keeps running on its own. |
 | `logged_in` / `success` | Login done — continue. |
 | `cli_unreachable` / `login_failed` (with `detail`) | Stop and show the user the `detail`. **Do not** improvise a parallel setup by hand. |
 
+On `awaiting_user`, run the script again once the user says they've logged in: it reports `logged_in` and you continue. Re-running while they're still in the browser is harmless — it returns the same code rather than issuing a new one.
+
 ## Phase 2 — Install the skill and hand off
 
 Install the Wix Headless skills (`CI=1` forces plain non-interactive CLI output — keep it on every Wix CLI command):

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

@@ -23,8 +23,13 @@ The verticals the skill operates end-to-end today: **stores · blog · cms · fo
 
 ### stores — sell products
 - **Intent:** sell / shop / products / catalog / merch / store.
-- **Required site features:** a product list or grid; a page per product; categories to browse by; a cart; a checkout.
-- **Implementation checklist:** show each product's image, name, and price; show options and variants (size, colour…) where they exist; show availability / out-of-stock; a quantity picker and an add-to-cart that updates a visible cart; the product description; link each product to its category.
+- **Required site features:** a homepage that sells (what the store offers, real products, one clear shopping action); a shop / category gallery with sort, the filters the catalog supports, and paging; a page per product; categories to browse by; a cart the shopper can review and edit, opening as a side drawer after every add; checkout reachable directly from that cart.
+- **Implementation checklist:**
+  - *Homepage:* say what the store sells in the first screen; real products from the catalog under truthful headings — never a repeat of the shop page, never a heading like "Best Sellers" without data behind it.
+  - *Gallery:* a real product — image, name, price, link — visible in the first screen before any scrolling; a result count; loading, empty-catalog, no-results-for-these-filters, and error states that look different from each other.
+  - *Product page:* in the first screen, the product image, name, price, the first choice to make, and the buy button — disabled with a plain reason until every choice is made; every ribbon the merchant set; the current price and, when there is one, the labelled original price; a gallery of every product image; options with unavailable choices marked; quantity; the full description and information sections; pre-order, subscriptions, and notify-me only when the catalog has them.
+  - *Cart:* each line's image, name, chosen options, quantity (editable) and price; subtotal and discounts as Wix calculates them; "shipping and taxes calculated at checkout" rather than invented numbers; survives a reload; checkout from the drawer.
+  - *Everywhere:* availability / out-of-stock shown truthfully; each product linked to its category; no reviews, ratings, scarcity, or delivery promises the merchant didn't supply; no Wix IDs or technical words in shopper-facing text.
 
 ### blog — publish posts
 - **Intent:** blog / posts / articles / publication / news.

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

@@ -36,7 +36,7 @@ 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. |
+| stores | `@wix/stores` + `@wix/categories` (+ `@wix/ecom`, `@wix/redirects` for cart/checkout) | `how-to-code-a-store.md` — Catalog V3 gallery (sort/filter/paging), product page (variants, prices, ribbons), Cart V2 + checkout, and what a complete storefront shows. |
 | 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>. |
 | cms | `@wix/data` | `how-to-code-cms.md` — `items.query` read contract. |
 | 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. |
@@ -77,6 +77,7 @@ Everything else the host resolves live from the queries in §3. (Static platform
 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.
 
 - State them as the *what* (product behaviour), not the *how* (no component code, no API calls) — the host owns the build.
+- **When a loaded vertical ships an experience overlay** (`references/inline-recipes/experience-<vertical>.md`; today `experience-store.md`), point the host at it alongside the checklist — it is that vertical's design and copy bar (surfaces, first-viewport rules, truthful copy), read after the general `DESIGN.md`/`CONTENT.md`.
 - If a *required feature* depends on backend support that **Seed** enabled (e.g., comments), note it's available so the host wires it. If Seed could **not** enable it, say so plainly rather than implying the site is complete.
 - **When pricing-plans is loaded, `login / account / gated content` is a *required* feature, not optional polish** — a plans grid with no way to log in and subscribe is incomplete (subscribing requires a member; §5 member-auth note). Point the host at the matching `how-to-code-members-*.md` recipe. For the other verticals, a "my …" surface (my orders / my bookings / my registrations) is a member-gated *enhancement* — list it only if the run's intent calls for an account view, and flag it needs the same login mechanism.
 - **Curation / hero / nav must come from a LIVE query, never a pinned slug/id.** A "featured" or "latest" item, a hero, and every nav/category bar must be driven by a query — "next upcoming" (`queryEvents` filtered to `UPCOMING`/`STARTED`, sorted by start date), "newest" (`queryPosts`), `queryCategories`, etc. — resolved at request time. A pinned "featured event" slug not only fails to rotate as the owner adds content, it can go **stale/past**. Even a **single-item** site (one event, one product) must drive its homepage from the *listing query*, not a hardcoded lone slug — so a second item the owner adds later surfaces automatically instead of staying invisible.

package/skills/wix-headless/references/inline-recipes/experience-store.md

@@ -0,0 +1,48 @@
+---
+name: "Storefront Experience"
+description: The storefront's own design and copy bar, on top of DESIGN.md and CONTENT.md — how to derive a store's direction from its catalog, what the homepage, gallery, product page, and cart must show, the overlay contract, truthful commerce copy, and image discipline. Read when building or wiring a store frontend; the API contract lives in how-to-code-a-store.md.
+---
+**EXPERIENCE OVERLAY**: What makes a storefront good — read after `DESIGN.md` and `CONTENT.md`
+
+`DESIGN.md` and `CONTENT.md` are the floor for every site. This file adds what is specific to a store. It is the *what* of a good storefront — the API *how* is `how-to-code-a-store.md`. The wiring is necessary, not sufficient: a store whose calls all work but whose homepage repeats the shop page, whose first screen shows no product, or whose cart hides checkout behind a page is not done.
+
+**These are defaults for when the brief doesn't say otherwise.** Whatever the user asked for in their prompt — a layout, a page they don't want, a cart page instead of a drawer, a specific look — wins over any line here.
+
+## 1 · Design from the catalog, not from the category
+
+Before choosing tokens, **look at the catalog**: the categories and their depth, the assortment size, the media (count, aspect ratios, background consistency, focal points), the options and price points, the ribbons and sales. Then write the store's direction as a few lines, held with the design tokens:
+
+- a **one-sentence thesis** — the offer, the shopper, the character;
+- **three traits**;
+- an **avoid-list** of the stereotypes this store would fall into by default: "premium" does not mean dark, serif, minimal; "kids" does not mean primary colors; a bakery is not automatically cream and script. Keep the conventions of the store's own vertical that genuinely help shoppers compare and choose;
+- one **signature decision** that makes the store recognizable with the logo hidden, backed by real content — a product form, a material, the category structure, a typographic move;
+- a **media treatment** per placement (product, category, hero, fallback): frame ratio, `cover`/`contain`, focal behavior.
+
+Two stores with the same vertical and different catalogs should look nothing alike. Never ask the user for a reference store; if they supply one, take only portable principles (hierarchy, image prominence, rhythm, density), never its layout, palette, typefaces, or taxonomy.
+
+**Audit the media before giving it a role.** Never stretch an image, enlarge a thumbnail into a hero, or crop the product away; give every image a stable aspect ratio and `object-fit` so the grid doesn't jump. When hero-scale media is absent, compose the hero from typography, a product tile, or a collage of what exists. Product photography informs compatible backgrounds and contrast; it does not automatically dictate the UI's dominant color.
+
+## 2 · The surfaces and their bar
+
+- **Global shell:** category navigation from the live tree (a curated menu is fine, but every product-bearing category stays reachable); a persistent cart control with a live count; a footer sized to the real destinations. Announcement, shipping, and returns text only from the merchant.
+- **Homepage — a merchandising surface, not the shop page again.** Say what the store sells and give one dominant shopping action in the first viewport; real products from live queries under truthful headings; category discovery when the taxonomy is meaningful. Don't reuse the same first product as hero, first card, and feature. No section exists to fill space — a claim-dependent module with no truthful source is omitted.
+- **Gallery — a discovery surface.** Title, result count, sort, the filters the catalog supports, paging; in its default state a **real product card — image, name, price, link — is inside the first viewport**, also on a short desktop window. Skeletons while loading, a distinct "no results for these filters" with a reset, an honest empty catalog, a recoverable error. Filters that stay visible with the results commit immediately; filters in a sheet stage changes until Apply.
+- **Product page — a complete purchase decision.** In the first viewport at mobile, tablet, and desktop: a recognizable product image, name, price, the first required choice (or a control that jumps to it), and the buy action with its neutral disabled reason. Then every ribbon, the full description and info sections, a gallery of **every** image, quantity, and — when the catalog has them — subscriptions, preorder, group navigation, notify-me. A sticky buy region must never cover a control.
+- **Cart — a side drawer by default**, opened after every successful add and from the header: image, name, the chosen options and text, quantity editing with pending and failure states, line prices, the calculated subtotal and discount, "shipping and taxes calculated at checkout", and checkout **from the drawer**. Persists across navigation and refresh. A separate cart page is optional, never a mandatory step before checkout.
+- **Quick add** anchors to its card (an inline or attached panel; a bottom sheet on mobile); a centered dialog is the exception for a demonstrably large configuration, not the default. Its first view shows identity, price, the first required choice, and the action.
+
+## 3 · Overlays (cart drawer, quick add, mobile nav, filter sheet)
+
+Mount at the document root — a `position: fixed` panel inside a header with a `transform`, `filter`, or `backdrop-filter` gets clipped. Full-viewport scrim; background scroll locked and inert; the panel scrolls independently with Close and the primary action always reachable; focus moves in and is trapped while modal; Escape closes; focus returns to the trigger on close (or moves to a successor surface when one overlay opens another). Verify this in the browser — CSS alone doesn't prove it.
+
+## 4 · Truthful commerce copy
+
+- **Claims come from the merchant or the data, never from the page's need for a section.** No invented reviews, ratings, "X people bought this", scarcity, delivery promises, certifications, guarantees, or payment/trust badges.
+- **Labels match their source.** "Best Sellers" needs sales data or a category the merchant named that way; the catalog's default order is not a ranking. "Featured" or the category's real name is always safe.
+- **Write for shoppers, not implementers.** No Wix IDs, API names, "catalog", "current catalog", "headless", or integration words in headings, labels, buttons, or empty states.
+- **Prices tell the truth.** A ribbon is a label, never proof of a discount; a struck price is labelled ("was") and shown only when it is real and higher; a range never gets a lone struck minimum; savings are never computed in the client.
+- **Operational text is the merchant's.** A cart says "shipping and taxes calculated at checkout" rather than a number nobody configured.
+
+## 5 · Images
+
+Responsive delivery (`srcset` + `sizes` from scaled Wix media candidates — `how-to-code-a-store.md` § Rendering product images), stable aspect ratios with `width`/`height`, lazy loading below the fold, meaningful `alt` text from the catalog's `altText` or the product name. Failed images get a visible fallback, never a broken icon.