@wix/agent-skills 1.16.3 → 1.18.0

package/skills/wix-headless-fast/references/blog/seed/SEED.md

@@ -0,0 +1,72 @@
+# Blog — seeding
+
+Seed by **running `seed-blog.mjs` with a plan file** — don't hand-write the REST calls.
+The script mints its own site token via the Wix CLI (logged-in session + `wix.config.json`
+required), installs the Blog app if needed, resolves a real author memberId (every post
+create requires one), and creates everything in the right order — categories/tags first,
+then **published** posts, then imported cover images (PATCH + re-publish).
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/references/blog/seed/seed-blog.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to 3 posts** (the seed shows
+the shape; the owner writes the rest in the dashboard) and make them exercise the UI: group
+them into 2 categories when the brief has natural sections, tag a couple, vary the content
+blocks (heading + paragraphs + a quote or list per post), and give every post a cover — a
+feed without covers looks broken.
+
+```json
+{
+  "categories": ["Brewing", "Stories"],
+  "posts": [
+    { "title": "How We Roast Our Single-Origin Beans", "category": "Stories", "tags": ["coffee"],
+      "coverImageUrl": "https://…",
+      "content": [
+        { "type": "heading", "text": "From farm to cup", "level": 2 },
+        { "type": "paragraph", "text": "Every batch starts with beans sourced from a single estate." },
+        { "type": "quote", "text": "Great coffee is grown, not made." }
+      ] },
+    { "title": "The Pour-Over, Step by Step", "category": "Brewing", "tags": ["guides"],
+      "coverImageUrl": "https://…",
+      "content": [
+        { "type": "paragraph", "text": "A repeatable ritual in five minutes." },
+        { "type": "ordered", "items": ["Rinse the filter", "Bloom 30 seconds", "Pour in circles"] }
+      ] },
+    { "title": "Why Water Matters More Than You Think", "category": "Brewing",
+      "coverImageUrl": "https://…",
+      "content": [
+        { "type": "paragraph", "text": "Coffee is 98% water — its minerals decide the cup." },
+        { "type": "bulleted", "items": ["Filtered, not distilled", "Aim for ~150 ppm hardness"] }
+      ] }
+  ]
+}
+```
+
+- `content` blocks: `{type:"heading",text,level?}` · `{type:"paragraph",text}` ·
+  `{type:"quote",text}` · `{type:"bulleted"|"ordered",items:[…]}`. For node types these don't
+  cover (code, inline images), pass a pre-built Ricos `richContent` on the post instead.
+- `category`/`categories`/`tags` are display **names** — created idempotently and resolved to
+  ids internally. Optional: skip them entirely when the brief doesn't group posts.
+- Cover — the default is a `coverImagePrompt` (AI-generated, ~1 Wix AI credit per image,
+  account-billed): brand-contextual — subject, aesthetic/mood, palette, lighting — always
+  ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually supplied use
+  `coverImagePath` (a file on this machine — uploaded to Wix Media) or `coverImageUrl` (their
+  own hosted URL; verify it with `curl -sI` → 200) — never a stock-photo or guessed URL. Covers resolve
+  in parallel and never block the seed; a failed cover leaves that post text-only (the script
+  re-publishes each post it covers).
+- Posts are created **published** — an unpublished post never reaches visitors. The bulk
+  create returns 200 even on partial failure: check each `posts[].success` in the result.
+
+**Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
+seems needed.
+
+## Escape hatch — individual functions
+`setupBlog` composes exported steps — `installBlogApp`, `getAuthorMemberId`, `createPosts`,
+`createCategories`, `createTags`, `importImage`, `attachPostCovers`, plus `makeCtx()` —
+import them only for a partial re-seed.
+
+## Reference
+Unexpected shape or an uncovered operation → read the live Wix API reference; the
+authoritative source recipe is `wix-headless/references/inline-recipes/setup-blog.md`.

package/skills/wix-headless-fast/references/blog/seed/seed-blog.mjs

@@ -0,0 +1,287 @@
+// Blog seed — a BUILD-TIME script, never shipped in the app. Run from the project root
+// (where wix.config.json lives) with a plan file:
+//
+//   node <SKILL_ROOT>/references/blog/seed/seed-blog.mjs plan.json
+//
+// It mints its own site token via the Wix CLI, installs the Wix Blog app if needed, resolves
+// a real author memberId (every post create requires one), creates categories/tags (idempotent
+// by label, with a fresh-install verify-retry), bulk-creates PUBLISHED posts with Ricos
+// richContent, and imports+attaches cover images (PATCH + re-publish). Prints a JSON result
+// to stdout.
+//
+// Plan shape (see SEED.md):
+//   { "categories"?: [name], "tags"?: [name],
+//     "posts": [{ "title", "content": [blocks] | "richContent"?, "category"?|"categories"?,
+//                 "tags"?, "coverImageUrl"? | "coverImagePrompt"? }] }
+//   content blocks: { type:"heading", text, level? } | { type:"paragraph", text }
+//     | { type:"quote", text } | { type:"bulleted"|"ordered", items:[text,…] }
+//
+// Seeding is ADDITIVE — never deletes or overwrites existing content. Unexpected shapes →
+// read the live API reference; authoritative source recipe:
+// wix-headless/references/inline-recipes/setup-blog.md.
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolveItemImages } from "../../shared/seed/images.mjs";
+
+const API = "https://www.wixapis.com";
+const BLOG_APP_ID = "14bcded7-0066-7c35-14d7-466cb3f09103";
+
+export function makeCtx({ cwd = process.cwd() } = {}) {
+  const config = JSON.parse(readFileSync(`${cwd}/wix.config.json`, "utf8"));
+  const siteId = config.siteId ?? config.projectId;
+  if (!siteId) throw new Error("wix.config.json has no siteId — is this a Wix CLI project?");
+  const token = execFileSync("npx", ["@wix/cli@latest", "token", "--site", siteId], {
+    encoding: "utf8",
+    cwd,
+  }).trim();
+  if (!token) throw new Error("The Wix CLI returned no token — run `npx @wix/cli@latest login` first.");
+  return { token, siteId };
+}
+
+async function req(ctx, path, { method = "POST", body } = {}) {
+  const res = await fetch(API + path, {
+    method,
+    headers: {
+      Authorization: `Bearer ${ctx.token}`,
+      "wix-site-id": ctx.siteId,
+      "Content-Type": "application/json",
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 400)}`);
+  return json;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ---- Ricos richContent builder (setup-blog.md § "CRITICAL RICOS NESTING") --------------------
+// Rules baked in: TEXT is always a leaf inside a container; BLOCKQUOTE / LIST_ITEM wrap a
+// PARAGRAPH; BULLETED_LIST / ORDERED_LIST wrap LIST_ITEM -> PARAGRAPH -> TEXT; every container
+// node gets a unique id, TEXT leaves use id "". For node types not covered here (code, images)
+// pass a pre-built `richContent` on the post instead — it's used verbatim.
+const mkText = (text) => ({ type: "TEXT", id: "", nodes: [], textData: { text: text || "", decorations: [] } });
+const mkParagraph = (id, text) => ({ type: "PARAGRAPH", id, nodes: [mkText(text)], paragraphData: {} });
+
+function mkRichContent(blocks = [], postIdx = 0) {
+  let n = 0;
+  const id = () => `p${postIdx}-n${n++}`;
+  const nodes = [];
+  for (const b of blocks) {
+    switch (b.type) {
+      case "heading":
+        nodes.push({ type: "HEADING", id: id(), nodes: [mkText(b.text)], headingData: { level: b.level ?? 2 } });
+        break;
+      case "quote":
+        nodes.push({ type: "BLOCKQUOTE", id: id(), nodes: [mkParagraph(id(), b.text)], blockquoteData: { indentation: 1 } });
+        break;
+      case "bulleted":
+      case "ordered": {
+        const listType = b.type === "bulleted" ? "BULLETED_LIST" : "ORDERED_LIST";
+        nodes.push({
+          type: listType, id: id(),
+          nodes: (b.items ?? []).map((item) => ({ type: "LIST_ITEM", id: id(), nodes: [mkParagraph(id(), item)] })),
+        });
+        break;
+      }
+      case "paragraph":
+      default:
+        nodes.push(mkParagraph(id(), b.text));
+    }
+  }
+  return { nodes };
+}
+
+// One post's plain data -> a flat Blog V3 draft-post object. media is omitted — covers are a
+// separate pass (attachPostCovers), per the recipe.
+function buildPost(p, i, memberId) {
+  return {
+    title: p.title,
+    memberId,
+    richContent: p.richContent ?? mkRichContent(p.content, i),
+    ...(p.categoryIds ? { categoryIds: p.categoryIds } : {}),
+    ...(p.tagIds ? { tagIds: p.tagIds } : {}),
+  };
+}
+
+// ---- operations ----------------------------------------------------------------------------
+
+// docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
+export async function installBlogApp(ctx) {
+  try {
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+      tenant: { tenantType: "SITE", id: ctx.siteId },
+      appInstance: { appDefId: BLOG_APP_ID, enabled: true },
+    } });
+  } catch {
+    /* already installed is fine */
+  }
+}
+
+// Every post create needs a REAL author memberId — a fabricated id fails with
+// "memberIds ... do not exist". A provisioned site has the owner as members[0].
+// docs: https://dev.wix.com/docs/api-reference/crm/members-contacts/members/members/list-members.md
+export async function getAuthorMemberId(ctx) {
+  const r = await req(ctx, "/members/v1/members?fieldsets=PUBLIC&paging.limit=1", { method: "GET" });
+  const id = r.members?.[0]?.id;
+  if (!id) throw new Error(`No site member found for author attribution: ${JSON.stringify(r).slice(0, 400)}`);
+  return id;
+}
+
+/**
+ * Create posts, PUBLISHED (publish:true — unpublished posts never reach visitors).
+ * Endpoint auto-selected per the recipe: single-post endpoint for exactly one (nested
+ * `{ draftPost }` envelope), bulk for >= 2 — `bulk` sits BETWEEN v3 and draft-posts, and each
+ * bulk item is FLAT (wrapping it in `draftPost` 400s). Returns [{ id, index, success }].
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/draft-posts/create-draft-post.md
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/draft-posts/bulk-create-draft-posts.md
+ */
+export async function createPosts(ctx, posts, { memberId, publish = true } = {}) {
+  if (!memberId) throw new Error("createPosts requires opts.memberId (see getAuthorMemberId)");
+  if (posts.length === 1) {
+    const r = await req(ctx, "/blog/v3/draft-posts", { body: { draftPost: buildPost(posts[0], 0, memberId), publish } });
+    return [{ id: r.draftPost?.id, index: 0, success: !!r.draftPost?.id }];
+  }
+  const r = await req(ctx, "/blog/v3/bulk/draft-posts/create", {
+    body: { draftPosts: posts.map((p, i) => buildPost(p, i, memberId)), publish },
+  });
+  // Bulk returns 200 even on partial failure — read per-item results[].itemMetadata.success.
+  return (r.results ?? []).map((x) => ({
+    id: x.itemMetadata?.id, index: x.itemMetadata?.originalIndex, success: !!x.itemMetadata?.success,
+  }));
+}
+
+// Existing label -> id, straight from the query (the source of truth for what persisted).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/category/query-categories.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/query-tags.md
+async function labelIdMap(ctx, kind) {
+  const path = kind === "categories" ? "/blog/v3/categories/query" : "/v3/tags/query";
+  const r = await req(ctx, path, { body: { query: { paging: { limit: 100 } } } });
+  return new Map((r[kind] ?? []).map((x) => [x.label, x.id]));
+}
+
+// Create category/tag labels resiliently. TWO hazards this absorbs:
+//  1. Fresh-install provisioning window — for a few seconds after the Blog app installs,
+//     per-item category/tag creates return 200 with an id but DON'T persist (the id is a lie).
+//     So the create response is never trusted — re-query, treat the query as truth, re-create
+//     what's still missing until it sticks.
+//  2. Idempotency — an already-present label (a partial-failure re-run) is skipped.
+// Category bodies are NESTED (`{ category: { label } }`); tag bodies are FLAT (`{ label }`) —
+// a `{ tag: { label } }` body sends an empty top-level label and 400s. Returns [{ id, name }].
+async function ensureLabels(ctx, kind, createPath, mkBody, names) {
+  let map = await labelIdMap(ctx, kind);
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const missing = names.filter((n) => !map.has(n));
+    if (!missing.length) break;
+    if (attempt) await sleep(1500); // backoff only between retries — happy path pays nothing
+    for (const name of missing) {
+      try { await req(ctx, createPath, { body: mkBody(name) }); }
+      catch (e) { if (!String(e.message).includes("-> 409")) throw e; } // 409 = raced, already there
+    }
+    map = await labelIdMap(ctx, kind);
+  }
+  return names.map((name) => ({ id: map.get(name), name }));
+}
+
+/** Create categories idempotently by label (no bulk endpoint). Feed ids into post.categoryIds. */
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/category/create-category.md
+export async function createCategories(ctx, names) {
+  return ensureLabels(ctx, "categories", "/blog/v3/categories", (name) => ({ category: { label: name } }), names);
+}
+
+/** Create tags idempotently by label. Feed ids into post.tagIds. */
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/create-tag.md
+export async function createTags(ctx, names) {
+  return ensureLabels(ctx, "tags", "/blog/v3/tags", (name) => ({ label: name }), names);
+}
+
+// Blog binds a post cover by Wix Media file ID — an external url must be imported first; a
+// plan `coverImagePrompt` is generated (Wix AI, 1 credit) then imported. Both live in the
+// shared util (parallel, resilient, never blocks the seed).
+export { importImage } from "../../shared/seed/images.mjs";
+
+// covers: [{ postId, fileId }] where fileId is the Wix Media file.id from importImage. Per
+// post: PATCH /blog/v3/draft-posts/{id} (NOT POST …/{id}/update — that 404s), setting
+// media.displayed:true + media.custom:true + wixMedia.image.id (the id ALONE is a silent
+// no-op), then RE-PUBLISH — the PATCH sets hasUnpublishedChanges, so the live post stays
+// cover-less until republished. Image failures never block the run.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/draft-posts/update-draft-post.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/draft-posts/publish-draft-post.md
+export async function attachPostCovers(ctx, covers) {
+  let attached = 0;
+  for (const { postId, fileId } of covers) {
+    try {
+      await req(ctx, `/blog/v3/draft-posts/${postId}`, {
+        method: "PATCH",
+        body: { draftPost: { media: { displayed: true, custom: true, wixMedia: { image: { id: fileId } } } } },
+      });
+      await req(ctx, `/blog/v3/draft-posts/${postId}/publish`, { method: "POST" });
+      attached++;
+    } catch (e) {
+      console.error(`cover attach skipped for post ${postId}: ${e.message}`);
+    }
+  }
+  return attached;
+}
+
+/**
+ * ONE-CALL seed: install → author memberId → categories/tags (names resolved to ids) →
+ * published posts → covers, ids threaded in memory. The default path.
+ */
+export async function setupBlog(ctx, { posts = [], categories = [], tags = [] } = {}) {
+  await installBlogApp(ctx);
+  await sleep(3000); // let a fresh Blog install settle so the first category/tag writes stick
+                     // (correctness is still guaranteed by ensureLabels' verify-retry).
+  const memberId = await getAuthorMemberId(ctx);
+
+  const catNames = [...new Set([...categories, ...posts.flatMap((p) => [].concat(p.category ?? [], p.categories ?? []))])];
+  const tagNames = [...new Set([...tags, ...posts.flatMap((p) => [].concat(p.tags ?? []))])];
+  const cats = catNames.length ? await createCategories(ctx, catNames) : [];
+  const tgs = tagNames.length ? await createTags(ctx, tagNames) : [];
+  const catId = new Map(cats.map((c) => [c.name, c.id]));
+  const tagId = new Map(tgs.map((t) => [t.name, t.id]));
+
+  const created = await createPosts(ctx, posts.map((p) => {
+    const cn = [].concat(p.category ?? [], p.categories ?? []);
+    const tn = [].concat(p.tags ?? []);
+    return {
+      ...p,
+      ...(cn.length ? { categoryIds: cn.map((n) => catId.get(n)).filter(Boolean) } : {}),
+      ...(tn.length ? { tagIds: tn.map((n) => tagId.get(n)).filter(Boolean) } : {}),
+    };
+  }), { memberId });
+
+  // Pass 2 — covers: resolve (import by url / generate by prompt) in one parallel wave, then
+  // attach (PATCH + re-publish per post). Failures leave the post text-only; the seed's exit
+  // never depends on images.
+  const files = await resolveItemImages(ctx, created.map((c, i) => (
+    c?.id && c?.success
+      ? { path: posts[i]?.coverImagePath, url: posts[i]?.coverImageUrl, prompt: posts[i]?.coverImagePrompt, displayName: `post-${i}.png` }
+      : null
+  )));
+  const covers = created
+    .map((c, i) => (files[i] ? { postId: c.id, fileId: files[i].id } : null))
+    .filter(Boolean);
+  const coversAttached = covers.length ? await attachPostCovers(ctx, covers) : 0;
+
+  return { posts: created, categories: cats, tags: tgs, coversAttached };
+}
+
+// ---- CLI entry ----------------------------------------------------------------------------------
+
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
+if (invokedDirectly) {
+  const planPath = process.argv[2];
+  if (!planPath) {
+    console.error("usage: node seed-blog.mjs <plan.json>   (run from the project root)");
+    process.exit(1);
+  }
+  const plan = JSON.parse(readFileSync(planPath, "utf8"));
+  const ctx = makeCtx();
+  setupBlog(ctx, plan)
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+}

package/skills/wix-headless-fast/references/bookings/INSTRUCTIONS.md

@@ -0,0 +1,129 @@
+# Bookings — playbook
+
+The booking machinery ships as files — services reads, availability (appointment AND class),
+the schema-driven booking form, and the exact `createBooking → cart → checkout-or-place`
+sequence, typed end-to-end. **The presentation is yours**: you design and implement the
+service card, the listing surface, and the booking surface on the shipped hooks/DTOs, plus
+the home page and the brand. You never write booking logic; you never skip designing.
+
+## The file map (deployed into `src/`)
+
+**Don't read the shipped files** — this table and the contracts below are everything you
+need. Open a shipped file's source only on a real fallback (runtime error / uncovered field),
+or to read a reference component's pattern.
+
+| file | what it is |
+|---|---|
+| `wix/config.ts` · `wix/sdk.ts` · `wix/media.ts` · `wix/money.ts` | shared auth seam + helpers (deploy configures; nothing to set) |
+| `wix/bookings/types.ts` | the DTOs (`ServiceSummary`, `ServiceDetail`, `Slot`, `BookingFormField`, `BookingResult`) — contracts below |
+| `wix/bookings/services.ts` | `fetchServices`, `fetchServiceBySlug`, `fetchBookingCategories` |
+| `wix/bookings/booking.ts` | `fetchSlots`, `fetchBookingForm`, `bookService` — the exact booking sequence lives here |
+| `hooks/bookings/useServices.ts` | listing + category filter — contract below |
+| `hooks/bookings/useBookingFlow.ts` | the whole booking state machine — contract below |
+| `components/bookings/ServicesView.tsx` (+ `ServiceCard`) · `ServiceBookingView.tsx` | **REFERENCE implementations** — correct, plain; build your own instead of shipping them |
+| `styles/global.css` | the design system: Tailwind v4 + the `@theme` token block (shared across verticals) |
+
+Astro stack additionally gets:
+
+| file | what it is |
+|---|---|
+| `layouts/SiteLayout.astro` | site chrome — **yours to brand** (keep the `seo-tags` slot + global.css import). If storefront is also deployed, its layout won — add a Services nav link there |
+| `pages/services.astro` | SSR listing — **keep the frontmatter**, swap the island import to YOUR component |
+| `pages/services/[slug].astro` | SSR detail + booking with owner-editable SEO — **keep the frontmatter and the SEO pieces** (`wixMetadata`, `loadSEOTagsServiceConfig`, `<SEO.Tags>`) exactly; swap the island import. The booking island stays `client:only="react"` (availability is timezone-specific) |
+
+## What you build — the design job
+
+1. **The service card + listing surface** — your tile (image, type badge, duration/price
+   presentation) and rhythm, with skeletons while loading and an honest empty state — on
+   `useServices`.
+2. **The booking surface** — day-grouped slot picking, week paging, staff filter (only when
+   >1 staff), the schema-driven form, the book CTA (label free vs priced), and the confirmed
+   state — on `useBookingFlow`, which owns ALL booking logic; you own how it looks.
+3. **The home page** — hero, featured services (fetch in frontmatter → your components),
+   brand story.
+
+Plus the **theme** (`@theme` block, one edit) and the **chrome** (`SiteLayout`, one pass).
+Style everything with Tailwind utilities on the tokens.
+
+### The contracts your components consume
+
+```ts
+// ServiceSummary (tiles) — display-ready:
+// { id, slug, name, tagLine, type: "APPOINTMENT"|"CLASS", price /* "€75.00" | "Free" */,
+//   free, durationMinutes|null, imageUrl, categoryId|null, staff: [{id,name}] }
+// ServiceDetail adds: description, formId, paymentOption, cancellationFeeEnabled.
+
+// useServices({ initialServices?, initialCategories? }) →
+// { services: ServiceSummary[]|null /* null = loading → skeletons */,
+//   categories: [{id,name}], activeCategoryId, setActiveCategoryId(id|null), error }
+
+// useBookingFlow(service: ServiceDetail) →
+// { days: [{ dayKey, dayLabel, slots: Slot[] }] | null,   // day-grouped; null = loading
+//   windowStart, nextWeek(), prevWeek(),                  // 7-day paging (prev clamps to today)
+//   staffId, setStaffId(id|undefined),                    // show a picker only when service.staff.length > 1
+//   selectedSlot, setSelectedSlot(slot|null),             // Slot = { startLocal, endLocal, dayKey, label, … }
+//   formFields: [{ target, label, type, options? }],      // never empty (contact-basics fallback)
+//   values, setValue(target, value),                      // inputs write here, keyed by target
+//   canBook,                                              // gate the CTA on this
+//   book(): Promise<BookingResult>,                       // paid → the browser redirects to Wix checkout;
+//   booking, confirmed, error }                           // free/offline → confirmed is set (REAL success)
+```
+
+### Wiring — Astro (default)
+
+1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass — merge into the
+   storefront layout instead if both verticals are deployed).
+2. Write your components under `src/components/bookings/` (new names — don't overwrite the
+   references), swap the island imports in `pages/services.astro` and
+   `pages/services/[slug].astro`. Listing island: `client:load` with the SSR props; booking
+   island: `client:only="react"`. **Author your surfaces in as few messages as possible** —
+   batch multiple Writes per message.
+3. Write `pages/index.astro` (home) — it exists from the scaffold; Read it before overwriting.
+
+### Wiring — React SPA (Vite etc.)
+
+Import `./styles/global.css` once at the app entry (needs `@tailwindcss/vite` in the vite
+plugins — deploy added the dep). Routes: `/services` → your listing; `/services/:slug` →
+fetch with `fetchServiceBySlug(slug)` client-side, then your booking surface.
+
+## Hard rules
+
+- **Booking logic only through the shipped exports** — `useBookingFlow`/`bookService` own the
+  sequence (createBooking → cart holds the seat → checkout-or-place), the payment-option
+  derivation, ANY_RESOURCE, and the formSubmission shape. Never re-derive any of it, never
+  call `confirmBooking`, never hand-build a checkout URL.
+- **The form is schema-driven** — render `formFields` as given (values keyed by `target`);
+  never hardcode field names beyond what the fallback already guarantees.
+- **Gate the CTA on `canBook`** and surface `error` — `book()` can reject (slot taken,
+  validation); that message is for the visitor.
+- **The confirmed state must reflect REAL success**: render it only from `confirmed` (set by
+  the free/offline branch). A visitor returning from the hosted checkout redirect is NOT a
+  success signal — don't fake a confirmation page off the return URL.
+- Theme via the `@theme` tokens; no parallel theme files, no hardcoded palettes.
+- Live data or an honest empty state — never mock services, slots, or availability.
+- Keep the detail page's SEO pieces exactly as shipped.
+
+## Point the user to their dashboard
+
+Give the owner the dashboard link plus the Bookings services/calendar pages — the deploy
+step's JSON printed `dashboardUrl`; append `/bookings/services` for service management.
+Taking real online payments needs a premium plan + a connected payment method — mention it.
+
+## Seeding
+
+Per `seed/SEED.md` — plain-data `plan.json` into `seed-bookings.mjs` from the project root.
+Seed services that exercise the UI (an APPOINTMENT with duration+price, a free one, a CLASS
+with future sessions when it fits the business; an image per service).
+
+## Verify (before declaring done)
+
+- [ ] `/services` renders live services SSR (view-source shows names) through YOUR components;
+      empty catalog shows your honest empty state.
+- [ ] A service page shows day-grouped bookable times; week paging works; the form renders
+      (schema or fallback) and the CTA stays disabled until a slot + all fields are set.
+- [ ] A FREE service books end-to-end: `book()` resolves, your confirmed state renders.
+- [ ] A PAID service redirects to the Wix-hosted checkout.
+- [ ] Service page view-source carries the SEO tags (Astro).
+- [ ] Card/listing/booking surfaces/home are YOUR designs on the tokens; data-layer/hook files
+      unedited.
+- [ ] Dashboard links handed to the owner.

package/skills/wix-headless-fast/references/bookings/app/components/bookings/ServiceBookingView.tsx

@@ -0,0 +1,143 @@
+// REFERENCE booking surface: service info + day-grouped slot picker + staff filter +
+// schema-driven form + book CTA, on the @theme tokens. Correct and complete; per the
+// skill's model you design and build your own on useBookingFlow. Mount client:only —
+// availability is timezone/session-specific.
+import { useBookingFlow } from "../../hooks/bookings/useBookingFlow";
+import type { ServiceDetail } from "../../wix/bookings/types";
+
+const chip = (selected: boolean) =>
+  `rounded-full border px-4 py-1.5 text-sm transition-colors ${
+    selected
+      ? "border-primary bg-primary text-primary-foreground"
+      : "border-border text-foreground hover:bg-secondary"
+  }`;
+
+export default function ServiceBookingView({ service }: { service: ServiceDetail }) {
+  const {
+    days,
+    nextWeek,
+    prevWeek,
+    staffId,
+    setStaffId,
+    selectedSlot,
+    setSelectedSlot,
+    formFields,
+    values,
+    setValue,
+    canBook,
+    book,
+    booking,
+    confirmed,
+    error,
+  } = useBookingFlow(service);
+
+  if (confirmed) {
+    return (
+      <div className="rounded-lg border border-border bg-secondary p-8 text-center">
+        <p className="text-lg font-semibold">You're booked! 🎉</p>
+        <p className="mt-2 text-sm text-muted-foreground">
+          {service.name}
+          {selectedSlot ? ` — ${selectedSlot.dayKey} at ${selectedSlot.label}` : ""}. A confirmation
+          email is on its way.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      {service.staff.length > 1 && (
+        <div className="mb-5">
+          <p className="mb-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">Staff</p>
+          <div className="flex flex-wrap gap-2">
+            <button type="button" className={chip(staffId === undefined)} onClick={() => setStaffId(undefined)}>
+              Anyone
+            </button>
+            {service.staff.map((m) => (
+              <button key={m.id} type="button" className={chip(staffId === m.id)} onClick={() => setStaffId(m.id)}>
+                {m.name}
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+
+      <div className="mb-2 flex items-center justify-between">
+        <p className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">Pick a time</p>
+        <div className="flex gap-2">
+          <button type="button" onClick={prevWeek} aria-label="Previous week" className="rounded-full border border-border px-3 py-1 text-sm text-foreground transition-colors hover:bg-secondary">←</button>
+          <button type="button" onClick={nextWeek} aria-label="Next week" className="rounded-full border border-border px-3 py-1 text-sm text-foreground transition-colors hover:bg-secondary">→</button>
+        </div>
+      </div>
+
+      {days === null ? (
+        <div className="space-y-3" aria-busy="true">
+          {Array.from({ length: 3 }, (_, i) => (
+            <div key={i} className="h-10 animate-pulse rounded-md bg-secondary" />
+          ))}
+        </div>
+      ) : days.length === 0 ? (
+        <p className="rounded-md border border-border p-4 text-sm text-muted-foreground">
+          No times in this week — try the next one.
+        </p>
+      ) : (
+        <div className="space-y-4">
+          {days.map((day) => (
+            <div key={day.dayKey}>
+              <p className="mb-2 text-sm font-medium">{day.dayLabel}</p>
+              <div className="flex flex-wrap gap-2">
+                {day.slots.map((s) => (
+                  <button
+                    key={s.startLocal + (s.eventId ?? "")}
+                    type="button"
+                    className={chip(selectedSlot?.startLocal === s.startLocal)}
+                    onClick={() => setSelectedSlot(s)}
+                  >
+                    {s.label}
+                  </button>
+                ))}
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+
+      <div className="mt-6 grid max-w-md gap-3">
+        {formFields.map((f) => (
+          <label key={f.target} className="block">
+            <span className="mb-1 block text-xs font-semibold uppercase tracking-wider text-muted-foreground">{f.label}</span>
+            {f.options?.length ? (
+              <select
+                value={values[f.target] ?? ""}
+                onChange={(e) => setValue(f.target, e.target.value)}
+                className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground outline-none transition-shadow focus:ring-2 focus:ring-primary"
+              >
+                <option value="">Choose…</option>
+                {f.options.map((o) => (
+                  <option key={o} value={o}>{o}</option>
+                ))}
+              </select>
+            ) : (
+              <input
+                type={f.type === "EMAIL" ? "email" : f.type === "PHONE" ? "tel" : f.type === "NUMBER" ? "number" : f.type === "URL" ? "url" : "text"}
+                value={values[f.target] ?? ""}
+                onChange={(e) => setValue(f.target, e.target.value)}
+                className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground outline-none transition-shadow focus:ring-2 focus:ring-primary"
+              />
+            )}
+          </label>
+        ))}
+      </div>
+
+      {error && <p className="mt-3 text-sm text-red-600">{error}</p>}
+      <button
+        type="button"
+        disabled={!canBook || booking}
+        onClick={() => book().catch(() => {})}
+        className="mt-5 rounded-full bg-primary px-8 py-3 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
+      >
+        {booking ? "Booking…" : service.free ? "Book — free" : `Book · ${service.price}`}
+      </button>
+    </div>
+  );
+}