@wix/agent-skills 1.14.0 → 1.15.1

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

@@ -1,77 +0,0 @@
-# Bookings Pages — the SSR routes (astro)
-
-The `pages` scope of the bookings vertical. You write the route files. The
-**logic** is in `../../bookings/FLOW.md` (read it first); this doc is the astro
-wiring + the gotchas. Read `references/shared/IMPLEMENTER.md` +
-`references/shared/STYLING.md` first.
-
-> **Start from the templates — don't re-author the SSR data access.** Examples at
-> `<SKILL_ROOT>/references/astro/templates/bookings/`: `ServiceCard.astro`,
-> `services/index.astro`, `services/[slug].astro`, `booking-confirmation.astro`.
-> Read and adapt (copy, headings, styling); keep the SDK query shapes.
-
-## Pages you write
-
-| File | From template | Role |
-|------|---------------|------|
-| `src/pages/services/index.astro` | `…/services/index.astro` | SSR catalog grid (SEO). `queryServices` via ambient `@wix/essentials`. |
-| `src/components/ServiceCard.astro` | `…/ServiceCard.astro` | static service card for the grid. |
-| `src/pages/services/[slug].astro` | `…/services/[slug].astro` | SSR detail (SEO) + mounts `<ServiceBookingFlow client:only="react">`. Also fetches the **booking-form schema** and passes `fields` to the island. |
-| `src/pages/booking-confirmation.astro` | `…/booking-confirmation.astro` | confirmation — renders from the `service`/`startDate` query params (no re-fetch). |
-
-Plus the nav/home links (shell chain — see below).
-
-## astro-specific rules
-
-1. **SSR reads use the ambient `@wix/essentials` client — never `OAuthStrategy`.**
-   `const result = await auth.elevate(services.queryServices)({ query: { filter: { appId: BOOKING_APP_ID }, paging: { limit: 100 } }, conditionalFields: ["STAFF_MEMBER_DETAILS"] }).find();`
-   Building `createClient({ auth: OAuthStrategy({ clientId: import.meta.env.* }) })`
-   in frontmatter 500s in the deployed runtime (the env var is client-only).
-   Always include **`appId`** in the filter. Single service by slug: the
-   `.eq("mainSlug.name", slug).eq("appId", BOOKING_APP_ID).limit(1).find()` chain.
-   The same elevation works for `services.queryLocations` and
-   `categoriesV2.queryCategories` (used by the optional catalog filters, below).
-1b. **Optional catalog filters (location + category) — auto-skip; see `../../bookings/FLOW.md` §7.**
-   The catalog page reads `?locationId`/`?category` from the request URL and merges
-   them into the **same** `queryServices` filter (location → `locations.business.id`
-   $hasSome, or the synthetic `locations.type` mapping; category → `category.id` $eq).
-   It SSRs `queryLocations()` (show the selector only when business+custom+customer
-   count > 1) and `queryCategories().find()` (non-fatal — render without the bar on
-   failure; show only when > 1 category). The chosen location is carried into the
-   detail link (`ServiceCard` `locationId`/`locationType` props) so availability is
-   scoped to it. Reference: `…/templates/bookings/services/index.astro`.
-2. **The detail page fetches the booking-form schema server-side.** Read
-   `service.form._id`'s form via `@wix/forms` (`auth.elevate(forms.getForm)(formId)`),
-   map `formFields` to `{ label, target, required, componentType, identifier, options }`,
-   and pass the array as `fields` into `<ServiceBookingFlow>`. **Filter to fields with a
-   recognized string `componentType`** (`TEXT_INPUT`/`PHONE_INPUT`/`DROPDOWN`) — skip
-   complex object-valued fields (e.g. the default form's multi-line `ADDRESS`), or
-   `createBooking` fails with "must be object". Pass the full `service` too — the
-   booking step reads its payment/policy. Same field-mapping as `../forms/CONTACT_FORM.md`.
-   Also pass, through to `<ServiceBookingFlow>`: `service.staffMemberDetails?.staffMembers`
-   (the staff picker — the service was queried with `STAFF_MEMBER_DETAILS`); the
-   service's **business `locations`** — sourced from `auth.elevate(services.queryLocations)()`
-   (the site's real business locations) intersected with the service's own location ids,
-   NOT from `service.locations` alone (its ids can be ones the availability engine doesn't
-   recognize → 0 slots) — so the calendar scopes availability to one location and avoids
-   duplicate per-location slots (FLOW.md §7); and the `?locationId` read from the request
-   URL (the picker's default).
-3. **Only the read pages are SSR.** The detail page SSRs the service info for SEO,
-   then the booking UI runs in the `client:only` island. Do not SSR availability.
-4. **Confirmation renders from query params.** The booking step redirects with
-   `?service=…&startDate=…`; render those. Do not re-fetch a stranger's booking
-   from this public page.
-5. **Two dirs deep** (`services/[slug].astro`) → import with `../../`, not `../../../`.
-
-## Shell chain — nav + home (this scope patches shared files)
-
-- **Navigation** — at `<!-- nav:links -->` in `src/components/Navigation.astro`,
-  append a link to **`/services`** (label fitting the brand: "Book", "Services", "Appointments").
-- **Home** — at `<!-- home:bookings -->` in `src/pages/index.astro`, add a short,
-  brand-voiced CTA linking to **`/services`** (heading + a line + a button-styled
-  link). Use the site's primary-action token (`--color-accent`). Do not list
-  specific services or hardcode slugs — the catalog renders them live.
-- Append at the markers; keep the markers; never replace other packs' insertions.
-
-## Return
-`{ status, phase, scope: "pages", summary, data, files, errors }`. Run the pre-return file-existence assertion (`../../bookings/INSTRUCTIONS.md`). If `index.astro`/`Navigation.astro` lacks its marker, return `status: "partial"` with the coded error.

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

@@ -1,214 +0,0 @@
-# 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).** The Wix Data items API is the **`items`** named export of **`@wix/data`**: `import { items } from "@wix/data"`, then `items.query` / `items.insert` / `items.update` / `items.remove` (plus `items.bulkInsert` / `bulkSave` / `bulkPatch` / …). This is the documented form and what every CMS page here uses. Do **not** import from the internal `@wix/wix-data-items-sdk`. SETUP.md's per-pack install table (Step 4c) installs `@wix/data` + `@wix/essentials` for the cms pack.
-
-## 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 { items } from "@wix/data";
-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/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 { items } from "@wix/data";
-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 { items } from "@wix/data";
-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/astro/cms/FAQ_KNOWLEDGE_BASE.md

@@ -1,231 +0,0 @@
-# Recipe: FAQ / Knowledge Base
-
-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` (this folder — service module, query patterns, image resolution, elevation) for page-rendering patterns, and `../../cms/CMS_FOUNDATIONS.md` for REST-based seeding.
-
-## Collection Schema
-
-The schema the `seed` scope creates via REST (see `../../cms/CMS_FOUNDATIONS.md`) — fields:
-
-| Field | Type | Purpose |
-|-------|------|---------|
-| `question` | Text | The question |
-| `slug` | Text | URL-friendly identifier (for anchor links) |
-| `answer` | Rich Text | The answer (HTML) |
-| `category` | Text | FAQ category (e.g., "Shipping", "Returns") |
-| `orderIndex` | Number | Manual sort order within category |
-| `published` | Boolean | Publish status |
-
-## Files to Create
-
-| File | Purpose |
-|------|---------|
-| `src/lib/faq.ts` | Service module — queries, category grouping |
-| `src/pages/faq/index.astro` | Single FAQ page with category sections |
-| `src/components/FaqSection.tsx` | React island — accordion + search combined |
-
-> FAQ is a single-page pattern — no detail pages needed.
-
-## Implementation
-
-### 1. FAQ Service Module (`src/lib/faq.ts`)
-
-```typescript
-import { items } from "@wix/data";
-import { auth } from "@wix/essentials";
-
-const COLLECTION_ID = "FAQ";
-
-export interface FaqItem {
-  _id: string;
-  question: string;
-  slug: string;
-  answer: string;
-  category: string;
-  orderIndex: number;
-}
-
-function mapFaqItem(item: Record<string, any>): FaqItem {
-  return {
-    _id: item._id,
-    question: item.question ?? "",
-    slug: item.slug ?? "",
-    answer: item.answer ?? "",
-    category: item.category ?? "General",
-    orderIndex: item.orderIndex ?? 0,
-  };
-}
-
-export async function queryFaqItems(): Promise<FaqItem[]> {
-  const elevatedQuery = auth.elevate(items.query);
-  const { items: results } = await elevatedQuery(COLLECTION_ID)
-    .eq("published", true)
-    .ascending("orderIndex")
-    .limit(200)
-    .find();
-
-  return results.map(mapFaqItem);
-}
-
-export function groupByCategory(faqItems: FaqItem[]): Map<string, FaqItem[]> {
-  return faqItems.reduce((map, item) => {
-    const cat = item.category || "General";
-    if (!map.has(cat)) map.set(cat, []);
-    map.get(cat)!.push(item);
-    return map;
-  }, new Map<string, FaqItem[]>());
-}
-```
-
-Key details:
-- No image resolution needed — FAQ items are text-only
-- `published` filter ensures draft items don't appear
-- Higher limit (200) since FAQ items are lightweight
-- Update `COLLECTION_ID` to match the exact collection name from the Wix dashboard (no namespace prefix for native collections)
-
-### 2. FAQ Section React Island (`src/components/FaqSection.tsx`)
-
-```tsx
-import { useState } from "react";
-
-interface FaqItem {
-  _id: string;
-  question: string;
-  slug: string;
-  answer: string;
-  category: string;
-}
-
-interface Props {
-  categories: Array<{ name: string; items: FaqItem[] }>;
-}
-
-export default function FaqSection({ categories }: Props) {
-  const [search, setSearch] = useState("");
-  const query = search.toLowerCase().trim();
-
-  const filtered = query
-    ? categories
-        .map((cat) => ({
-          ...cat,
-          items: cat.items.filter(
-            (item) =>
-              item.question.toLowerCase().includes(query) ||
-              item.answer.toLowerCase().includes(query)
-          ),
-        }))
-        .filter((cat) => cat.items.length > 0)
-    : categories;
-
-  return (
-    <div>
-      <div>
-        <input
-          type="text"
-          placeholder="Search questions..."
-          value={search}
-          onChange={(e) => setSearch(e.target.value)}
-          className="faq-search"
-        />
-      </div>
-
-      {filtered.length === 0 && (
-        <p>No matching questions found.</p>
-      )}
-
-      {filtered.map((cat) => (
-        <section key={cat.name} className="faq-section" id={cat.name.toLowerCase().replace(/\s+/g, "-")}>
-          <h2 className="faq-category">{cat.name}</h2>
-          <div>
-            {cat.items.map((item) => (
-              <details key={item._id} className="faq-item" id={item.slug}>
-                <summary className="faq-question">
-                  <span>{item.question}</span>
-                  <svg
-                    className="faq-toggle"
-                    xmlns="http://www.w3.org/2000/svg"
-                    viewBox="0 0 24 24"
-                    fill="none"
-                    stroke="currentColor"
-                    strokeWidth="2"
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                  >
-                    <polyline points="6 9 12 15 18 9" />
-                  </svg>
-                </summary>
-                <div
-                  className="faq-answer"
-                  dangerouslySetInnerHTML={{ __html: item.answer }}
-                />
-              </details>
-            ))}
-          </div>
-        </section>
-      ))}
-    </div>
-  );
-}
-```
-
-> **Styling note:** Uses `.faq-search`, `.faq-section`, `.faq-category`, `.faq-item`, `.faq-question`, `.faq-toggle`, `.faq-answer` from the designed component's `<style is:global>` block. See `references/shared/STYLING.md` (FAQ Accordion).
-
-Key details:
-- `<details>/<summary>` for native accordion behavior — no JavaScript needed for open/close
-- CSS transition on the chevron via the `.faq-toggle` class
-- Client-side search filters across both question and answer text
-- `dangerouslySetInnerHTML` for rich text answers (content is from the CMS, not user input)
-- Anchor `id` on each category section and question for direct linking
-
-### 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-6` 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";
-import FaqSection from "../../components/FaqSection";
-import { queryFaqItems, groupByCategory } from "../../lib/faq";
-
-const faqItems = await queryFaqItems();
-const grouped = groupByCategory(faqItems);
-const categories = [...grouped.entries()].map(([name, items]) => ({ name, items }));
----
-
-<Layout title="FAQ">
-  <main>
-    <div class="container-reading px-6">
-      <h1>Frequently Asked Questions</h1>
-      <p>Find answers to common questions below, or use the search to find what you need.</p>
-
-      {categories.length > 1 && (
-        <nav>
-          {categories.map((cat) => (
-            <a
-              href={`#${cat.name.toLowerCase().replace(/\s+/g, "-")}`}
-            >{cat.name}</a>
-          ))}
-        </nav>
-      )}
-
-      <FaqSection client:only="react" categories={categories} />
-    </div>
-  </main>
-</Layout>
-```
-
-Key details:
-- Category jump links in the nav work because `FaqSection` renders matching `id` attributes
-- `client:only="react"` — required for search state
-- Data is fetched server-side and passed as props to the React island
-
-## Testing
-
-Assumes the `seed` scope has already created the "FAQ" collection and inserted items via REST (see `../../cms/CMS_FOUNDATIONS.md`) — with 6+ FAQ items across 2+ categories, all `published: true`.
-
-1. Run `npx @wix/cli@latest dev`
-2. `/faq` — shows all questions grouped by category
-3. Click a question — accordion opens with the answer
-4. Type in search — filters questions in real-time
-5. Click a category jump link — scrolls to that section