@wix/agent-skills 1.36.0 → 1.36.1

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

@@ -1,98 +0,0 @@
-# Astro — the pinned docs to read *before* connecting an Astro frontend to Wix
-
-Astro is the **documented default** frontend for Wix-managed headless — pick it unless the user names another framework (then read `non-astro.md` instead). This file is to *wiring an Astro frontend to the Wix backend* what `SEED.md` is to seeding: the pointer to *how* it connects — an **index of doc pages**, each with a one-line "what it settles" note, **followed by a Caveats section** carrying the things the docs don't say. It holds **no config blobs, page skeletons, design tokens, or payloads** — the model designs and writes the whole frontend; this file only says *how to connect it* and *what to watch out for*.
-
-**Auto-auth is the whole point.** On managed-Astro you create **no client** — no `createClient`, no `OAuthStrategy`, no `clientId`, no token handling in app code. You `import { x } from "@wix/<pkg>"` and call methods; `@wix/astro` + the session middleware authenticate every call automatically (§2, §3). The manual OAuth client survives **only** off this path — self-managed or non-Astro frontends (`non-astro.md`).
-
-**Hard constraint up front: Astro 5 only.** `headless link` does **not** support Astro 6 — check the project's Astro major before linking an existing project (Caveat A1).
-
-**How to use it.** Before scaffolding, wiring, or releasing, look the task up here and read its pinned pages top-to-bottom until you can act — read-then-act, never invent a URL or a config from memory. If a task has no entry, navigate from the doc index in §4.
-
-**URL form & how to read it.** Each pinned link is the **`.md` twin** of a docs article (the article URL with `.md` appended). A page pinned here is **already curated — read it directly; don't re-discover it with search.** The two read paths take **different URL forms** — don't mix them:
-
-- **`curl` the pinned link — first priority. Fetch it as-is (keep the `.md`)** for raw markdown.
-- **MCP doc tools — second priority** (discovery of a page this file doesn't pin, or a fallback if a fetch fails). **Pass the URL *without* the `.md` suffix:** `ReadFullDocsArticle` for the guide/article pages here; `SearchWixCLIDocumentation` / `SearchWixHeadlessDocumentation` / `SearchWixSDKDocumentation` to reach an unpinned command or method page.
-- **No MCP, or a shape not pinned anywhere → doc discovery** (`DOC_DISCOVERY.md`): a `curl` semantic search (`document_type: SDK`/`WIX_HEADLESS`) plus structured schema lookup, then read the hit's `.md?apiView=SDK`.
-
----
-
-## 1 — Get the project onto Wix (scaffold / link / connect)
-
-Pick the row that matches the operation, then read it before running anything.
-
-| Page | What it settles |
-|---|---|
-| <https://dev.wix.com/docs/wix-cli/command-reference/project-creation/create-headless.md> | **`create`** — `npm create @wix/new@latest -- headless`. The flags (`--folder-name`, `--business-name`, `--site-template`, `--skip-install`, `--skip-git`, `--no-publish`) and the **required `--` separator**. `--site-template` accepts `commerce\|scheduler\|registration\|blank`, but **we don't adopt the business templates** — the model designs, so scaffold `blank` and let config come from Wix, not template pages. |
-| <https://dev.wix.com/docs/go-headless/get-started/quick-starts/wix-managed-headless/quick-start-from-an-existing-astro-project.md> | **`connect`** (user brought an Astro project) — `npm create @wix/new@latest -- headless link`. The end-to-end "link an Astro project I already have" flow. |
-| <https://dev.wix.com/docs/wix-cli/command-reference/project-creation/create-headless-link.md> | **`headless link` reference** — link flags and **exactly what it mutates in `astro.config.mjs`** (the integration list, `output: 'server'`, the image domain, the prod fetch adapter). Read alongside Caveat A2 — the docs' list is incomplete. |
-| <https://dev.wix.com/docs/wix-cli/command-reference/project-creation/create-init.md> | **`init`** — connect existing code in place without scaffolding (the lower-level connect primitive). |
-| <https://dev.wix.com/docs/go-headless/get-started/quick-starts/wix-managed-headless/quick-start-with-the-wix-cli.md> | The end-to-end orientation for a fresh managed project, start to finish — read once for the shape of the whole flow. |
-
-## 2 — The integration & auth (the keystone)
-
-This is what makes managed-Astro different from every other path: authentication is automatic.
-
-| Page | What it settles |
-|---|---|
-| <https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/about-the-astro-integration.md> | **The keystone.** Auto-auth via the private app as OAuth handler, visitor sessions, member login, extensions, elevation. This is the "no client" anchor — read it first for §2/§3. |
-| <https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/handle-member-login-using-wix-s-astro-integration.md> | **Member login** — the built-in `/api/auth/login` + `/api/auth/logout` routes and the `returnUrl` param. Use these instead of hand-rolling login. **For the full frontend contract (login = sign-up, gate in SSR/backend route, current member via `@wix/members`, no client, no elevate, pricing-plans dependency) → Read `inline-recipes/how-to-code-members-astro.md`** (local — Read it, don't curl). **Only if the brief explicitly asks for a custom/branded login form or custom sign-up fields → Read `inline-recipes/how-to-code-members-custom-login.md`** instead (a client-driven `OAuthStrategy` flow — on Astro that means an explicit client in a backend route, outside auto-auth; pick by intent, not project type). |
-| <https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/elevate-api-call-permissions.md> | **Elevation.** A privileged read at runtime goes in a **backend HTTP endpoint** (`src/pages/api/*.ts`, `export const GET: APIRoute`) that wraps `auth.elevate()`, called from the frontend via `fetch('/api/…')`. This is the documented shape — prefer it over inline-frontmatter elevation. |
-| <https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/fix-403-errors-for-api-calls.md> | **Fix 403** — the identity-vs-permission troubleshooting page; read when a call 403s to tell "wrong identity" from "needs elevation." |
-
-## 3 — Frontend data access (SDK, no client)
-
-| Page | What it settles |
-|---|---|
-| <https://dev.wix.com/docs/sdk/articles/set-up-a-client/about-the-wix-client.md> | **Confirms managed-Astro is on the "don't need a client" list** — the client/`OAuthStrategy` is for self-managed only. Read it to be sure you should *not* be constructing a client here. |
-| <https://dev.wix.com/docs/api-reference/articles/sdk-setup-and-usage/develop-with-the-sdk.md> | **Develop with the SDK** — calling SDK methods across SSR / islands / backend endpoints, and where elevation fits. |
-
-One line on what reaches the frontend: **visitor-scoped reads work out of the box** with no wiring. **Admin-only data is seeded at build time** (see `SEED.md`) — don't reach for runtime elevation unless the data genuinely can't be seeded ahead of time.
-
-## 4 — CLI, project structure, dev loop, release
-
-| Page | What it settles |
-|---|---|
-| <https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md> | What the CLI is and why the structure is Astro-based; auto-auth + session middleware framing. |
-| <https://dev.wix.com/docs/wix-cli/guides/project-structure/project-structure.md> | **On-disk layout** — `.wix/`, `.astro/`, `astro.config.mjs`, `.env.local`, `wix.config.json`, `src/`. What's generated and not to be hand-edited. (Field-name note: `wix.config.json` carries `appId` + `siteId`/`projectId` — read defensively.) |
-| <https://dev.wix.com/docs/wix-cli/command-reference/project-commands/dev.md> | **`wix dev`** — local dev server with hot reload. |
-| <https://dev.wix.com/docs/wix-cli/command-reference/project-commands/build.md> | **`wix build`** — build before release/preview. |
-| <https://dev.wix.com/docs/wix-cli/command-reference/project-commands/release.md> | **`wix release`** — publishes the **frontend build output** to Wix hosting and registers the origin OOTB. **Release once, at the end** (`managed/CREATE.md` §5 / `CONNECT.md` §5) — not mid-flow. Re-release **only** when the build output itself changed. **Seeded backend content and entity images are fetched at runtime, not baked into the build** — a re-release does **not** refresh them, so never re-release to "clear a cache" for a backend data/image change (that's a red herring; a backend image not showing is an attach-shape bug — `SEED.md` § "Entity images"). Only if a genuine *frontend* republish shows stale build output does running `wix release` again help. |
-
-Prefer the documented `wix …` / `npm run dev\|build\|release` forms (the scaffold rewrites `package.json` to route them through `wix`). Deploy mechanics — origin registration, retries — live in `managed/DEPLOYMENT.md`, not here.
-
-## 5 — Environment variables (custom vars only)
-
-| Page | What it settles |
-|---|---|
-| <https://dev.wix.com/docs/go-headless/wix-managed-headless/project-development/environment-variables/manage-environment-variables.md> | **The documented mechanism.** Declare each var in the `envField` schema in `astro.config.mjs` (`context: client\|server`, `access: public\|secret`); import from **`astro:env/client`** / **`astro:env/server`**; set with **`wix env set --key=… --value=…`**, pull with **`wix env pull`** (no `--json`). **Never edit the `WIX_CLIENT_*` vars** — the CLI manages them. |
-| <https://dev.wix.com/docs/go-headless/wix-managed-headless/project-development/environment-variables/about-environment-variables-in-the-cli.md> | The four var types (client/server × public/secret) — read when choosing the right `context`/`access`. |
-
-This is for *custom* vars only. Because there's no client on managed-Astro, app code doesn't read `WIX_CLIENT_ID` at all (don't reach for the `import.meta.env.WIX_CLIENT_ID` manual-client pattern — managed-Astro has no client, so there's nothing to read it into).
-
-## 6 — SEO: let owners manage tags on item pages
-
-Main pages (home, listings, about) get their SEO tags **automatically** on managed-Astro — nothing to write. **Item pages** — any parameterized detail route (`/blog/[...slug]`, a product / service / event detail, an optional category/collection route) — do **not**: they need code so the tags a site owner edits in the dashboard reach the live `<head>`. Wire this on **every managed site that renders item/detail routes** — it's what lets owners control each item's `<title>`/description/OG/canonical without touching code, and it registers the route for the sitemap + dashboard SEO editor. Skipping it leaves detail pages with a generic fallback title the owner can't fix.
-
-| Page | What it settles |
-|---|---|
-| <https://dev.wix.com/docs/go-headless/wix-managed-headless/seo/add-seo-support-to-item-pages.md> | **The item-page SEO contract.** The three steps every detail route needs — export `wixMetadata` (route registration), call `loadSEOTagsServiceConfig(...)`, render `<SEO.Tags>` — plus the deps (`@wix/seo` + `@wix/essentials ≥ 1.0.10`), the `WIX_APPS` sourcing rule (reference it directly in the export), per-page-type values, and how to verify. Read it before writing any `[slug]` / `[...slug]` detail page. |
-
-The **per-vertical values** — which `WIX_APPS.*PageMetadata` accessor + `seoTags.ItemType.*` to pass — live in each capability's `inline-recipes/how-to-code-*.md` (blog, store, bookings, events each name theirs).
-
-## 7 — Caveats (the gaps the docs don't mention)
-
-The heart of the file: hard-won knowledge the docs won't surface. These are **guidance the model must follow when it writes the frontend** — not things this skill writes for it.
-
-| Caveat | What it says |
-|---|---|
-| **A1 — Astro 5 only** | `headless link` does **not** support Astro 6. Before linking an existing Astro project, check its Astro major; on 6 it fails. Fresh scaffolds are fine (they pin a supported Astro). |
-| **A2 — `astro.config.mjs` always carries `wixPages()` + `checkOrigin: false`** | A working config must **always** include `@wix/astro-pages` (`wixPages()`) alongside `wix()`/`react()`, **and** set `security: { checkOrigin: false }`. Neither is in the docs; both are **unconditional** (no "when to add" logic). `wixPages()` injects the `/_wix/pages.json` page manifest + the `wix:astro:pages` virtual module the Wix platform consumes — omit it and `/_wix/pages.json` 404s. `checkOrigin: false` disables Astro 5's CSRF origin check, which false-positives on legitimate same-site POSTs behind Wix hosting; it's a safe no-op when there are no server POSTs. If you touch `astro.config.mjs`, keep both. |
-| **A3 — Guard every SSR SDK call** | Wrap every Wix SDK call in `.astro` frontmatter in `try/catch` — an unguarded throw truncates the response mid-stream (white screen). Memoize repeated SSR probes at module scope to coalesce duplicate calls within a request. |
-| **A4 — Islands reading browser-only state must be `client:only="react"`** | An island that reads browser-only state (cart badge via `sessionStorage`, availability/booking widgets) must be `client:only="react"`, not `client:load` — otherwise SSR renders a zero/empty state and hydration flashes it to the real value. |
-| **A5 — No HTML comments in `.astro` frontmatter** | `.astro` frontmatter is TypeScript — use `//`, never `<!-- -->`, or the build fails. |
-| **A6 — Wix media + rich text** | **Resolve `wix:image://` URIs — never hand-build the CDN URL.** SDK media fields (product/blog/CMS images) come back as internal identifiers like `wix:image://v1/<hash>/<file>#originWidth=…`, **not** ready URLs. Convert them with the SDK media module — `import { media } from '@wix/sdk'`, then `media.getScaledToFillImageUrl(uri, w, h, {})` (**returns the URL string directly — do NOT append `.url`; the 4th `options` arg is required, pass `{}`**), or `media.getImageUrl(uri).url` for the original (**that** one returns a `{ url }` object). The two shapes differ — mixing them (`getScaledToFillImageUrl(...).url`) resolves every image to `undefined`. Manually building a `static.wixstatic.com/.../v1/fit/...` URL gets the format wrong and the image **403s** (or silently fails to load). Only `wix:image://` values need this — an already-absolute `https://` URL (e.g. an Unsplash placeholder) passes straight through. Docs: <https://dev.wix.com/docs/sdk/core-modules/sdk/media>. Then **constrain** Wix image URLs (`aspect-ratio` + `object-fit: cover`) or they render at intrinsic size and overflow the layout. **Rich text:** the ban is on dumping *raw* HTML/Ricos into a text node — when you bind a rich-text field into a layout slot (a card excerpt, a `textContent` string), use its `.plain` variant. This is **not** a "render plain text" rule: a **blog post body is `richContent` (Ricos) and must render formatted** — via `@wix/ricos`, or by converting Ricos → sanitized HTML and rendering with `set:html` (SDK_HANDOFF §3/§6 require full formatted content, not flattened text). Plain `.plain` is for short bound fields; formatted Ricos is for the post body. |
-| **A7 — `clientId` is off-path here** | In managed-Astro there is no client, so `appId`-as-`clientId` only matters on the self-managed / non-Astro path (see `non-astro.md`). Don't construct one here. |
-| **A8 — Member auth uses the built-in routes, never an `OAuthStrategy` client** | Render account/gated UI **behind a login check resolved server-side** — in SSR frontmatter (guarded `try/catch`, A3) or a `src/pages/api/*.ts` route — and bounce anonymous visitors with `/api/auth/login?returnUrl=…` (the same shape blog comments already use). **Do not build an `OAuthStrategy` login handshake on Astro** — that's the non-Astro path and it 500s under auto-auth. Read the current member with **`@wix/members` `getCurrentMember`** (not the dev-preview `@wix/site-members`). Full contract: `inline-recipes/how-to-code-members-astro.md`. |
-| **A9 — `sharp` is dev-only and never used here — pre-empt it, never build or diagnose it** | `sharp` is **not** a declared dependency: it's an *optional* transitive dep of Astro (`astro.optionalDependencies.sharp`, absent from your `package.json`) that powers only Astro's **local, build-time** image optimization (`astro:assets` / `<Image>`). This headless flow serves **remote Wix Media URLs** (`static.wixstatic.com`) through plain `<img>` — it **never** calls `<Image>`, so sharp is invoked at neither build nor runtime; it is pure dev-time dead weight here. Its postinstall can try to **build from source via node-gyp, fail, and abort the whole `npm install`, leaving `node_modules/` empty.** **Pre-empt this — don't react to it: always run `npm install --ignore-scripts`** (skips sharp's failing native build; the Wix CLI/SDK packages carry no postinstall that this breaks). **Do not** reach for **`--no-optional`** (deprecated / a silent no-op in npm 7+, so sharp still builds and aborts) or **`--omit=optional`** (sharp still resolves and builds). A missing or failed `sharp` is **expected and irrelevant** to a site that serves remote image URLs: **never** retry the install, switch node versions, add `node-addon-api`, or spend *any* time diagnosing a sharp error — one `--ignore-scripts` install, then move straight on. |
-
-> **Seeding token (cross-link, not duplicated):** build-time seeding still mints a REST token via the Wix CLI — that token is **byte-identical on every re-mint**, so mint once and reuse. The full token mechanism lives in `managed/AUTHENTICATION.md`; don't restate it here.

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

@@ -1,102 +0,0 @@
----
-name: "Donations Experience"
-description: The donor-facing design and copy bar for a Wix Donations site, covering cause discovery, campaign pages, accessible giving forms, recurring intent, draft recovery, truthful progress and checkout returns. Read when building or wiring a donation experience; the API contract lives in how-to-code-donations.md.
----
-**EXPERIENCE OVERLAY**: What makes a donation experience good — read after the general `DESIGN.md` and `CONTENT.md` when using those guides.
-
-Read alongside [How to Code Donations](how-to-code-donations.md). These are defaults, not
-a prescribed design: the user's brief wins. Configure campaigns only when asked; presentation must
-follow their live settings. These principles are framework- and hosting-independent; this is a
-Headless experience, not instructions to install an Editor widget.
-
-## Design from the cause
-
-Inspect campaign count, names, imagery, amounts/impact text, frequencies, goals and giving rules
-before choosing layout and tokens. Use the organization's supplied story and brand to choose a
-distinctive visual direction; “nonprofit” does not imply one palette, stock photograph or page formula.
-Treat approved imagery with dignity; do not present generated beneficiaries or events as documentary
-evidence. The campaign entity has no story field; keep authored narrative separate from its data.
-
-- **Homepage:** explain who is helped, what the organization does and one clear route to give in the
-  first screen. Follow with the content that earns the decision: a real featured cause, supplied impact
-  explanations, a story, or verified trust information. A single-cause site need not invent a campaign
-  gallery. Distinguish receiving help, volunteering, sponsorship and merchandise from donating.
-- **Several campaigns:** offer meaningful discovery with image, name, optional real progress, status
-  and a direct campaign link. Keep cards aligned with long names and missing images. One campaign
-  can open directly at `/donate`; do not add an unnecessary selection step. On phones, keep the
-  introduction and covers compact enough that the first cause's name and entry point appear in the
-  first screen, not just a large image. This is discovery, not a second homepage hero.
-- **Campaign page:** show the cause, concise context and giving form together. On phones, bound the
-  image and long story: at about 390px wide, the first screen should expose the cause, the start of
-  amount/frequency selection and a clear Donate action. Let longer choices/details scroll rather
-  than shrinking every control to fit. On desktop a side-by-side layout is useful, not mandatory.
-  Keep readable type and price labels without clipping.
-  Use real missing/archived states; never silently substitute another cause.
-
-## Make the giving decision clear
-
-- Show configured presets and their impact text. Offer custom giving only when enabled, and expose
-  its actual bounds near the field. Validate empty, invalid, non-positive and out-of-range input; show
-  errors after interaction/attempt, retain the donor's work and prevent handoff until corrected.
-- Offer only configured frequencies. Use clearly selected, keyboard-operable controls; even when
-  only one frequency exists, make a recurring commitment explicit. Amount shortcuts must preserve
-  their advertised amount and cadence; no silent conversion from one-time to monthly. Carry explicit
-  monthly-giving intent through discovery into the selected campaign's form when offered; later
-  donor edits take precedence. Explain an unavailable frequency instead of silently substituting it.
-- Prefer native radios with a shared name and a fieldset/legend for amount and frequency choices.
-  Custom radios must implement labelled groups, arrow-key navigation, selection and visible focus.
-  Associate errors/hints with their inputs and focus the first invalid control after an attempted
-  submission, not on every keystroke. See [form feedback](https://www.w3.org/WAI/tutorials/forms/notifications/).
-- Show currency and the selected amount/frequency in the primary action or its adjacent summary.
-  Fee coverage, when enabled, is visible, reversible and explained beside its checkbox, including its
-  recurring effect. Use the catalog fee flag, not a second local surcharge. Totals must agree at checkout.
-- Show a note only when enabled. A contextual dedication label is useful only when the control and
-  its persistence work; free text is not tribute notification or a restricted fund. Do not collect the
-  donor's billing/payment data again when hosted checkout already owns that step.
-- One Donate action owns the pending/redirect flow. Disable repeated activation, show progress and a
-  recoverable error. No merchandise-cart drawer or cart-page detour is required for direct giving.
-
-## Preserve the donor's work
-
-Restore a per-campaign draft after navigation, refresh and checkout cancellation: preset/custom mode,
-amount, frequency, fee choice and note. Scope short-lived, per-tab state to the content site, visitor
-and campaign; keep notes out of URLs, logs and long-lived storage. Revalidate restored choices against
-current campaign settings and show a correction when necessary; do not silently replace an amount or
-cadence. Expire drafts and clear them on explicit reset, visitor change or verified completion. A
-checkout return alone is neither completion nor a reason to reset the form.
-
-## Progress and confidence without invented claims
-
-Use goals and metrics only when configured and readable. No goal means no progress module. A failed
-metrics read is not zero donations; omit unavailable figures while keeping the form usable. Counts
-are donations, not unique donors. A bar stays within its track above 100%, while the real number may
-exceed the goal. Let the API's status/acceptance rules decide closure, not an inferred percentage.
-
-Use organization-supplied identity, contact, policies and substantiated claims. Do not invent tax
-deductibility, matching grants, certifications, urgency, donors, receipts or outcomes. For recurring
-giving, include the actual cancellation/help route or policy when supplied; no nonfunctional “manage
-subscription” control. Keep offline giving and other support paths secondary and accurately labeled.
-Avoid unsolicited signup/promotional popups that interrupt giving. Metadata, social links and policy
-destinations must belong to the organization, with no template placeholders. Give each campaign its
-own title, description and sharing image from its name and approved content, not a repeated generic
-homepage description. Do not invent a campaign SEO API field.
-
-## Finish the whole donor journey
-
-Verify loading, empty, closed, missing, invalid, submitting, failed and return states, not only the
-happy-path screenshot. Test desktop, a common phone width (around 390px) and a narrow phone (320px),
-including long campaign names, header/logo/CTA fit, discovery density, form controls and focus/error
-states. No horizontal overflow or clipped actions; do not just hide overflow. A sticky region must
-not cover controls; any modal/sheet needs scroll and focus management. Follow a monthly entry link
-through cause selection, then test custom amount + fee + note → checkout → cancel/back; choices must
-survive. Check refresh recovery too, without submitting a payment.
-
-Check the anonymous API → hosted-checkout handoff as required by the integration recipe. Verify that
-the checkout names the right cause and commitment. On return, show paid/order facts only when
-verified with appropriate access; an abandoned flow or direct thank-you visit is not proof of payment.
-Keep a generic acknowledgement when order details cannot be read. Do not claim a tax receipt or
-successful payment from the URL alone. Even an unverified return needs a meaningful heading, a clear
-verification-status message and a useful next step, not an empty page or a disclaimer alone. Verify
-hosted checkout separately from the custom form; qualify a desktop-viewport-only mobile check and
-confirm suspected hosted rendering problems on a real mobile browser. No live payment without
-explicit authorization.

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

@@ -1,49 +0,0 @@
----
-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, a filter panel, paging, and a buy path on every card. The filter panel — price, stock, and the option facets the catalog has (Color as swatches) — is **required whenever the catalog has anything to filter**; it is not polish to add if the brief mentions it. Every card offers a way to buy: one click for a product with no options, a quick-add picker for one with options, the product page only when the product needs free text. 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. Cards hold their hierarchy under the catalog's longest name and a ranged price: name and price on separate lines, the price never clipped, checked at phone width; a color option may show as swatches on the card when there is room.
-- **Categories are pages.** Every product-bearing category has its own URL (`/category/<slug>`), linked from the navigation — a shopper can share it and a search engine can index it. A category that exists only as a filter toggle on the shop page is not enough.
-- **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. On a phone this decides the layout: the image is a bounded band, not a full-screen hero that pushes the price and the button below the fold; description and details come after the action. 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, the subscription plan and its billing terms when the line is one, 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.

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

@@ -1,196 +0,0 @@
----
-name: "How to Code a Blog"
-description: The frontend read contract for a Blog V3 site — which @wix/blog modules to import, how to list/get posts with the mandatory RICH_CONTENT fieldset, how to resolve categories/tags/cover media, how to render Ricos rich content, and the read-public/write-authenticated comments flow. Specifies the *how* (modules + exact calls + the failure modes the docs omit); which posts to render come from the blog the site reads.
----
-**RECIPE**: How to Code a Wix Blog Frontend (Blog V3 + Ricos rich content)
-
-A concise contract for writing the **frontend code** of a blog against a Blog V3 site: listing posts, opening a post by slug, rendering its rich content, resolving categories/tags/cover images, and (optionally) reading and submitting comments. **This recipe is the *how* (which modules, which calls, which fields), not the *what*** — which posts to show, how the page looks, and the framework are decided by the request you're fulfilling.
-
-> **This recipe is for CODING the blog, not for seeding it.** It assumes a Blog V3 site already exists (published posts, optional categories/tags). It says nothing about creating posts — only how to read and render them from frontend code.
-
-> **⚠️ Reading rule — always append `.md?apiView=SDK` to every doc link below.** The Wix docs render two views of the same page. The **bare / REST view shows `id`**; the **`?apiView=SDK` view shows `_id`** — and the SDK is what your frontend calls. Reading the REST view by mistake is the most common source of `undefined`-id bugs (links to `/blog/undefined`). Fetch the `.md?apiView=SDK` form directly; if a field name surprises you, you're probably reading the REST view.
-
----
-
-## The modules and the client (read this first)
-
-**Wix Blog app id** (a constant Astro needs for blog-post page routing, and comments need as `appId`):
-`14bcded7-0066-7c35-14d7-466cb3f09103`
-
-**⚠️ CRITICAL: blog posts are NOT CMS collections — use `@wix/blog`, never `@wix/data`.** Querying blog content through `@wix/data` reads the wrong store and returns nothing. Import only:
-
-| Need | Package | Module |
-|---|---|---|
-| Posts (list, get, query by slug) | `@wix/blog` | `posts` |
-| Categories (resolve `categoryIds`) | `@wix/blog` | `categories` |
-| Tags (resolve `tagIds`) | `@wix/blog` | `tags` |
-| Render rich content | `@wix/ricos` | `RicosViewer` + `quickStartViewerPlugins` |
-| Resolve `wix:image://` cover URIs | `@wix/sdk` | `media` |
-| Likes — like/unlike a post (only if the site has members) | `@wix/blog` | `likes` |
-| Comments — read/submit (only if the blog has comments) | `@wix/comments` | `comments` |
-| Comment/like author name/photo (only with members) | `@wix/members` | `members` |
-
-Discover the exact current call shapes with `SearchWixSDKDocumentation` (e.g. `"blog query posts"`, `"comments queryComments createComment"`) rather than walking a module menu — the menu pages often surface only dashboard/extension pages, not the runtime query functions. The `@wix/ricos` viewer API moves between versions — **follow the blog doc to the current viewer API; don't pin a version blind.**
-
-**Auth / client — framework split:**
-- **Astro (Wix-managed):** authentication is ambient. Call `posts` / `categories` / `tags` directly from server components and backend routes (`src/pages/api/*.ts`) — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
-- **Non-Astro (Vite/React/Vue/static):** build one manual visitor client and reuse it:
-  ```js
-  import { createClient, OAuthStrategy } from '@wix/sdk';
-  import { posts, categories, tags } from '@wix/blog';
-
-  const client = createClient({
-    modules: { posts, categories, tags },
-    auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
-  });
-  ```
-  The `clientId` is public, not a secret.
-
----
-
-## The blog features (build the ones the site needs)
-
-Each section below is a **self-contained blog feature** — implement only the ones the site uses; they don't have to be built in order. The only ordering is *within* a feature (e.g. resolve `categoryIds` after you have the post).
-
-### Listing posts (and the `RICH_CONTENT` + `_id` rules)
-
-Query posts with `posts.queryPosts(...)`, newest first:
-
-```js
-const { items } = await posts
-  .queryPosts({ fieldsets: ["RICH_CONTENT", "URL"] })
-  .descending("firstPublishedDate")
-  .limit(20)
-  .find();
-```
-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.)
-
-**⚠️ CRITICAL: the entity id is `_id`, NOT `id`.** The SDK normalizes every entity's id to **`_id`**; `post.id` is `undefined` in SDK code. Use `post._id` for keys and lookups, and `post.slug` for links (`/blog/${post.slug}`). (A surprising field name means you're reading the REST doc view — re-open it with `?apiView=SDK`.)
-
-**Visibility:** only published posts are returned to a visitor token, so a missing post usually means it wasn't seeded `publish: true` — not a query bug (ties back to the seed recipe).
-
-### Opening a post by slug
-
-Filter by `slug` and take the first item:
-
-```js
-const { items } = await posts
-  .queryPosts({ fieldsets: ["RICH_CONTENT", "URL"] })
-  .eq("slug", slug)
-  .find();
-const post = items[0];
-if (!post) { /* 404 → redirect to /blog */ }
-```
-
-**Astro page routing + SEO (Wix-managed) — `wixMetadata` is required.** A blog-post detail page (`src/pages/blog/[...slug].astro`) is a Wix **item page**: its `<title>`/description/OG/canonical come from what the owner sets in the dashboard. Wire it per the canonical guide — **[Add SEO Support to Item Pages](https://dev.wix.com/docs/go-headless/wix-managed-headless/seo/add-seo-support-to-item-pages.md)** — which covers all three steps: export `wixMetadata` (registers the route → sitemap + dashboard SEO editor), call `loadSEOTagsServiceConfig(...)`, and render `<SEO.Tags>` (from `@wix/seo`; deps + `@wix/essentials ≥ 1.0.10` are in the guide's "Before you begin"). Source `wixMetadata` from `WIX_APPS`, referenced **directly** inside the export (it's evaluated in module scope):
-
-```js
-import { WIX_APPS } from "@wix/essentials";
-import { seoTags } from "@wix/seo";           // → itemType: seoTags.ItemType.BLOG_POST
-
-export const wixMetadata = {
-  appDefId: WIX_APPS.blogs.id,
-  pageIdentifier: WIX_APPS.blogs.postPageMetadata.pageIdentifier,
-  identifiers: { slug: WIX_APPS.blogs.postPageMetadata.identifiers.slug },
-};
-```
-Use the `[...slug]` **rest** param (not `[slug]`), and `Astro.params` directly — Wix headless projects run `output: "server"` (SSR), so there's no `getStaticPaths()`. **If you add a blog category route** (e.g. `/category/[slug]`), wire it the same way with `WIX_APPS.blogs.categoryPageMetadata` + `seoTags.ItemType.BLOG_CATEGORY`. ⚠️ Dashboard SEO *overrides* for blog **categories** may not be honored by the resolver (it can return label-derived defaults) — the route still registers and gets valid default tags, so this is a Wix-side gap, not a wiring bug.
-
-### Rendering the post body (Ricos rich content)
-
-The body is **Ricos** (`post.richContent`), not HTML — **never** `set:html={post.content}` (there is no `.content`), and never `String(node)`. Render it with `@wix/ricos`:
-
-```tsx
-// src/components/RicosViewer.tsx
-import { quickStartViewerPlugins, RicosViewer } from '@wix/ricos';
-import '@wix/ricos/css/all-plugins-viewer.css';
-
-const plugins = quickStartViewerPlugins();   // module-level, once — not per render
-
-export default function RicosContentViewer({ content }) {
-  if (!content) return null;
-  return <div className="ricos-content"><RicosViewer content={content} plugins={plugins} /></div>;
-}
-```
-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.
-
-**⚠️ Ricos text invisible on dark themes.** The Ricos library CSS hardcodes near-black text color on paragraphs/lists. If the site theme is dark, scope an override on the `.ricos-content` wrapper forcing `var(--color-text)` — and in Astro use `<style is:global>`, because React islands don't inherit scoped Astro styles.
-
-For a short excerpt/card summary use `post.excerpt` (a plain string) — not the raw `richContent` nodes.
-
-### Resolving categories and tags
-
-`post.categoryIds` / `post.tagIds` are id arrays — resolve each to a label:
-
-```js
-const { category } = await categories.getCategory(id);   // ENVELOPE — destructure { category }
-const tag = await tags.getTag(id);                        // returns the BlogTag DIRECTLY — do NOT destructure
-```
-Docs: <https://dev.wix.com/docs/api-reference/business-solutions/blog/category/get-category.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/get-tag.md?apiView=SDK>
-
-**⚠️ CRITICAL: the two return shapes differ.** `categories.getCategory(id)` returns an **envelope** `{ category }` — destructure it. `tags.getTag(id)` returns the **tag object directly** — destructuring it as `{ tag }` yields `undefined`. Getting this backwards is a silent `undefined.label`.
-
-### Rendering the cover image
-
-A post's cover lives at `post.media?.wixMedia?.image` and may be a **`wix:image://` identifier, not a ready URL**. Resolve it with the SDK media module:
-
-```js
-import { media } from '@wix/sdk';
-const coverUrl = post.media?.wixMedia?.image
-  ? media.getImageUrl(post.media.wixMedia.image).url   // or media.getScaledToFillImageUrl(ref, w, h)
-  : undefined;
-```
-
-**Never hand-build a `static.wixstatic.com/.../v1/fit/...` URL** — the format is easy to get wrong and the image then **403s**. Only `wix:image://` values need resolving; an already-absolute `https://` URL (e.g. an Unsplash placeholder seeded when imagery is off) goes straight into `<img src>`. Constrain Wix image URLs with `aspect-ratio` + `object-fit: cover` so they don't overflow at intrinsic size. Doc: <https://dev.wix.com/docs/sdk/core-modules/sdk/media>
-
-### Member features (only if the site has the members capability)
-
-When the site has **members** (login — see `how-to-code-members-astro.md` / `-non-astro.md`), two blog features become member-native. Both follow the same **read-public / write-as-the-logged-in-member** shape as everywhere else — resolve identity at the action, never gate the whole page, and **never `auth.elevate()`** for a member acting on their own behalf.
-
-> **⚠️ Members-only (gated) content — gate on a LIVE, queryable signal, never a hardcoded id/slug list.** If the brief gates full articles to paying members, decide "is this post gated?" from a signal **carried on the post itself** and read at request time — a `members-only` blog **category or tag**, or a boolean field on a companion CMS record — so a gated post the owner publishes later **self-classifies** with no code change. **Do NOT** gate by a hardcoded list of "premium" post slugs/ids frozen at build time: a members-only post added afterward would read as **public** (an owner edit silently lost). Combine the gate with the member check — resolve the visitor's plan/login at the action, and reveal the full body only when both the post is flagged gated *and* the member is eligible (plan eligibility is itself a live read — see `how-to-code-pricing-plans.md`).
-
-> **⚠️ Members can LIKE and COMMENT — they CANNOT author or manage posts.** Every draft-post write/query method (`createDraftPost`, `updateDraftPost`, `publishDraftPost`, `deleteDraftPost`, `queryDraftPosts`) is **admin-only** (`applicableIdentities: [APP]`, Manage-Blog scope) — a member token is rejected. Blog authoring is a back-office capability; the seed recipe's `memberId` only *attributes* a post to a member, it doesn't grant members authoring rights (`setup-blog.md` STEP 1). Do **not** build a "write a post" / "my drafts" member surface expecting the member's own session to work. (It's only achievable by an app-mediated backend that `auth.elevate()`s to APP, creates on the member's behalf, and enforces per-member ownership itself — an authoring workflow with moderation implications, not a drop-in feature. Don't build it unless the brief explicitly asks.)
-
-### Likes (member-native)
-
-Liking is a first-class member action — `likes.createLike` / `deleteLike` / `queryLikes` accept a **`MEMBER`** identity (not admin), so a logged-in member likes/unlikes a post directly.
-
-- **Show the count + "liked by me":** `likes.queryLikes` (public read) for the per-post total; the current member's like state comes from their own likes. Post-level engagement counts are also on the post via the metrics fieldset.
-- **Toggle:** on click, POST to a backend endpoint (`src/pages/api/*.ts`) that calls `likes.createLike` / `deleteLike` with the request session; if the caller isn't a member, redirect to `/api/auth/login?returnUrl=…` (same gate-on-action shape as comments). Keys off the post id (`post._id`).
-- Discover shapes: `SearchWixSDKDocumentation "blog likes createLike queryLikes"`.
-
-### Comments — read public, write authenticated
-
-> **⚠️ Intent-gate this feature.** Comments **hard-depend on members/login**, so build them **only when the brief explicitly asks for reader comments or discussion.** An unrequested comments feature drags in an unrequested login gate — consistent with the `CAPABILITIES.md` blog entry (comments are optional / intent-gated, not part of the baseline blog surface). Reading comments is public; **submitting / editing / deleting** needs a logged-in member — render the thread always, and resolve identity **at the action** (show a "log in to comment" prompt to anonymous visitors, not a form that bounces).
-
-Package: `@wix/comments` (`comments`). The API keys off the post's **`referenceId`** — request the `REFERENCE_ID` fieldset when fetching the post, then `contextId = resourceId = post.referenceId`, and `appId = "14bcded7-0066-7c35-14d7-466cb3f09103"` (the Blog app id).
-
-- **List (public, SSR) — use `listCommentsByResource`, NOT `queryComments`.** `comments.listCommentsByResource(APP_ID, { contextId, resourceId, commentSort: { order: "OLDEST_FIRST" }, cursorPaging: { limit } })` → returns `{ comments }`. **⚠️ The docs' `queryComments` example ships wrapped in `auth.elevate(comments.queryComments)` — an admin path that must NOT be used for the public/anonymous SSR read.** Reaching for `queryComments` steers you straight into that elevated example; use `listCommentsByResource` for the visitor read.
-- **Comment body is Ricos, not a string.** `createComment` / `updateComment` take `content: { richContent: <ricos-doc> }` — the same `{ nodes: [{ type:"PARAGRAPH", nodes:[{ type:"TEXT", textData:{ text, decorations:[] }}]}]}` shape as post bodies. Convert the textarea string ↔ Ricos yourself (a small `plainTextToRicos` / `ricosToPlainText` helper).
-- **Submit (member-gated):** POST to a backend endpoint (`src/pages/api/*.ts`) that resolves the session and calls `comments.createComment(...)`; if the caller isn't a member, redirect to `/api/auth/login?returnUrl=…` (framework-provided on managed Astro — **no `src/pages/api/auth` file needed**, `@wix/astro` emits it at build). **Not** a client island.
-- **Edit / delete own comment — ownership is app-enforced.** The SDK does **not** enforce ownership server-side, so you must: fetch first (`comments.getComment(id)`), check `existing.author?.memberId === member._id`, then `comments.updateComment(id, { revision: existing.revision, content })` (**⚠️ update requires the fetched `revision`**) or `comments.deleteComment(id)`.
-- **Comment count:** request the **`METRICS` fieldset** on the post fetch and read `post.metrics.comments`. Do **not** call `comments.countComments` — it needs elevation.
-- **Author name/photo:** resolve `comment.author?.memberId` (and `post.memberId`) via `@wix/members`. Comment fields normalize to **`_id`** / **`_createdDate`** (same `_id` rule as posts).
-- **Pagination / "load more":** `listCommentsByResource` is **cursor-paged** — pass `cursorPaging: { limit }` and follow the returned paging **cursor** for the next page; don't offset-page.
-- **"Edited" indicator:** after an update, `comment.contentEdited === true` — render an "(edited)" marker.
-- **Threaded replies (optional, only if the brief wants nested discussion):** a reply carries `comment.parentComment` (present *only* on replies); `comment.replyCount` is the number of replies; fetch one comment's thread with `comments.getCommentThread(commentId, …)`. For a flat thread (the common case), ignore `parentComment` and just render the `listCommentsByResource` results in `OLDEST_FIRST` order.
-- **Optional extras (wire only if asked):** comment votes — `comment.voteSummary.upvoteCount` / `downvoteCount`; and marking/pinning — `comment.marked`.
-
-> **⚠️ REST-vs-SDK permission trap.** The raw REST comments methods all report `applicableIdentities: [APP]` (admin) — but the **`@wix/comments` SDK path** resolves the **read as public** and the **write as the logged-in member**. Don't let the REST spec push you into `auth.elevate()`-ing the read or the member write — that's wrong for the visitor thread. Only the genuine **moderation** calls (`hideComment`, `moderateDraftContent`, `countComments`, `markComment`, publish/bulk-*) need elevation, and those are back-office, not part of the visitor-facing feature.
-
----
-
-## Conclusion
-A correct Blog V3 frontend:
-- imports **`posts` / `categories` / `tags` from `@wix/blog`** (+ `@wix/ricos`, `media`) — **never `@wix/data`** for blog content;
-- queries with the **`RICH_CONTENT` fieldset** (else `richContent` is `undefined`) and uses **`post._id`** (never `post.id`) and `post.slug` for links;
-- renders the body with **`@wix/ricos` `RicosViewer`** (`client:only="react"` in Astro, `.ricos-content` color override for dark themes) — never `set:html`, never raw nodes;
-- destructures **`categories.getCategory` as `{ category }`** but takes **`tags.getTag` directly** (not `{ tag }`);
-- resolves **`wix:image://` covers via the SDK `media` module** — never a hand-built CDN URL;
-- exports **`wixMetadata`** on the Astro `[...slug]` detail page;
-- if comments exist, reads them **public/SSR** and submits via an **authenticated API endpoint** keyed on **`post.referenceId`** + the Blog `appId`;
-- if the site has **members**, wires **likes** (`@wix/blog` `likes`, `MEMBER`-scoped) and comments as member-native, gate-on-action features — but **never** a member post-authoring surface (all draft-post methods are APP-only; a member token is rejected).