@wix/agent-skills 1.8.0 → 1.10.0

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

@@ -1,428 +1,77 @@
-# 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" }
-  ]
-}
-```
+# 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/FAQ_KNOWLEDGE_BASE.md

@@ -180,7 +180,7 @@ 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".
+**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
 ---
@@ -195,7 +195,7 @@ const categories = [...grouped.entries()].map(([name, items]) => ({ name, items
 
 <Layout title="FAQ">
   <main>
-    <div class="container-reading px-lg">
+    <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>
 

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

@@ -33,7 +33,7 @@ No REST calls required. Page-design scopes are frontend-only — no `curl`, no M
 | `home` | build wave | `src/pages/index.astro` (composes pack home-sections + brand hero/CTA into the Composer-written shell) |
 | `static` | build wave | `src/pages/about.astro`, `src/pages/faq.astro` |
 | `store-pages` | build wave | `src/pages/products/index.astro`, `src/pages/products/[slug].astro`, `src/components/ProductCard.astro`, `src/pages/cart.astro`, `src/pages/thank-you.astro` |
-| `services-pages` | build wave | `src/pages/services/index.astro`, `src/pages/services/[slug].astro`, `src/pages/booking-confirmation.astro`, `src/pages/manage-booking.astro` |
+| `services-pages` | build wave | `src/pages/services/index.astro`, `src/pages/services/[slug].astro`, `src/pages/booking-confirmation.astro` |
 | `blog-pages` | build wave | `src/pages/blog/index.astro`, `src/pages/blog/[slug].astro` |
 | `contact-page` | build wave | `src/pages/contact.astro` |
 
@@ -102,8 +102,8 @@ All page scopes share common inputs and rules. Scope-specific details follow.
     </section>
     ```
 8. **Comments in frontmatter.** Use `//` or `/* */` — never HTML `<!-- -->` comments in `.astro` frontmatter (it's TypeScript, not HTML). HTML comments in the template section are fine.
-9. **Responsive.** All pages must work at mobile (320px), tablet (768px), and desktop (1024px+). Use Tailwind responsive prefixes (`md:`, `lg:`) and the spacing scale from `@theme`.
-10. **Use Tailwind utility classes in templates.** For layout, spacing, typography, and responsive design — use utility classes directly in the markup. Contract classes are still required for components referenced by Phase 3/4 agents. Mix both: `<div class="product-grid grid grid-cols-1 md:grid-cols-3 gap-lg">`. Always use brand `@theme` tokens (e.g., `bg-bark`, `text-cream`) — never default Tailwind colors.
+9. **Responsive.** All pages must work at mobile (320px), tablet (768px), and desktop (1024px+). Use Tailwind responsive prefixes (`md:`, `lg:`) and Tailwind's numeric spacing scale (`gap-4`, `py-24`, …).
+10. **Use Tailwind utility classes in templates.** For layout, spacing, typography, and responsive design — use utility classes directly in the markup. Contract classes are still required for components referenced by Phase 3/4 agents. Mix both: `<div class="product-grid grid grid-cols-1 md:grid-cols-3 gap-6">`. Always use brand `@theme` tokens (e.g., `bg-bark`, `text-cream`) — never default Tailwind colors.
 11. **No duplicate files.** If two scopes list the same file (rare), the scope whose prompt explicitly names it as "owned" takes precedence. If unclear, write it and note the overlap in your return.
 12. **Do NOT write to `src/styles/components-<pack>.css` or `src/styles/global.css`** — `components-<pack>.css` is pre-copied from the skill template by the orchestrator (build-wave pre-batch); `global.css` is owned by the Composer. Writing to either causes double-write conflicts.
 
@@ -230,7 +230,7 @@ All store-facing pages designed together for visual coherence.
 
 All bookings-facing pages designed together for visual coherence. **Canonical templates exist** at `<SKILL_ROOT>/references/astro/templates/bookings/` — adapt them (copy, headings, styling); do not re-author the SDK/booking-flow wiring (`references/astro/bookings/SERVICES_PAGES.md` is the wiring spec).
 
-**Files:** `src/pages/services/index.astro`, `src/pages/services/[slug].astro`, `src/pages/booking-confirmation.astro`, `src/pages/manage-booking.astro`
+**Files:** `src/pages/services/index.astro`, `src/pages/services/[slug].astro`, `src/pages/booking-confirmation.astro`
 
 **Services listing (`/services`):**
 - Page heading + optional brand tagline
@@ -240,13 +240,10 @@ All bookings-facing pages designed together for visual coherence. **Canonical te
 **Service detail (`/services/[slug]`):**
 - `container-reading` width (never a bare `max-w-<size>`); optional banner image **only when the service has media** (image-less is the common seed case — no fixed-ratio placeholder)
 - Title, tagline, duration + price row, description
-- "Book this service" section mounting the `ServiceBookingFlow` island (`client:only="react"`, threads `serviceType`) — calendar slots use `time-slot` classes (`--available`/`--selected`/`--full`), form uses the `booking-form` family
+- "Book this service" section mounting the `ServiceBookingFlow` island (`client:only="react"`, threads `serviceType`) — the week calendar uses the `availability-*` classes (week strip + `availability-day`), slots use `time-slot` classes (`--available`/`--selected`), and the form uses the `booking-*` family
 
 **Booking confirmation (`/booking-confirmation`):**
-- `max-w-prose`, centered; status-aware headline ("Thank you for booking" vs pending-approval) + embedded cancel (`ManageBooking` island, `showSummary={false}`)
-
-**Manage booking (`/manage-booking`):**
-- `container-reading`; booking summary + cancel via the `manage-booking` class family
+- `max-w-prose`, centered; "Thank you for booking" headline + the service name and time (read from the `service`/`startDate` query params) + a link back to `/services`. No re-fetch, no cancel UI (manage/cancel is out of scope).
 
 ### Scope: `blog-pages`
 
@@ -320,7 +317,7 @@ The JSON block MUST be the **last** content in your message — the parent parse
 | Author a `.tsx` React island in a page scope | Phase 3 Components writes the islands; the route only **mounts** them (`client:load`) |
 | Ship hardcoded data arrays as the final page | Query live SDK data in frontmatter (per the vertical reference) and bind it; hardcoded shapes are only a fallback for empty queries |
 | Write `global.css` or `@theme` tokens | The Composer owns `global.css`; you consume the published token contract |
-| Invent global semantic classes for layout/spacing/typography (`.featured-section`, `.page-header`) | Use Tailwind utilities derived from `@theme` tokens at the call site (`<section class="py-4xl">`); see `../../shared/STYLING.md` |
+| Invent global semantic classes for layout/spacing/typography (`.featured-section`, `.page-header`) | Use Tailwind utilities derived from `@theme` tokens at the call site (`<section class="py-24">`); see `../../shared/STYLING.md` |
 | Override `global.css` rules from page `<style>` blocks | Pages can add co-located styles for one-off decoration; never override Composer-owned global classes |
 | HTML `<!-- comment -->` in `.astro` frontmatter | Use `//` or `/* */` — frontmatter is TypeScript |
 | Use external placeholder image services (picsum, unsplash) | Use colored `<div>` placeholders with `data-decorative-slot` — the orchestrator injects Image Phase 1 URLs later |

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

@@ -22,7 +22,7 @@ Files this agent MUST NOT touch:
 
 Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave).
 
-For layout/spacing/typography, compose Tailwind utilities derived from `@theme` tokens at the call site (`<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-2xl">`). For published global semantic classes (`cart-summary`, `cart-total`, `checkout-btn`, `cart-empty` — the compound + interactive-state patterns), use the ACTUAL class name verbatim. Row-internal class names (`cart-item-qty`, `qty-btn`, etc.) come from the template — keep them as-is and live in `components-ecom.css`. See `references/shared/STYLING.md` and `references/shared/IMPLEMENTER.md` § "Styling: tokens-first, classes as exception".
+For layout/spacing/typography, compose Tailwind utilities derived from `@theme` tokens at the call site (`<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-12">`). For published global semantic classes (`cart-summary`, `cart-total`, `checkout-btn`, `cart-empty` — the compound + interactive-state patterns), use the ACTUAL class name verbatim. Row-internal class names (`cart-item-qty`, `qty-btn`, etc.) come from the template — keep them as-is and live in `components-ecom.css`. See `references/shared/STYLING.md` and `references/shared/IMPLEMENTER.md` § "Styling: tokens-first, classes as exception".
 
 ## Template files
 
@@ -61,7 +61,7 @@ Full cart display with two-column layout, quantity editing, remove, unavailable
 Class names used (template provides them — do not invent):
 - **Global semantic classes** (in `global.css`, designer-owned): `cart-summary`, `cart-total`, `checkout-btn`, `cart-empty` — compound patterns + interactive states
 - **Row-internal classes** (in `components-ecom.css`, written by this scope): `cart-item-qty`, `qty-btn`, `qty-value`, `cart-item-unavailable`, `cart-item-actions`, `cart-item-prices`, `cart-item-full-price`, `cart-item-unit-price`, `cart-item-line-total`, `cart-item-remove`, `cart-item-image-link`, `cart-item-name-link`, `cart-discount`, `cart-discount-name`, `cart-discount-amount`, `cart-applied-discounts`, `cart-applied-discounts-name`, `cart-item-option`, `cart-item-modifiers`
-- **Layout/spacing in markup as utilities**: `cart-grid` → `<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-2xl md:gap-3xl md:items-start">`; `cart-items` → `<div class="flex flex-col gap-lg">`; `cart-item` → `<div class="flex gap-lg pb-lg border-b border-rule last:border-0">`; `cart-subtotal` → `<div class="flex justify-between items-baseline">`; `cart-item-image` → utilities; `cart-item-info` → utilities; `cart-item-name` → `class="font-display text-lg leading-tight"`
+- **Layout/spacing in markup as utilities**: `cart-grid` → `<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-12 md:gap-16 md:items-start">`; `cart-items` → `<div class="flex flex-col gap-6">`; `cart-item` → `<div class="flex gap-6 pb-6 border-b border-rule last:border-0">`; `cart-subtotal` → `<div class="flex justify-between items-baseline">`; `cart-item-image` → utilities; `cart-item-info` → utilities; `cart-item-name` → `class="font-display text-lg leading-tight"`
 
 ### 2. `src/components/CartBadge.tsx`