@wix/agent-skills 1.6.0 → 1.7.0

package/skills/wix-headless/references/{blog → astro/blog}/BLOG_SETUP.md

@@ -5,7 +5,7 @@ Prerequisites, dependencies, blog service module, and astro config changes for t
 ## Prerequisites
 
 - A Wix Managed Headless project (has `wix.config.json` and `astro.config.mjs`)
-- The **Wix Blog app** installed on the connected Wix site (via MCP after scaffolding, or installed via MCP if missing — see `BLOG_CONTENT.md` Step 0)
+- The **Wix Blog app** installed on the connected Wix site (installed via the apps-installer REST endpoint after scaffolding — see `../../blog/BLOG_CONTENT.md` Step 0)
 - At least one published blog post in the Wix dashboard
 
 ## Package Installation
@@ -215,4 +215,4 @@ Key details:
 - `media.getImageUrl(ref).url` resolves Wix media references to real URLs
 - `getPostBySlug` returns `null` for missing posts — pages must handle this with a redirect
 - `queryBlogPosts()` sorts by `firstPublishedDate` descending (newest first)
-- `RICH_CONTENT` fieldset is required to get renderable content for `RicosViewer`
+- `RICH_CONTENT` fieldset is required to get renderable content for `RicosViewer`

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

@@ -0,0 +1,214 @@
+# CMS Foundations — Code Patterns for `@wix/data` (astro)
+
+The **rendering / code-patterns** half of CMS foundations: service module template, `@wix/data` SDK queries, image resolution, elevated access, and rich-text (Ricos) rendering — everything a CMS **page** scope needs to read collections and render them in Astro.
+
+> **Seeding lives in the business track.** Creating collections and inserting/verifying items via REST is **not** here — it is in `<SKILL_ROOT>/references/cms/CMS_FOUNDATIONS.md` (the `seed` scope's doc). This file is consumed by the `pages` scope; that file by the `seed` scope. The `cms/INSTRUCTIONS.md` router points each scope at the right half.
+
+> **Import note (read first).** Page code in this plugin uses `import * as items from "@wix/wix-data-items-sdk"` rather than the documented `import { items } from "@wix/data"`. The Wix-headless docs still show the `@wix/data` form, but `@wix/data` 1.0.448 dropped the `items` re-export — only sub-namespaces (`backups`, `collections`, `permissions`, …) remain, and the documented form fails the build with `'items' is not exported by '@wix/data'`. The actual `items` API (with `query`, `insert`, `update`, `remove`, `bulkInsert`, etc.) lives in `@wix/wix-data-items-sdk`, which `@wix/data` depends on transitively. Importing from there directly works on every current `@wix/data` version. SETUP.md's per-pack install table (Step 4c) installs `@wix/wix-data-items-sdk` (alongside `@wix/data` and `@wix/essentials`) for the cms pack so it's always present. Use the wix-data-items-sdk import everywhere.
+
+## Rendering Ricos rich-text fields
+
+Wix CMS stores `RICH_TEXT` / `RICH_CONTENT` fields as **Ricos JSON** — a structured node tree (PARAGRAPH, HEADING, BULLETED_LIST, etc.), not HTML. The dashboard's rich-text editor reads and writes this format.
+
+For SSR Astro pages (about, faq, portfolio, team, resource), import the seeded `renderRicos` util from `src/utils/ricos.ts`. The util is shipped by `seed-utilities.sh` (copied from `<SKILL_ROOT>/shared-utilities/ricos.ts` during Setup), so it's already on disk — do NOT inline a Ricos walker in your page.
+
+```astro
+---
+import * as items from "@wix/wix-data-items-sdk";
+import { auth } from "@wix/essentials";
+import { renderRicos } from "../utils/ricos";
+
+const elevatedQuery = auth.elevate(items.query);
+const { items: results } = await elevatedQuery("about-content")
+  .limit(1)
+  .find();
+const about = results[0];
+const bodyHtml = renderRicos(about?.body);
+---
+
+<article class="prose">
+  <h1>{about?.heading}</h1>
+  <div set:html={bodyHtml} />
+</article>
+```
+
+The util covers the common subset (PARAGRAPH, HEADING 1-6, BULLETED_LIST / ORDERED_LIST / LIST_ITEM, BLOCKQUOTE, DIVIDER + BOLD / ITALIC / UNDERLINE / LINK decorations). Anything outside that set renders defensively as a `<p>` with the raw text — never throws.
+
+> **Why not @wix/ricos?** The blog vertical uses `@wix/ricos`'s React `RicosViewer` as a client island because blog posts can carry the full Ricos feature set (galleries, polls, embedded media). For static CMS pages, that's ~80kb of React for paragraphs and lists — overkill. Use the seeded SSR walker instead.
+
+> **Do NOT `set:html={item.body}` directly.** That ships JSON-encoded text into the page (e.g. `[object Object]` or `{"nodes":...}`). Always go through `renderRicos`.
+
+> **Critical Rules — Read Before Starting**
+> 1. **Collection IDs have NO namespace** — user collections use just the name (e.g., `"Projects"`). Only Wix App collections use `<namespace>/<name>`. Verify via `curl`: `GET /wix-data/v2/collections?fields=id`.
+> 2. **SDK query pattern** — `items.query("CollectionId").find()`. There is no `items.queryDataItems()` in the SDK.
+> 3. **`auth.elevate` on every query** — without it, restricted collections silently return no items.
+> 4. **CMS only for user collections** — use `@wix/blog` for blog posts, `@wix/stores` for products, `@wix/forms` for form submissions.
+
+## Prerequisites (page-side)
+
+- `@wix/data` + `@wix/wix-data-items-sdk` + `@wix/essentials` installed (collected by SETUP.md Step 4c — do NOT install independently).
+- The collections + items already created and seeded by the `seed` scope (see `../../cms/CMS_FOUNDATIONS.md`). Pages only **read**.
+
+## Collection ID Format
+
+Native (user-created) CMS collections use **just the collection name** — no namespace prefix.
+
+Example: if the collection is called `Projects`, the collection ID is simply `"Projects"`.
+
+Only Wix App collections (e.g., `Members/PublicData`, `Locations/Locations`) use a `<namespace>/<name>` format. User-created collections never use a namespace.
+
+> **How to verify**: Call `GET /wix-data/v2/collections?fields=id` via `curl` (with the standard REST headers from `../../shared/AUTHENTICATION.md`) and use the exact `id` value from the response. Never guess — the dashboard name may differ from the ID.
+
+## Quick Reference — Inline Query (Simple Pages)
+
+For pages that just need to list items from a collection:
+
+```astro
+---
+import * as items from "@wix/wix-data-items-sdk";
+import { auth } from "@wix/essentials";
+
+// Always elevate queries for permission safety
+const elevatedQuery = auth.elevate(items.query);
+const { items: results } = await elevatedQuery("MyCollection")
+  .ascending("sortField")
+  .limit(50)
+  .find();
+
+// Fields are directly on each item (NOT item.data.field)
+const myItems = results.map((item) => ({
+  name: item.name,        // correct
+  // name: item.data.name  // wrong — REST pattern, not SDK
+}));
+---
+```
+
+> **Common mistake:** `items.queryDataItems(...)` does NOT exist in the
+> `@wix/data` SDK. The REST API uses `/items/query` with a `dataCollectionId`
+> body field, but the SDK uses `items.query("collectionId")` — a chainable
+> QueryBuilder. Do not confuse REST and SDK patterns.
+
+## Service Module Template
+
+Every CMS use case follows the same `src/lib/{usecase}.ts` pattern — a typed interface and query functions that pages import.
+
+```typescript
+import * as items from "@wix/wix-data-items-sdk";
+import { auth } from "@wix/essentials";
+import { media } from "@wix/sdk";
+
+// -- Collection ID (use exact name from Wix dashboard — no namespace for native collections) --
+const COLLECTION_ID = "collection-name";
+
+// -- Typed interface matching collection fields --
+export interface CollectionItem {
+  _id: string;
+  title: string;
+  slug: string;
+  // ...add fields matching your collection schema
+  coverImage?: string;
+}
+
+// -- Image resolution helper --
+function resolveImage(wixImageUrl: string | undefined, width = 800, height = 600): string | undefined {
+  if (!wixImageUrl) return undefined;
+  return media.getScaledToFillImageUrl(wixImageUrl, width, height, {});
+}
+
+// -- Query all items --
+// Wrap every Wix SDK await in try/catch. If the query throws at SSR, an empty
+// array keeps the page renderable instead of crashing it. (Unguarded SSR
+// awaits truncate Astro's response stream mid-body — nav renders, then blank.)
+export async function queryItems(): Promise<CollectionItem[]> {
+  try {
+    const elevatedQuery = auth.elevate(items.query);
+    const { items: results } = await elevatedQuery(COLLECTION_ID)
+      .ascending("orderIndex")
+      .limit(50)
+      .find();
+
+    return results.map((item) => ({
+      ...item,
+      coverImage: resolveImage(item.coverImage),
+    })) as CollectionItem[];
+  } catch (err) {
+    console.error(`[cms:${COLLECTION_ID}] query failed:`, err);
+    return [];
+  }
+}
+
+// -- Get single item by slug --
+export async function getItemBySlug(slug: string): Promise<CollectionItem | null> {
+  try {
+    const elevatedQuery = auth.elevate(items.query);
+    const { items: results } = await elevatedQuery(COLLECTION_ID)
+      .eq("slug", slug)
+      .limit(1)
+      .find();
+
+    const item = results[0];
+    if (!item) return null;
+
+    return {
+      ...item,
+      coverImage: resolveImage(item.coverImage),
+    } as CollectionItem;
+  } catch (err) {
+    console.error(`[cms:${COLLECTION_ID}] getItemBySlug failed:`, err);
+    return null;
+  }
+}
+```
+
+Key details:
+- `auth.elevate(items.query)` wraps the query for restricted collections — always use this by default since collection permissions vary
+- `media.getScaledToFillImageUrl(url, w, h, {})` resolves `wix:image://` URLs to sized CDN URLs
+- Sort by `orderIndex` (ascending) for manually ordered content, or `_createdDate` (descending) for chronological
+- The interface must match the collection fields — check the dashboard, don't guess
+
+## Multi-Image Resolution
+
+For collections with image arrays (e.g., gallery images):
+
+```typescript
+function resolveImages(imageUrls: string[] | undefined, width = 800, height = 600): string[] {
+  if (!imageUrls || imageUrls.length === 0) return [];
+  return imageUrls
+    .map((url) => media.getScaledToFillImageUrl(url, width, height, {}))
+    .filter(Boolean);
+}
+```
+
+## Category Filtering Pattern
+
+Many use cases filter by category via URL search params (server-rendered, no client JS):
+
+```astro
+---
+const activeCategory = Astro.url.searchParams.get("category");
+const allItems = await queryItems();
+const filtered = activeCategory
+  ? allItems.filter((item) => item.category === activeCategory)
+  : allItems;
+const categories = [...new Set(allItems.map((item) => item.category).filter(Boolean))];
+---
+
+<nav>
+  <a href="?" class:list={[!activeCategory && "active"]}>All</a>
+  {categories.map((cat) => (
+    <a
+      href={`?category=${encodeURIComponent(cat)}`}
+      class:list={[activeCategory === cat && "active"]}
+    >{cat}</a>
+  ))}
+</nav>
+```
+
+> **Styling note:** Category filter pill styling composes `@theme` tokens as Tailwind utilities at the call site — see `../../shared/STYLING.md`.
+
+## Testing
+
+1. Confirm the collection exists in the Wix dashboard → CMS (the `seed` scope created it — see `../../cms/CMS_FOUNDATIONS.md`).
+2. Run `npx @wix/cli@latest dev`.
+3. Navigate to the listing page — should show items.
+4. Click an item — should navigate to the detail page.

package/skills/wix-headless/references/{cms → astro/cms}/FAQ_KNOWLEDGE_BASE.md

@@ -2,7 +2,7 @@
 
 Build a FAQ page using `@wix/data` — Q&A pairs organized by category with accordion UI and client-side search. Use for frequently asked questions, help centers, or knowledge bases.
 
-> Read `CMS_FOUNDATIONS.md` first for shared patterns (service module, image resolution, elevation, MCP seeding).
+> Read `CMS_FOUNDATIONS.md` (this folder — service module, query patterns, image resolution, elevation) for page-rendering patterns, and `../../cms/CMS_FOUNDATIONS.md` for REST-based seeding.
 
 ## Collection Schema
 
@@ -180,6 +180,8 @@ Key details:
 
 ### 3. FAQ Page (`src/pages/faq/index.astro`)
 
+**Layout width:** Center the page column with `container-reading` (from designer `global.css`) or `max-w-6xl mx-auto px-lg` when `--container-6xl` exists in `@theme`. **Do not** use `max-w-3xl` unless `--container-3xl` is declared in `@theme` — with only a spacing scale, Tailwind maps `max-w-3xl` to ~5rem and the FAQ collapses to one word per line. See `references/shared/STYLING.md` § "Prose / reading width".
+
 ```astro
 ---
 import Layout from "../../layouts/Layout.astro";
@@ -193,7 +195,7 @@ const categories = [...grouped.entries()].map(([name, items]) => ({ name, items
 
 <Layout title="FAQ">
   <main>
-    <div>
+    <div class="container-reading px-lg">
       <h1>Frequently Asked Questions</h1>
       <p>Find answers to common questions below, or use the search to find what you need.</p>
 
@@ -222,8 +224,8 @@ Key details:
 
 1. Create a "FAQ" collection in the Wix dashboard → CMS with the schema above
 2. Add 6+ FAQ items across 2+ categories, all with `published: true`
-3. Run `npx @wix/cli dev`
+3. Run `npx @wix/cli@latest dev`
 4. `/faq` — shows all questions grouped by category
 5. Click a question — accordion opens with the answer
 6. Type in search — filters questions in real-time
-7. Click a category jump link — scrolls to that section
+7. Click a category jump link — scrolls to that section

package/skills/wix-headless/references/{cms → astro/cms}/PORTFOLIO.md

@@ -2,7 +2,7 @@
 
 Build a visual portfolio using `@wix/data` — project grid with category filtering, image galleries, and project detail pages. Use for work samples, case studies, creative projects, or any visual showcase.
 
-> Read `CMS_FOUNDATIONS.md` first for shared patterns (service module, image resolution, elevation, MCP seeding).
+> Read `CMS_FOUNDATIONS.md` (this folder — service module, query patterns, image resolution, elevation) for page-rendering patterns, and `../../cms/CMS_FOUNDATIONS.md` for REST-based seeding.
 
 ## Collection Schema
 
@@ -410,7 +410,7 @@ const featured = await queryFeaturedProjects(3);
 
 ## Seed with Images
 
-After seeding projects via MCP, generate cover images (and optionally gallery images) following `../../shared/IMAGE_GENERATION.md` and `CMS_FOUNDATIONS.md` → "MCP Seeding with Images".
+After seeding projects via REST, generate cover images (and optionally gallery images) following `../../shared/IMAGE_GENERATION.md` and `../../cms/CMS_FOUNDATIONS.md` → "Seeding with Images".
 
 **Cover image prompt template:**
 
@@ -431,7 +431,7 @@ Gallery image [N] for [TITLE]: [describe a specific aspect/angle of the project]
 Example patch:
 
 ```
-CallWixSiteAPI: PATCH /wix-data/v2/items/{projectId}
+REST: PATCH https://www.wixapis.com/wix-data/v2/items/{projectId}
 body: {
   "dataCollectionId": "Projects",
   "dataItem": {
@@ -448,7 +448,7 @@ body: {
 1. Create a "Projects" collection in the Wix dashboard → CMS with the schema above
 2. Add 3+ projects with cover images, categories, and at least one with gallery images
 3. Mark 1–2 as `featured: true`
-4. Run `npx @wix/cli dev`
+4. Run `npx @wix/cli@latest dev`
 5. `/work` — grid with category filter tabs
 6. Click a category — filters projects
-7. Click a project — detail page with gallery lightbox
+7. Click a project — detail page with gallery lightbox

package/skills/wix-headless/references/{cms → astro/cms}/RESOURCE_LIBRARY.md

@@ -2,7 +2,7 @@
 
 Build a downloadable resource library using `@wix/data` — file listings with category filtering, file type badges, and detail pages with download buttons. Use for documents, guides, templates, whitepapers, or any downloadable assets.
 
-> Read `CMS_FOUNDATIONS.md` first for shared patterns (service module, image resolution, elevation, MCP seeding).
+> Read `CMS_FOUNDATIONS.md` (this folder — service module, query patterns, image resolution, elevation) for page-rendering patterns, and `../../cms/CMS_FOUNDATIONS.md` for REST-based seeding.
 
 ## Collection Schema
 
@@ -321,7 +321,7 @@ Key details:
 
 ## Seed with Images
 
-After seeding resources via MCP, generate cover images following `../../shared/IMAGE_GENERATION.md` and `CMS_FOUNDATIONS.md` → "MCP Seeding with Images".
+After seeding resources via REST, generate cover images following `../../shared/IMAGE_GENERATION.md` and `../../cms/CMS_FOUNDATIONS.md` → "Seeding with Images".
 
 **Prompt template:**
 
@@ -334,7 +334,7 @@ Cover image for [TITLE], a [FILE TYPE]. Abstract [BRAND AESTHETIC]. Color tones:
 Example patch:
 
 ```
-CallWixSiteAPI: PATCH /wix-data/v2/items/{resourceId}
+REST: PATCH https://www.wixapis.com/wix-data/v2/items/{resourceId}
 body: {
   "dataCollectionId": "Resources",
   "dataItem": {
@@ -350,7 +350,7 @@ body: {
 1. Create a "Resources" collection in the Wix dashboard → CMS with the schema above
 2. Add 4+ resources across 2+ categories with different file types (PDF, DOC, ZIP)
 3. Include `fileUrl` links (can be any downloadable URL for testing)
-4. Run `npx @wix/cli dev`
+4. Run `npx @wix/cli@latest dev`
 5. `/resources` — shows all resources with category filters and file type badges
 6. Click a category — filters resources
-7. Click a resource — detail page with download button and related resources
+7. Click a resource — detail page with download button and related resources

package/skills/wix-headless/references/{cms → astro/cms}/TEAM_DIRECTORY.md

@@ -2,7 +2,7 @@
 
 Build a team directory using `@wix/data` — staff cards grouped by department with individual profile pages. Use for about us, our team, meet the staff, or any people directory.
 
-> Read `CMS_FOUNDATIONS.md` first for shared patterns (service module, image resolution, elevation, MCP seeding).
+> Read `CMS_FOUNDATIONS.md` (this folder — service module, query patterns, image resolution, elevation) for page-rendering patterns, and `../../cms/CMS_FOUNDATIONS.md` for REST-based seeding.
 
 ## Collection Schema
 
@@ -266,7 +266,7 @@ if (!member) return Astro.redirect("/404");
 > **Do not skip:** Team members without photos appear as initial-letter placeholders.
 > Always ask the user if they want to generate headshot images before moving on.
 
-After seeding team members via MCP, generate headshot images following `../../shared/IMAGE_GENERATION.md` and `CMS_FOUNDATIONS.md` → "MCP Seeding with Images".
+After seeding team members via REST, generate headshot images following `../../shared/IMAGE_GENERATION.md` and `../../cms/CMS_FOUNDATIONS.md` → "Seeding with Images".
 
 **Prompt template:**
 
@@ -279,7 +279,7 @@ Professional headshot portrait of [NAME], [ROLE] at [BUSINESS NAME]. [BRAND AEST
 Example: after generating and importing the image, patch the team member item:
 
 ```
-CallWixSiteAPI: PATCH /wix-data/v2/items/{memberId}
+REST: PATCH https://www.wixapis.com/wix-data/v2/items/{memberId}
 body: {
   "dataCollectionId": "Team",
   "dataItem": {
@@ -294,6 +294,6 @@ body: {
 
 1. Create a "Team" collection in the Wix dashboard → CMS with the schema above
 2. Add 4+ members across 2+ departments, with photos and social links
-3. Run `npx @wix/cli dev`
+3. Run `npx @wix/cli@latest dev`
 4. `/team` — shows members grouped by department
-5. Click a member — profile page with photo, bio, and social links
+5. Click a member — profile page with photo, bio, and social links