@wix/agent-skills 1.7.0 → 1.8.0

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

@@ -0,0 +1,428 @@
+# Bookings Pages — Phase 4
+
+You are the Phase 4 Pages agent for the bookings vertical. Your scope: write the route files. Read `references/shared/IMPLEMENTER.md` + `references/shared/STYLING.md` first.
+
+> **Start from the canonical templates — don't invent the SSR data access.** Verified templates live at `<SKILL_ROOT>/references/astro/templates/bookings/`: `services/index.astro`, `services/[slug].astro`, `booking-confirmation.astro`, `manage-booking.astro` (plus the pre-copied API endpoints `api/confirm-booking.ts`, `api/waitlist.ts`). **Read and adapt them** (copy, headings, styling) — this doc explains the *why*. The SSR query pattern (`@wix/essentials` `auth.elevate`), the confirm step, and the manage/waitlist endpoints are live-verified.
+
+---
+
+## Files you own
+
+| File | Route | Description |
+|------|-------|-------------|
+| `src/pages/services/index.astro` | `/services` | SSR services listing grid |
+| `src/pages/services/[slug].astro` | `/services/[slug]` | SSR service detail + client-side booking flow |
+| `src/pages/booking-confirmation.astro` | `/booking-confirmation` | Status-aware confirmation + inline cancel |
+| `src/pages/manage-booking.astro` | `/manage-booking` | Per-booking view/cancel (anonymous token) |
+
+---
+
+## Step 1 — Read your seeded slice
+
+Read your `seeded.bookings` slice from **`.wix/seeded.json`** (written once by the orchestrator at the seed gate — see `BUILD-astro.md` § "The `.wix/seeded.json` handoff"): `services[{id, slug, name, type, durationMinutes, price, currency}]` + `staff[{id, resourceId, name}]`. Use it to know the seeded slugs/names/types while authoring — do **NOT** import it into route files; the pages query the **live SDK** at request time (below). If your slice is absent, fail loud (`status: "partial"`, `errors: [{code: "SEEDED_JSON_SLICE_MISSING", missing: "seeded.bookings"}]`) — do not render an empty page.
+
+---
+
+## Page 1 — `/services/index.astro`
+
+### Frontmatter
+
+```typescript
+---
+import Layout from '../../layouts/Layout.astro';
+import ServiceCard from '../../components/ServiceCard.astro';
+import { services } from '@wix/bookings';
+import { auth } from '@wix/essentials';
+
+// SSR data access: use the ambient @wix/astro server client via @wix/essentials —
+// the SAME pattern the CMS pages use (`auth.elevate(fn)` + a direct module import).
+// Do NOT build a `createClient`/`OAuthStrategy` here keyed off `import.meta.env`:
+// the `*_WIX_CLIENT_ID` env vars are CLIENT-only in @wix/astro and `undefined`
+// during server render, so `createClient`/`OAuthStrategy` throws and the page
+// returns HTTP 500 in production. (It "works" in `astro dev` only because
+// `.env.local` is loaded there — the 500 surfaces only in the deployed runtime.)
+// Client-side islands access the ID differently — see COMPONENTS.md (`astro:env/client`).
+let serviceList: any[] = [];
+try {
+  // queryServices uses the QUERY BUILDER, then `.find()` — NOT a
+  // `{ query: { filter, paging } }` object. In @wix/bookings the object form
+  // returns ZERO items with no error; the builder is what actually queries.
+  const result = await auth.elevate(services.queryServices)()
+    .limit(100)
+    .find();
+  // Exclude hidden services from the public listing (filter in JS — robust
+  // regardless of whether `hidden` is a queryable builder field).
+  serviceList = (result.items ?? []).filter((s: any) => !s.hidden);
+} catch (err) {
+  console.error('[services] query failed:', err);
+}
+
+// Services V2: slug lives at service.mainSlug.name. ID is service._id (underscore).
+const getSlug = (service: any): string =>
+  service.mainSlug?.name ??
+  service.supportedSlugs?.[0]?.name ??
+  service._id; // fallback to ID if slug is absent
+
+// Services V2: price uses `value` (string), not `amount`
+const formatPrice = (service: any): string | undefined => {
+  const payment = service.payment;
+  if (!payment || payment.rateType === 'NO_FEE') return undefined;
+  if (payment.rateType === 'FIXED' && payment.fixed?.price) {
+    const { value, currency } = payment.fixed.price;
+    if (!value) return undefined;
+    return new Intl.NumberFormat('en-US', { style: 'currency', currency: currency ?? 'USD' }).format(Number(value));
+  }
+  return undefined;
+};
+
+// Duration: lives at service.schedule.availabilityConstraints.sessionDurations[0]
+const getDuration = (service: any): number =>
+  service.schedule?.availabilityConstraints?.sessionDurations?.[0] ?? 60;
+---
+```
+
+### Template
+
+```astro
+<Layout title="Services">
+  <main class="py-4xl">
+    <section class="container mx-auto px-lg">
+      <header class="mb-3xl">
+        <h1 class="font-display text-4xl mb-sm">Our Services</h1>
+        <!-- Optional tagline from brand -->
+      </header>
+
+      {serviceList.length === 0 ? (
+        <p class="text-secondary">Services coming soon — check back shortly.</p>
+      ) : (
+        <div class="service-grid">
+          {serviceList.map((service) => (
+            <ServiceCard
+              id={service._id}
+              slug={getSlug(service)}
+              name={service.name ?? 'Untitled'}
+              tagLine={service.tagLine}
+              durationMinutes={getDuration(service)}
+              price={formatPrice(service)}
+              imageUrl={service.media?.mainMedia?.image?.url ?? service.media?.items?.[0]?.image?.url}
+              type={service.type ?? 'APPOINTMENT'}
+            />
+          ))}
+        </div>
+      )}
+    </section>
+  </main>
+</Layout>
+```
+
+---
+
+## Page 2 — `/services/[slug].astro`
+
+### Frontmatter
+
+```typescript
+---
+// File is at src/pages/services/[slug].astro
+// ../../ from src/pages/services/ → src/
+import Layout from '../../layouts/Layout.astro';
+import ServiceBookingFlow from '../../components/ServiceBookingFlow';
+import { services } from '@wix/bookings';
+import { auth } from '@wix/essentials';
+
+const { slug } = Astro.params;
+
+// SSR via @wix/essentials — same ambient pattern as the listing page above and
+// the CMS pages. No createClient/OAuthStrategy, no import.meta.env (those 500 at
+// server render — see the listing-page note).
+let service: any = null;
+try {
+  // Query builder + `.find()` (the object form returns 0 items). Fetch the small
+  // catalog and match the slug in JS — robust without relying on a nested-field
+  // (`mainSlug.name`) builder filter.
+  const result = await auth.elevate(services.queryServices)()
+    .limit(100)
+    .find();
+  service =
+    (result.items ?? []).find(
+      (s: any) => (s.mainSlug?.name ?? s.supportedSlugs?.[0]?.name) === slug,
+    ) ?? null;
+} catch (err) {
+  console.error(`[services/${slug}] query failed:`, err);
+}
+
+if (!service) {
+  return Astro.redirect('/services', 302);
+}
+
+// Services V2: flat fields — `name`, `tagLine`, not `info.name`, `info.tagLine`
+// Price uses `value` (string), not `amount`
+const formatPrice = (payment: any): string | undefined => {
+  if (!payment || payment.rateType === 'NO_FEE') return undefined;
+  if (payment.rateType === 'FIXED' && payment.fixed?.price) {
+    const { value, currency } = payment.fixed.price;
+    if (!value) return undefined;
+    return new Intl.NumberFormat('en-US', { style: 'currency', currency: currency ?? 'USD' }).format(Number(value));
+  }
+  return undefined;
+};
+
+const price = formatPrice(service.payment);
+// Duration: service.schedule.availabilityConstraints.sessionDurations[0]
+const duration = service.schedule?.availabilityConstraints?.sessionDurations?.[0] ?? 60;
+// Media: service.media.mainMedia.image.url (V2 shape)
+const imageUrl = service.media?.mainMedia?.image?.url ?? service.media?.items?.[0]?.image?.url;
+---
+```
+
+### Template
+
+```astro
+<!--
+  Width: use `container-reading` (max-width: var(--container-prose) + auto margins),
+  NOT a bare `max-w-<size>`. In this Tailwind v4 setup any `max-w-<size>` whose key
+  the Composer didn't emit in @theme `--container-*` silently falls back to the
+  `--spacing-*` scale — e.g. `max-w-4xl` → ~7rem, a ~112px column (one word per line).
+  `container-reading` is a project-owned utility that always resolves. See STYLING.md.
+-->
+<Layout title={service.name ?? 'Service'}>
+  <main class="py-4xl">
+    <div class="container-reading px-lg">
+      <!-- Back link -->
+      <a href="/services" class="text-secondary hover:text-primary text-sm mb-xl block">
+        ← All Services
+      </a>
+
+      <!-- Optional banner image — render ONLY when the service has media. The
+           default seed is text-only, so most services have no image; rendering a
+           fixed-ratio placeholder there collapses to a thin bar and crowds the
+           text. Single full-width column when image-less. -->
+      {imageUrl && (
+        <img src={imageUrl} alt={service.name} class="w-full h-64 object-cover rounded-lg mb-xl" />
+      )}
+
+      <!-- Service hero — single column -->
+      <div class="flex flex-col gap-md mb-3xl">
+        {/* V2 flat fields: name, tagLine, description (not info.name etc.) */}
+        <h1 class="font-display text-4xl">{service.name}</h1>
+        {service.tagLine && (
+          <p class="text-secondary text-lg">{service.tagLine}</p>
+        )}
+        <div class="flex gap-md items-center text-sm">
+          <span class="font-medium">{duration} min</span>
+          {price && <span class="text-primary font-bold text-lg">{price}</span>}
+        </div>
+        {service.description && (
+          <p class="text-base leading-relaxed">{service.description}</p>
+        )}
+      </div>
+
+      <!-- Booking flow — client-side islands -->
+      <section class="border-t border-[--color-border] pt-2xl">
+        <h2 class="font-display text-2xl mb-xl">Book This Service</h2>
+        <ServiceBookingFlow
+          serviceId={service._id}
+          serviceName={service.name ?? 'this service'}
+          serviceType={service.type ?? 'APPOINTMENT'}
+          client:only="react"
+        />
+      </section>
+    </div>
+  </main>
+</Layout>
+```
+
+### ServiceBookingFlow coordinator
+
+Because `AvailabilityCalendar` and `BookingForm` share state (the selected slot) and need to transition between each other, write a thin coordinator island `ServiceBookingFlow.tsx` that manages this state:
+
+```typescript
+// src/components/ServiceBookingFlow.tsx
+import { useState } from 'react';
+import AvailabilityCalendar from './AvailabilityCalendar';
+import BookingForm from './BookingForm';
+
+interface Props {
+  serviceId: string;
+  serviceName: string;
+  serviceType: 'APPOINTMENT' | 'CLASS';  // threaded into both islands
+}
+
+export default function ServiceBookingFlow({ serviceId, serviceName, serviceType }: Props) {
+  const [selectedSlot, setSelectedSlot] = useState<any>(null);
+
+  const handleSuccess = (bookingId: string, startDate?: string) => {
+    const params = new URLSearchParams({ bookingId });
+    if (startDate) params.set('startDate', startDate);
+    if (serviceName) params.set('service', serviceName);
+    window.location.href = `/booking-confirmation?${params.toString()}`;
+  };
+
+  if (!selectedSlot) {
+    return (
+      <AvailabilityCalendar
+        serviceId={serviceId}
+        serviceName={serviceName}
+        serviceType={serviceType}
+        onSlotSelected={setSelectedSlot}
+      />
+    );
+  }
+
+  return (
+    <BookingForm
+      serviceId={serviceId}
+      serviceName={serviceName}
+      serviceType={serviceType}
+      slot={selectedSlot}
+      onSuccess={handleSuccess}
+      onCancel={() => setSelectedSlot(null)}
+    />
+  );
+}
+```
+
+Add `ServiceBookingFlow` to the files you own and include it in your pre-return assertion.
+
+---
+
+## Page 3 — `/booking-confirmation.astro`
+
+### Behavior — show the real status + cancel inline
+
+The confirmation page **re-fetches the booking** to show its **actual status** (`CONFIRMED` vs `PENDING` approval) — so the user sees whether the booking was approved, not just an optimistic "you're booked" — and embeds the cancel action. It re-uses the **anonymous-action-token** flow: the server elevates (app identity) to mint a per-booking token (`getAnonymousActionToken`), then reads it with the no-auth `bookingsGetBookingAnonymously`, falling back to the redirect params (`?bookingId=...&startDate=...&service=...`) if the lookup fails. Cancel is the same `<ManageBooking>` island used by `/manage-booking` (pass `showSummary={false}` to avoid duplicating the headline). See the canonical template `booking-confirmation.astro`.
+
+```typescript
+// frontmatter (essentials):
+const bookingId = Astro.url.searchParams.get('bookingId');
+const { token } = bookingId ? await auth.elevate(bookings.getAnonymousActionToken)(bookingId) : { token: null };
+const { booking, allowedAnonymousActions } = token ? await bookings.bookingsGetBookingAnonymously(token) : {};
+const status = booking?.status ?? null;            // CONFIRMED | PENDING | …
+const isPending = status === 'PENDING' || status === 'PENDING_APPROVAL';
+// Render: "You're booked / confirmed" vs "Booking received — awaiting confirmation" by status,
+// a Status badge, and <ManageBooking … canCancel={!!allowedAnonymousActions?.cancel} showSummary={false} />.
+```
+
+> **Two different `elevate`s, don't conflate them:** `@wix/essentials` `auth.elevate(fn)` works in `@wix/astro` SSR (used here to mint the token and across the listing/detail/CMS pages); the unavailable one is `wixClient.auth.elevate` (the instance method on a hand-built `createClient({ auth: OAuthStrategy(...) })`).
+
+### Template
+
+Use the canonical template verbatim and adapt copy/styling: `<SKILL_ROOT>/references/astro/templates/bookings/booking-confirmation.astro`. It renders a status-aware headline ("You're booked / confirmed" vs "Booking received — awaiting confirmation"), a Status badge, and the embedded `<ManageBooking … showSummary={false} />` cancel — wrapped in `max-w-prose` (a built-in literal; never a bare `max-w-<size>`, which can fall through to the spacing scale).
+
+---
+
+## Server endpoints + manage-booking page (verified live)
+
+Some bookings operations require **Manage Bookings** scope and so **cannot** run from the browser `OAuthStrategy` client — they must be Astro **API routes** (`output: "server"`) that elevate to app identity. Elevation rule (important): `auth.elevate()` only grants permissions for a real **SDK function**; for raw REST with no SDK wrapper, elevate the authenticated fetch itself.
+
+### `src/pages/api/confirm-booking.ts` — hold the seat (always, for create flows)
+`createBooking` returns `CREATED`, which holds nothing. Confirm to occupy the seat + validate availability:
+```typescript
+import { auth } from "@wix/essentials";
+import { bookings } from "@wix/bookings";
+// POST { bookingId, revision }
+await auth.elevate(bookings.confirmBooking)(bookingId, String(revision), {
+  paymentStatus: "NOT_PAID",
+  flowControlSettings: { checkAvailabilityValidation: true },
+});
+```
+
+### `src/pages/api/waitlist.ts` — native waitlist (v1; no v2/v3 exists)
+Register on the native waitlist when a session is full. Resolve a `contactId` (Contacts API, by email → create if missing), then `POST /bookings/v1/waitlist/register`. All via the **elevated authenticated fetch** (raw REST, so elevate `fetchWithAuth`, not a closure):
+```typescript
+import { auth, httpClient } from "@wix/essentials";
+const ef = auth.elevate(httpClient.fetchWithAuth as typeof fetch) as typeof fetch;
+const api = (url: string, body: unknown) =>
+  ef(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+
+// 1. contactId — query then create
+let contactId = (await (await api("https://www.wixapis.com/contacts/v4/contacts/query",
+  { query: { filter: { "info.emails.email": email } } })).json()).contacts?.[0]?.id;
+if (!contactId) contactId = (await (await api("https://www.wixapis.com/contacts/v4/contacts",
+  { info: { name: { first }, emails: { items: [{ email, primary: true }] } } })).json()).contact?.id;
+
+// 2. register — waitingResource is the v1 session id from the SESSION_CAPACITY_EXCEEDED message
+await api("https://www.wixapis.com/bookings/v1/waitlist/register", {
+  waitingResource: sessionId,
+  formInfo: {
+    paymentSelection: [{ rateLabel: "general", numberOfParticipants: totalParticipants }],
+    contactDetails: { contactId, firstName: first, email },
+  },
+});
+```
+
+### `src/pages/manage-booking.astro` + `ManageBooking.tsx` — view/cancel (anonymous-token flow)
+A plain visitor token can't list/cancel bookings (`queryExtendedBookings`/`cancelBooking` are APP/MEMBER only). The supported visitor path is the **anonymous action token**: the page (SSR) elevates to **mint** a per-booking token, then the no-auth anonymous methods act on it (the token can safely go to the browser):
+```typescript
+// manage-booking.astro frontmatter — bookingId from ?bookingId=
+const { token } = await auth.elevate(bookings.getAnonymousActionToken)(bookingId);   // APP identity → elevate
+const { booking, allowedAnonymousActions } = await bookings.bookingsGetBookingAnonymously(token); // no auth
+// Pass token + booking.revision + allowedAnonymousActions.cancel to a <ManageBooking client:only> island.
+```
+In the island (no-auth, visitor client OK):
+```typescript
+await wixClient.bookings.bookingsCancelBookingAnonymously(token, revision); // cancel
+```
+Reschedule-in-place uses `bookingsRescheduleBookingAnonymously(token, slot, { revision })`, but the CLASS `V2Slot` shape isn't fully pinned — prefer **cancel-and-rebook** (link to the service) unless you've verified the class slot shape live.
+
+Link to it from the confirmation page: `/manage-booking?bookingId=<id>&service=<name>`.
+
+---
+
+## Navigation contribution
+
+After writing your three route files, patch `src/layouts/Navigation.astro` to add the Services nav link. Insert at the `<!-- nav:links -->` marker:
+
+```astro
+<!-- nav:links -->
+<a href="/services">Services</a>
+```
+
+Follow the marker discipline rules in `references/shared/IMPLEMENTER.md` — preserve the marker line, insert after it, do not disturb adjacent content.
+
+---
+
+## Home page contribution
+
+Patch `src/pages/index.astro` to add a brief services teaser section. Insert at the `<!-- home:bookings -->` marker (emitted by `compose.mjs` when bookings is loaded). You are a **shell-patcher** (BUILD-astro § build wave, chain B) — `index.astro`/`Navigation.astro` patches are serialized against the other shell-patching verticals. The teaser should:
+- Show the first 3 services (query the live SDK like `/services` does; your `seeded.bookings` slice tells you what exists)
+- Include a "View All Services" CTA linking to `/services`
+- Use `<ServiceCard>` for each service entry
+
+If the `<!-- home:bookings -->` marker is absent from the file, skip the home contribution — do NOT invent a new insertion point.
+
+---
+
+## Pre-return file-existence assertion
+
+Before returning `status: "complete"`, verify all of these files exist on disk:
+- `src/pages/services/index.astro`
+- `src/pages/services/[slug].astro`
+- `src/pages/booking-confirmation.astro`
+- `src/pages/manage-booking.astro`
+- `src/components/ServiceBookingFlow.tsx`
+
+Missing file → return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<path>" }]`.
+
+---
+
+## Return contract
+
+```json
+{
+  "status": "complete",
+  "phase": "pages",
+  "vertical": "bookings",
+  "files": [
+    "src/pages/services/index.astro",
+    "src/pages/services/[slug].astro",
+    "src/pages/booking-confirmation.astro",
+    "src/pages/manage-booking.astro",
+    "src/components/ServiceBookingFlow.tsx"
+  ],
+  "contributions": [
+    { "file": "src/layouts/Navigation.astro", "marker": "nav:links" },
+    { "file": "src/pages/index.astro", "marker": "home:bookings" }
+  ]
+}
+```

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

@@ -4,7 +4,7 @@ The **rendering / code-patterns** half of CMS foundations: service module templa
 
 > **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.
+> **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
 
@@ -14,7 +14,7 @@ For SSR Astro pages (about, faq, portfolio, team, resource), import the seeded `
 
 ```astro
 ---
-import * as items from "@wix/wix-data-items-sdk";
+import { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 import { renderRicos } from "../utils/ricos";
 
@@ -46,7 +46,7 @@ The util covers the common subset (PARAGRAPH, HEADING 1-6, BULLETED_LIST / ORDER
 
 ## Prerequisites (page-side)
 
-- `@wix/data` + `@wix/wix-data-items-sdk` + `@wix/essentials` installed (collected by SETUP.md Step 4c — do NOT install independently).
+- `@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
@@ -65,7 +65,7 @@ For pages that just need to list items from a collection:
 
 ```astro
 ---
-import * as items from "@wix/wix-data-items-sdk";
+import { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 
 // Always elevate queries for permission safety
@@ -93,7 +93,7 @@ const myItems = results.map((item) => ({
 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 { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 import { media } from "@wix/sdk";
 

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

@@ -6,7 +6,7 @@ Build a FAQ page using `@wix/data` — Q&A pairs organized by category with acco
 
 ## Collection Schema
 
-Create a collection in the Wix dashboard → CMS with these fields:
+The schema the `seed` scope creates via REST (see `../../cms/CMS_FOUNDATIONS.md`) — fields:
 
 | Field | Type | Purpose |
 |-------|------|---------|
@@ -32,7 +32,7 @@ Create a collection in the Wix dashboard → CMS with these fields:
 ### 1. FAQ Service Module (`src/lib/faq.ts`)
 
 ```typescript
-import * as items from "@wix/wix-data-items-sdk";
+import { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 
 const COLLECTION_ID = "FAQ";
@@ -169,7 +169,7 @@ export default function FaqSection({ categories }: Props) {
 }
 ```
 
-> **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 `COMPONENT_PATTERNS.md` → FAQ Accordion.
+> **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
@@ -222,10 +222,10 @@ Key details:
 
 ## Testing
 
-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@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
+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

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

@@ -6,7 +6,7 @@ Build a visual portfolio using `@wix/data` — project grid with category filter
 
 ## Collection Schema
 
-Create a collection in the Wix dashboard → CMS with these fields:
+The schema the `seed` scope creates via REST (see `../../cms/CMS_FOUNDATIONS.md`) — fields:
 
 | Field | Type | Purpose |
 |-------|------|---------|
@@ -38,7 +38,7 @@ Create a collection in the Wix dashboard → CMS with these fields:
 ### 1. Portfolio Service Module (`src/lib/portfolio.ts`)
 
 ```typescript
-import * as items from "@wix/wix-data-items-sdk";
+import { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 import { media } from "@wix/sdk";
 
@@ -150,7 +150,7 @@ const { categories, activeCategory, basePath } = Astro.props;
 </nav>
 ```
 
-> **Styling note:** CategoryFilter styling is created by the design skill. See `COMPONENT_PATTERNS.md` → Category Filter.
+> **Styling note:** CategoryFilter styling is created by the design skill. See `references/shared/STYLING.md` (Category Filter).
 
 > Server-rendered, no JavaScript. Category is read from `Astro.url.searchParams` in the page.
 
@@ -189,7 +189,7 @@ const { project } = Astro.props;
 </a>
 ```
 
-> **Styling note:** ProjectCard styling is created by the design skill. See `COMPONENT_PATTERNS.md` → Project Card.
+> **Styling note:** ProjectCard styling is created by the design skill. See `references/shared/STYLING.md` (Project Card).
 
 ### 4. Project Grid Page (`src/pages/work/index.astro`)
 
@@ -376,7 +376,7 @@ export default function ImageGallery({ images, alt }: Props) {
 }
 ```
 
-> **Styling note:** Uses `.gallery-grid`, `.gallery-item`, `.lightbox-overlay`, `.lightbox-image`, `.lightbox-nav`, `.lightbox-close` from the designed component's `<style is:global>` block. See `COMPONENT_PATTERNS.md` → Image Gallery / Lightbox.
+> **Styling note:** Uses `.gallery-grid`, `.gallery-item`, `.lightbox-overlay`, `.lightbox-image`, `.lightbox-nav`, `.lightbox-close` from the designed component's `<style is:global>` block. See `references/shared/STYLING.md` (Image Gallery / Lightbox).
 
 Key details:
 - Renders as a grid; clicking opens a lightbox overlay
@@ -426,7 +426,7 @@ Project showcase image for [TITLE]. [BRAND AESTHETIC]. Color palette: [BRAND COL
 Gallery image [N] for [TITLE]: [describe a specific aspect/angle of the project]. [BRAND AESTHETIC]. [BRAND COLORS]. No text, no watermarks
 ```
 
-**Patch fields:** `coverImage`, optionally `galleryImages` (as an array of wixstatic URLs)
+**Patch field:** `galleryImages` (as an array of wixstatic URLs)
 
 Example patch:
 
@@ -445,10 +445,9 @@ body: {
 
 ## Testing
 
-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@latest dev`
-5. `/work` — grid with category filter tabs
-6. Click a category — filters projects
-7. Click a project — detail page with gallery lightbox
+Assumes the `seed` scope has already created the "Projects" collection and inserted items via REST (see `../../cms/CMS_FOUNDATIONS.md`) — 3+ projects with categories (and, after the image pass, cover/gallery images), 1–2 marked `featured: true`.
+
+1. Run `npx @wix/cli@latest dev`
+2. `/work` — grid with category filter tabs
+3. Click a category — filters projects
+4. Click a project — detail page with gallery lightbox

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

@@ -6,7 +6,7 @@ Build a downloadable resource library using `@wix/data` — file listings with c
 
 ## Collection Schema
 
-Create a collection in the Wix dashboard → CMS with these fields:
+The schema the `seed` scope creates via REST (see `../../cms/CMS_FOUNDATIONS.md`) — fields:
 
 | Field | Type | Purpose |
 |-------|------|---------|
@@ -36,7 +36,7 @@ Create a collection in the Wix dashboard → CMS with these fields:
 ### 1. Resources Service Module (`src/lib/resources.ts`)
 
 ```typescript
-import * as items from "@wix/wix-data-items-sdk";
+import { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 import { media } from "@wix/sdk";
 
@@ -146,8 +146,7 @@ const fileType = type.toUpperCase();
 ```
 
 Key details:
-- Color-coded by file type — red for PDF, blue for DOC, green for XLS, yellow for ZIP
-- Falls back to neutral gray for unknown types
+- The SVG uses `stroke="currentColor"` — any per-file-type coloring is purely CSS-driven (e.g. a `.file-type-pdf` class on the wrapper), not set here
 - File type label rendered inside the document icon SVG
 
 ### 3. Resource Card (`src/components/ResourceCard.astro`)
@@ -187,7 +186,7 @@ const { resource } = Astro.props;
 </a>
 ```
 
-> **Styling note:** ResourceCard styling is created by the design skill. See `COMPONENT_PATTERNS.md` → Resource Card.
+> **Styling note:** ResourceCard styling is created by the design skill. See `references/shared/STYLING.md` (Resource Card).
 
 ### 4. Resource Listing Page (`src/pages/resources/index.astro`)
 
@@ -347,10 +346,9 @@ body: {
 
 ## Testing
 
-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@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
+Assumes the `seed` scope has already created the "Resources" collection and inserted items via REST (see `../../cms/CMS_FOUNDATIONS.md`) — 4+ resources across 2+ categories with different file types (PDF, DOC, ZIP) and `fileUrl` links (any downloadable URL for testing).
+
+1. Run `npx @wix/cli@latest dev`
+2. `/resources` — shows all resources with category filters and file type badges
+3. Click a category — filters resources
+4. Click a resource — detail page with download button and related resources