@wix/agent-skills 1.25.0 → 1.27.0

package/skills/wix-headless-templates/events/seed/seed-events.mjs

@@ -0,0 +1,322 @@
+// Events 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>/templates/events/seed/seed-events.mjs plan.json
+//
+// It mints its own site token via the Wix CLI, installs the Wix Events app if needed,
+// resolves the site currency, then per event: create DRAFT → (TICKETING) add ticket tiers →
+// publish — the order two one-way constraints force (registration.initialType is immutable
+// after create; publishing is one-way). Then it creates + assigns categories and
+// imports+attaches images. Prints a JSON result to stdout.
+//
+// Plan shape (see SEED.md):
+//   { "events": [{ "title", "shortDescription"?, "type": "TICKETING"|"RSVP",
+//                  "startDate", "endDate" (future ISO-8601 UTC), "timeZoneId",
+//                  "location" ({name,type:"VENUE",address} | {name,type:"ONLINE"} | {locationTbd:true,name}),
+//                  "ticketTiers"?: [{ "name" (≤30 chars), "price" (decimal STRING), "description"?, "initialLimit"?, "feeType"? }],
+//                  "category"? (name), "imageUrl"? | "imagePrompt"?, "rsvpResponseType"? }] }
+//
+// Seeding is ADDITIVE — never deletes or overwrites existing content. Unexpected shapes →
+// read the live API reference; every call below
+// carries a docs: line with its reference page.
+import { setSiteCurrency } from "../../shared/seed/site.mjs";
+import { readFileSync } from "node:fs";
+import { resolveItemImages } from "../../shared/seed/images.mjs";
+import { seedSiteId } from "../../shared/seed/site-context.mjs";
+import { wixToken } from "../../shared/seed/wix-cli.mjs";
+
+const API = "https://www.wixapis.com";
+const EVENTS_APP_ID = "140603ad-af8d-84a5-2c80-a0f60cb47351";
+
+export function makeCtx({ cwd = process.cwd() } = {}) {
+  // The content site: the config's site, or the parent on a migration preview (site-context.mjs stops
+  // a seed there unless --allow-parent is passed after the user confirmed).
+  const siteId = seedSiteId({ cwd, argv: process.argv });
+  const token = wixToken(siteId, cwd);
+  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;
+}
+
+// {type:"TICKETING"|"RSVP", …} -> the registration block. TICKETING carries a tickets{}
+// config; RSVP carries rsvp{responseType} and seeds NO form fields (name+email is built-in).
+// initialType is IMMUTABLE after create — set from the plan, never plan to convert.
+function buildRegistration(ev) {
+  if (ev.type === "TICKETING") {
+    return {
+      initialType: "TICKETING",
+      tickets: {
+        ticketLimitPerOrder: ev.ticketLimitPerOrder ?? 8,
+        currency: ev.currency ?? "USD", // setupEvents threads the site currency; USD is the last resort
+        reservationDurationInMinutes: ev.reservationDurationInMinutes ?? 20,
+      },
+    };
+  }
+  return {
+    initialType: "RSVP",
+    rsvp: {
+      responseType: ev.rsvpResponseType ?? "YES_ONLY", // "YES_ONLY" | "YES_AND_NO"
+      ...(Number.isInteger(ev.rsvpLimit) && ev.rsvpLimit > 0 ? { limit: ev.rsvpLimit } : {}),
+      ...(ev.waitlist === true ? { waitlistEnabled: true } : {}),
+      // A future start date schedules the opening: the event publishes with status SCHEDULED_RSVP and
+      // the page says when registration opens; before it, an RSVP is refused. The API requires the
+      // window's END with its start (run 152: "both start and end dates"); it defaults to the event's
+      // start, the moment registration stops making sense.
+      ...(ev.registrationOpensAt ? { startDate: ev.registrationOpensAt, endDate: ev.registrationClosesAt ?? ev.startDate } : {}),
+    },
+  };
+}
+
+// {guests: N} on an RSVP event -> the registration form's guest control, added through the Events
+// Forms API AFTER the event exists (Create Event ignores form.controls; probed live 2026-09-28). The
+// control lands as a count input (options "0".."N") plus a names list capped at N — the shape the
+// site's form reader (events-core toRsvpForm) reads its max from — and takes effect at once.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/forms/add-control.md
+export async function addGuestControl(ctx, eventId, guests) {
+  const n = Number(guests);
+  if (!Number.isInteger(n) || n < 1) return false;
+  await req(ctx, `/events/v1/events/${eventId}/form/control`, { body: {
+    additionalGuests: { maxGuests: n, namesMandatory: false, labels: { single: "Bringing a guest?", multiple: "How many guests?" } },
+  } });
+  return true;
+}
+
+// ---- operations ----------------------------------------------------------------------------------
+
+// Idempotent: re-installing an already-installed app returns 200.
+// docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
+export async function installEventsApp(ctx) {
+  try {
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+      tenant: { tenantType: "SITE", id: ctx.siteId },
+      appInstance: { appDefId: EVENTS_APP_ID, enabled: true },
+    } });
+  } catch {
+    /* already installed is fine */
+  }
+}
+
+// The ticket-definitions API REQUIRES currency and uses whatever you pass verbatim (it does
+// NOT fall back to the site currency) — resolve it once, or a non-USD site gets mis-priced.
+// docs: https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties.md
+export async function getSiteCurrency(ctx) {
+  try {
+    const r = await req(ctx, "/site-properties/v4/properties", { method: "GET" });
+    return r?.properties?.paymentCurrency || "USD";
+  } catch {
+    return "USD";
+  }
+}
+
+/**
+ * STEP 1 — create ONE event as a draft (no bulk endpoint; loop for multiple). Dates MUST be
+ * in the future — a past event isn't registerable and won't show in the live listing.
+ * Returns { id, slug } — id feeds the tier/publish steps; slug is the URL identifier.
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/create-event.md
+ */
+export async function createEvent(ctx, ev) {
+  const body = {
+    draft: true,
+    event: {
+      title: ev.title,
+      shortDescription: ev.shortDescription,
+      location: ev.location,
+      dateAndTimeSettings: {
+        startDate: ev.startDate,
+        endDate: ev.endDate,
+        timeZoneId: ev.timeZoneId,
+        showTimeZone: ev.showTimeZone ?? true,
+      },
+      registration: buildRegistration(ev),
+    },
+    fields: ["DETAILS", "TEXTS", "REGISTRATION", "URLS"],
+  };
+  const r = await req(ctx, "/events/v3/events", { body });
+  return { id: r.event?.id, slug: r.event?.slug };
+}
+
+/**
+ * STEP 2 — ticket tiers for a TICKETING event (skip for RSVP). Must run BEFORE publish —
+ * publishing a ticketed event with no tiers ships an event with nothing to buy, and there is
+ * no un-publish. price is a decimal STRING ("65.00", never a number); name ≤ 30 chars; omit
+ * initialLimit for unlimited. `feeType` is FEE_INCLUDED (the Wix fee comes out of the price),
+ * FEE_ADDED_AT_CHECKOUT (the buyer pays it on top) or NO_FEE (free tickets and sites that don't
+ * require a fee). Tiers are independent — fired as one parallel batch.
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/ticket-definitions-v3/create-ticket-definition.md
+ */
+export async function createTicketTiers(ctx, eventId, tiers) {
+  return Promise.all(tiers.map(async (t) => {
+    const body = (feeType) => ({
+      ticketDefinition: {
+        eventId,
+        name: t.name,
+        description: t.description,
+        ...(t.initialLimit != null ? { initialLimit: t.initialLimit } : {}),
+        pricingMethod: { fixedPrice: { value: String(t.price), currency: t.currency ?? "USD" } },
+        feeType,
+      },
+      fields: ["SALES_DETAILS"],
+    });
+    // INVALID_FEE_TYPE ("feeType=FEE_INCLUDED feeRequired=false") means this site doesn't take a
+    // fee on this tier — right after the Events app is installed the fee settings can also lag a
+    // few seconds (seen on a fresh site, 2026-09-27). So the retries change the fee type instead
+    // of re-sending the same one: the plan's (default FEE_INCLUDED), then NO_FEE, then
+    // FEE_ADDED_AT_CHECKOUT after a five-second pause for the install race. Anything else, or a
+    // third failure, throws as before.
+    const feeTypes = [t.feeType ?? "FEE_INCLUDED", "NO_FEE", "FEE_ADDED_AT_CHECKOUT"];
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const r = await req(ctx, "/events/v3/ticket-definitions", { body: body(feeTypes[attempt]) });
+        return { id: r.ticketDefinition?.id, feeType: feeTypes[attempt] };
+      } catch (e) {
+        if (!/INVALID_FEE_TYPE/.test(e.message) || attempt >= 2) throw e;
+        if (attempt === 1) await new Promise((res) => setTimeout(res, 5000));
+      }
+    }
+  }));
+}
+
+// STEP 3 — publish (one-way; for TICKETING only after its tiers exist).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/publish-draft-event.md
+export async function publishEvent(ctx, eventId) {
+  return req(ctx, `/events/v3/events/${eventId}/publish`, { body: {} });
+}
+
+// STEP 4 (optional) — group events by a format/track. Categories are the v1 API (NOT v3).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/categories/create-category.md
+export async function createEventCategories(ctx, names) {
+  const out = [];
+  for (const name of names) {
+    const r = await req(ctx, "/events/v1/categories", { body: { category: { name } } });
+    out.push({ id: r.category?.id, name });
+  }
+  return out;
+}
+
+// Assign events to a category. Path is /{categoryId}/events (NOT /assign); body key is
+// `eventId` — an ARRAY despite the singular name.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/categories/assign-events.md
+export async function assignEventsToCategory(ctx, categoryId, eventIds) {
+  return req(ctx, `/events/v1/categories/${categoryId}/events`, { body: { eventId: eventIds } });
+}
+
+// Events binds mainImage by Wix Media file ID — an external url must be imported first
+// (a raw url as the id stores 200 but renders nothing); a plan `imagePrompt` 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";
+
+// mainImage is an Image OBJECT; height/width are REQUIRED or it won't render. Events V3 uses
+// NO revision — partial PATCH keyed by event.id. Works before OR after publish.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/update-event.md
+export async function setEventMainImage(ctx, it) {
+  return req(ctx, `/events/v3/events/${it.eventId}`, {
+    method: "PATCH",
+    body: {
+      event: {
+        id: it.eventId,
+        mainImage: { id: it.id, url: it.url, height: it.height ?? 1024, width: it.width ?? 1024, altText: it.altText },
+      },
+      fields: ["DETAILS"], // mainImage reads back only under DETAILS
+    },
+  });
+}
+
+/**
+ * ONE-CALL seed: install → site currency → per event create DRAFT → tiers → publish →
+ * categories → images, ids threaded in memory. The default path.
+ */
+export async function setupEvents(ctx, { events = [], currency } = {}) {
+  // Before any event exists: a ticket tier's currency is fixed at creation.
+  if (currency) await setSiteCurrency(ctx, currency);
+  await installEventsApp(ctx);
+  const siteCurrency = currency ?? await getSiteCurrency(ctx);
+
+  const created = [];
+  for (const ev of events) {
+    const e = await createEvent(ctx, { ...ev, currency: ev.currency ?? siteCurrency });
+    if (!e.id) throw new Error(`Event "${ev.title}" was not created — no id returned.`);
+    const tiers = ev.type === "TICKETING" && ev.ticketTiers?.length
+      ? await createTicketTiers(ctx, e.id, ev.ticketTiers.map((t) => ({ ...t, currency: t.currency ?? siteCurrency })))
+      : [];
+    // The guest control goes on the draft's form before publish; a refusal leaves the event without it
+    // (the owner adds it in the dashboard) and the result says so.
+    let guestControl = false;
+    if (ev.type !== "TICKETING" && ev.guests) {
+      try { guestControl = await addGuestControl(ctx, e.id, ev.guests); }
+      catch (err) { console.error(`guest control skipped for "${ev.title}": ${err.message}`); }
+    }
+    await publishEvent(ctx, e.id);
+    created.push({ ...e, category: ev.category, imageUrl: ev.imageUrl, imagePrompt: ev.imagePrompt, ticketCount: tiers.length, feeTypes: tiers.map((t) => t.feeType), ...(ev.guests ? { guestControl } : {}) });
+  }
+
+  const names = [...new Set(created.map((e) => e.category).filter(Boolean))];
+  const categories = names.length ? await createEventCategories(ctx, names) : [];
+  for (const c of categories) {
+    const eventIds = created.filter((e) => e.category === c.name).map((e) => e.id);
+    if (eventIds.length) await assignEventsToCategory(ctx, c.id, eventIds);
+  }
+
+  // Pass 2 — images: resolve (import by url / generate by prompt) in one parallel wave, then
+  // attach. Failures leave the event text-only; the seed's exit never depends on images.
+  const files = await resolveItemImages(ctx, created.map((e) => ({
+    url: e.imageUrl,
+    path: e.imagePath,
+    prompt: e.imagePrompt,
+    displayName: `${e.slug || "event"}.png`,
+  })));
+  let imagesAttached = 0;
+  for (let i = 0; i < created.length; i++) {
+    const e = created[i];
+    if (!files[i]) continue;
+    try {
+      await setEventMainImage(ctx, { eventId: e.id, id: files[i].id, url: files[i].url, height: 1024, width: 1024, altText: e.slug });
+      imagesAttached++;
+    } catch {
+      /* never block on image failure — the event stays text-only */
+    }
+  }
+
+  return {
+    events: created.map((e) => ({ id: e.id, slug: e.slug, ticketCount: e.ticketCount, feeTypes: e.feeTypes, category: e.category ?? null })),
+    categories,
+    imagesAttached,
+    // Completing a PAID purchase needs a premium plan + a configured payment method in the
+    // dashboard — not a seeding failure; surface it to the owner. Free/RSVP need neither.
+    notes: created.some((e) => e.ticketCount > 0)
+      ? ["Paid tickets require a premium plan + a configured payment method in the dashboard to complete a purchase."]
+      : [],
+  };
+}
+
+// ---- 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-events.mjs <plan.json>   (run from the project root)");
+    process.exit(1);
+  }
+  const plan = JSON.parse(readFileSync(planPath, "utf8"));
+  const ctx = makeCtx();
+  setupEvents(ctx, plan)
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+}

package/skills/wix-headless-templates/faq/INSTRUCTIONS.md

@@ -0,0 +1,317 @@
+# FAQ — playbook
+
+The FAQ machinery ships as files — category and question reads over the Wix FAQ app (owner order,
+the Ricos answer rendered to sanitized HTML), one shared state machine for the page (category
+filter, search, the accordion, the URL), its React binding, and reference components, typed
+end-to-end. **The presentation is yours to design** on the shipped hook/DTOs: the accordion's look,
+the category nav, the search box, the FAQ page, the home page's "top questions" strip, and the brand.
+You never write FAQ data logic; you never skip designing. The vertical is **read-only** — visitors
+read; authoring stays in the dashboard.
+
+## The file map (deployed into `src/`)
+
+**On Astro and React the shipped files are tested and work as they are** — this table and the
+contracts below are everything you need to use them, so don't spend the run reading their source;
+wire them and build your surfaces. Reading them is the right move when something is off (a runtime
+error, a field this playbook doesn't cover) or when the brief wants a behaviour they don't offer —
+then read the file that owns it and change or extend it. On `lib`, `static`, and a port the hooks
+and components don't deploy at all; the store behind them does, and each wiring section below says
+how to bind it. Files you edit: `SiteLayout.astro`, `styles/global.css`, and the shipped page's
+template. Files you **create**: your accordion island (skeleton below) and your home page.
+
+| file | what it is |
+|---|---|
+| `wix/config.ts` · `wix/sdk.ts` | shared auth seam (deploy configures it — nothing to set by hand) |
+| `wix/media.ts` · `wix/money.ts` | shared helpers; an answer's inline images are already resolved https URLs inside `answerHtml` |
+| `wix/faq/types.ts` | the DTOs (`FaqCategory`, `FaqQuestion`, `FaqSection`, `FaqData`, `FaqQuestionPage`) — contracts below |
+| `wix/faq/faq.ts` | `fetchFaq` (everything the page needs), `fetchCategories`, `fetchQuestions` (one cursor page, optionally one category), `fetchQuestionById` — the transport; the rules and DTO mappers are in `faq-core.ts` beside it (shared with the REST layer) |
+| `wix/faq/faq-core.ts` | the rules: owner ordering, grouping into sections, client-side search, the deep-link spelling (`anchorId`, `faqDeepLink`, `parseDeepLink`), `faqJsonLd` (schema.org FAQPage), the Ricos-to-HTML subset, the wire spelling of a query |
+| `wix/faq/faq-store.ts` | the page's state machine, framework-free and **module-scoped** (one store per page, not per surface — the nav, the search, and the accordion share it across islands): `seedFaq`, `getFaqState`/`subscribeFaq` + actions; the hook binds it to React, every other stack uses it directly |
+| `hooks/faq/useFaq.ts` | React binding of `faq-store.ts` — contract below |
+| `components/faq/FaqAccordion.tsx` · `FaqCategoryNav.tsx` · `FaqSearch.tsx` | **reference implementations** — correct, plain, accessible; build your own instead of shipping them |
+| `styles/global.css` | **the design system**: Tailwind v4 + the `@theme` token block (shared across verticals). Everything, shipped and yours, styles from these tokens |
+
+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 another vertical is also deployed, its layout won — add an FAQ nav link there |
+| `pages/faq.astro` | SSR FAQ page — **keep the frontmatter** (the fetch, the `?category=` pre-selection, the FAQPage JSON-LD in the `seo-tags` slot); swap the island imports to YOUR components. Not a Wix item page: there is no owner-editable SEO type for FAQ, so `<title>`/description come from the layout props |
+
+## What you build — the design job
+
+1. **The accordion** — your question row (the question as the button, your open/closed affordance)
+   and answer panel (the HTML body, the per-question link) on `useFaq`, grouped under category
+   headings in owner order; skeletons while `data === null`, an honest empty state, a "no results"
+   state with a clear control while searching, an error line with retry.
+2. **The category nav + search** — pills for the categories that have questions (only when more
+   than one), "All" first; a labelled search input debounced into `setQuery`, the results count
+   announced. Three islands or one — the store is shared either way.
+3. **The FAQ page** — restyle `pages/faq.astro`'s template around your islands (heading, intro copy
+   from the brief, the islands). Keep the frontmatter.
+4. **The home page** — what the business is, and a "top questions" strip: the first few questions
+   of the first category (`fetchFaq()` in the frontmatter → your markup), each linking to
+   `faqDeepLink(q)`.
+
+Plus the **theme** (`@theme` block, one edit) and the **chrome** (`SiteLayout`, one pass). Style
+everything with Tailwind utilities on the tokens; the answer's HTML is plain tags (`p`, `h4`,
+`ul`/`ol`/`li`, `blockquote`, `pre`/`code`, `a`, `img`, `hr`, `strong`/`em`/`u`/`s`) — style them
+through descendant variants on your wrapper (`[&_p]:my-2 [&_ul]:list-disc …`), as the reference does.
+
+### What a complete FAQ shows (recommended defaults)
+
+Defaults for a brief that says nothing about them; the prompt wins where it differs. Look at the
+seeded content before designing (how many categories, how long the answers run, whether they carry
+lists or images) and design for this content, not for a stereotype of an FAQ.
+
+- **FAQ page:** the heading and one line of intro in the first screen, then the category nav (only
+  when more than one category has questions), the search, and the first questions — at 390px too;
+  the questions collapsed by default, one open at a time; a copied link reopens the same question.
+- **Search:** results as you type (debounced); the count announced; "No results for '…'" with a
+  clear control, never an empty page.
+- **Home:** the business first, then real questions under a truthful heading, each a link to
+  `/faq#q-<slug>`; not a copy of the FAQ page.
+- **Copy:** nothing the owner didn't write — no invented questions, view counts, or "popular" labels;
+  no Wix IDs or technical words in visible text.
+
+### The contracts your components consume
+
+Tested and working as they are; read the source when something is off or the brief wants more.
+
+```ts
+// FaqCategory: { id, title, sortOrder /* number | null */, questionCount /* hide empty categories with it */ }
+// FaqQuestion: { id, slug /* "" when absent */, question,
+//   answerHtml /* sanitized HTML — render via set:html / dangerouslySetInnerHTML on a wrapper */,
+//   answerText /* plain text — snippets, search, JSON-LD */,
+//   categoryId, sortOrder, shareLink /* Wix's own widget URL, "" unless asked */, labels /* not for visitors */ }
+// FaqSection: { category, questions }          // one category's questions in owner order
+// FaqData:    { categories, questions, truncated /* true → more than MAX_QUESTIONS (500) exist */ }
+
+// fetchFaq() → FaqData                          // categories (counted) + every question, owner order
+// fetchQuestions({ categoryId?, limit? /* ≤100 */, cursor? }) → { questions, nextCursor }
+// fetchCategories() → FaqCategory[]             // questionCount is 0 here; fetchFaq fills it
+// fetchQuestionById(id) → FaqQuestion | null
+
+// useFaq({ initialData?, initialCategoryId?, expandOnlyOne? /* true */, openFirst? /* false */, syncUrl? /* true */ }) →
+// { data: FaqData|null /* null = loading → skeletons */,
+//   sections: FaqSection[]        /* the VISIBLE questions grouped by category — render these */,
+//   visible: FaqQuestion[], activeCategoryId, selectCategory(id|null),
+//   query, setQuery(q), resultsCount /* visible.length while a query is typed */,
+//   expandedIds, isExpanded(id), toggleQuestion(id), expandQuestion(id), collapseAll(),
+//   loading, error, retry() }
+// One store per page: every island that calls useFaq sees the same state. Pass the page's SSR props
+// to EVERY island (the first to render seeds; the rest are no-ops) so server HTML and first paint agree.
+
+// anchorId(q) → "q-<slug || id>"                 // put it as the id of every question's wrapper
+// faqDeepLink(q, base = "/faq", categoryId?) → "/faq?category=…#q-<slug>"
+// faqJsonLd(questions, pageUrl?) → the FAQPage object (the page already emits it)
+```
+
+### The island you create — skeleton
+
+The Astro page ships; its frontmatter is machinery (SSR fetch → DTO props → islands; the JSON-LD; the
+category pre-selection) and stays as shipped. What you create is the accordion island `faq.astro`
+mounts (and your nav and search, or one island holding all three). Hooks first, branches after (an
+early return above a hook changes hook order and React throws). Islands render on the server too,
+after the 200 is sent — nothing in a render path may throw.
+
+```tsx
+// src/components/faq/<YourAccordion>.tsx — YOU build it; faq.astro mounts it (swap the import there).
+import { useFaq } from "../../hooks/faq/useFaq";
+import { anchorId, faqDeepLink } from "../../wix/faq/faq-core";
+import type { FaqData } from "../../wix/faq/types";
+
+export default function YourAccordion(props: {
+  initialData?: FaqData;              // SSR props from faq.astro — pass straight to useFaq;
+  initialCategoryId?: string | null;  // omitted in a SPA (client fetch)
+}) {
+  const { data, sections, query, setQuery, isExpanded, toggleQuestion, error, retry } = useFaq(props);
+  // …you implement the render:
+  //   • data === null → skeleton rows; data.questions.length === 0 → your honest empty state
+  //   • error → a short inline message with a retry control
+  //   • query set and sections empty → "No results for '…'" with a clear control (setQuery(""))
+  //   • else per section: the category title (an <h2>) and per question a wrapper
+  //     <div id={anchorId(q)}> holding an <h3><button aria-expanded={isExpanded(q.id)}
+  //     aria-controls={panelId} onClick={() => toggleQuestion(q.id)}>{q.question}</button></h3>
+  //     and a <div id={panelId} role="region" hidden={!isExpanded(q.id)}> with the answer:
+  //     <div dangerouslySetInnerHTML={{ __html: q.answerHtml }} /> — the ONLY HTML render — and a
+  //     link to faqDeepLink(q) (plus a "copy link" control if you like)
+  //   • data.truncated → one honest line ("Showing the first N questions")
+}
+```
+
+### The reference files for stacks where the components don't deploy
+
+On `lib`, `static`, and a port, nothing under `components/` or `hooks/` arrives. The state machine
+behind the hook does arrive — `wix/faq/faq-store.ts` — so you never rewrite it: `seedFaq(options)`
+once, `subscribeFaq`, render from `getFaqState()`, call its actions. Its `FaqState` interface is the
+render contract; read it. What you write is the rendering — the accordion, the nav, the search — and
+for that read these first; they are tested code for exactly that behaviour:
+
+1. `components/faq/FaqAccordion.tsx` — the button-in-heading + region pattern with `aria-expanded`,
+   `aria-controls` and `hidden`; the states in order (skeleton → error → empty → no results →
+   sections); the copy-link control; the truncation line.
+2. `components/faq/FaqCategoryNav.tsx` — "All" first, only categories with questions, `aria-pressed`
+   on the active pill, the `asLinks` no-JS variant.
+3. `components/faq/FaqSearch.tsx` — the 250 ms debounce with immediate flush on Enter and on clear,
+   the `aria-live` results count.
+
+All under `templates/faq/app/`.
+
+### Wiring — Astro (default)
+
+1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass — merge into the other
+   vertical's layout instead if both are deployed).
+2. Write your island(s) under `src/components/faq/` (new names — don't overwrite the references) and
+   swap the island imports in `pages/faq.astro`; restyle its template (keep the frontmatter).
+   **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 — another JS framework (`--stack lib`: Vue, Svelte, Solid, plain Vite)
+
+Read the reference files listed above before writing any surface.
+
+`deploy.mjs faq --stack lib` put the data layer in `src/wix/` and nothing else: `sdk.ts` (the
+visitor client, configured with the public client id), `media.ts`, `money.ts`, and `wix/faq/` —
+`faq.ts`, `types.ts`, `faq-core.ts`, and the store `faq-store.ts`. None of it is React. The hook and
+components don't ship on this stack; the store replaces the hook, and you write the components in
+your framework to the contracts on this page:
+
+- bind the store with your framework's external-store primitive (Vue: `shallowRef` updated in
+  `subscribeFaq`; Svelte: `readable(getFaqState(), (set) => subscribeFaq(() => set(getFaqState())))`;
+  Solid: a signal set in `subscribeFaq`). `seedFaq({ initialData? })` once when the page's data is
+  known (a SPA passes nothing and the first subscription fetches); `groupByCategory(state.data.categories,
+  state.visible)` from `faq-core` gives the sections. State in, actions out — exactly the hook's
+  contract above.
+
+Route `/faq` (`?category=` and `#q-…` are read and written by the store); dev server on 4321; a
+static build goes through `npx @wix/cli@latest release` with `site.outputDirectory` pointing at the
+build folder, an SSR build is hosted by you. Page tags from the first questions.
+
+### Wiring — static site (`--stack static`, no bundler)
+
+Read the reference files listed above before writing any surface.
+
+`deploy.mjs faq --stack static --out site` put the REST layer in `site/js/wix/` (browser ESM, the
+`.ts` beside each `.js` for reading). Everything the visitor loads lives under `site/` — pages,
+styles, `js/` — and `wix.config.json`'s `site.outputDirectory` is `"./site"`; the project root
+(config, plan, seed output) is never the upload. Same function names and DTOs as the table above,
+so the contracts on this page hold unchanged: `fetchFaq`, `fetchQuestions`, `fetchCategories`,
+`fetchQuestionById` from `./js/wix/faq.js`; `anchorId`, `faqDeepLink`, `groupByCategory` from
+`./js/wix/faq-core.js`. The state machine ships too: `seedFaq`, `subscribeFaq`, `getFaqState` and
+the actions from `./js/wix/faq-store.js` (the first `subscribeFaq` in a browser fetches when nothing
+was seeded). No components ship — you write the rendering in plain JS: one render function per
+surface that reads `getFaqState()`, called from `subscribeFaq`, with the controls calling the store's
+actions; the answer goes in through `innerHTML` (it is the core's sanitized HTML). The page is
+`faq.html` (Wix static hosting serves files, not directories — name the file and link to it).
+Structured data built in the browser is not read by search engines — an FAQ that needs the FAQPage
+markup indexed stays on Astro; say so in the closing message. Set `document.title` from the first
+questions once they load. The visitor token persists in `localStorage` on its own; never mint per
+page. `npx @wix/cli@latest release` uploads `site/`.
+
+### Wiring — server-rendered, another language (Flask, Laravel, Rails, …)
+
+Read the reference files listed above before writing any surface.
+
+Run `deploy.mjs faq --stack static` in the project folder anyway: `js/wix/` is both the browser-side
+code and the readable spec. Reads render on the server: port `js/wix/faq.ts` and `faq-core.ts` to
+your language — the same four functions returning the same DTO shapes as dicts, one anonymous
+visitor token per process for these public reads (mint and refresh per `client.ts`) — the
+Ricos-to-HTML subset ports with the core (escape text, allow only http(s) links, the node table in
+`faq-core.ts`), and the FAQPage JSON-LD is server-rendered from the same DTOs, so questions and
+answers are in the HTML. Nothing in this vertical runs on the visitor's behalf, so the browser side
+is optional: the category filter, the search, and the accordion can run client-side on
+`./js/wix/faq-store.js` exactly as the static wiring above, or as plain server routes
+(`/faq?category=<id>`, answers rendered open when there is no script). Route stays `/faq`.
+
+**Pre-rendered (Frozen-Flask, Pelican, any static-site generator) → Wix-hosted.** Same port for the
+reads, run at build time with one anonymous token — walk `fetchQuestions` by `nextCursor` until it
+is null (or call the ported `fetchFaq`). Run `deploy.mjs faq --stack static --out <build dir>` so
+`js/wix/` is inside the output the page imports from, point `site.outputDirectory` at that folder,
+`wix release`. Give the templates one base path to `js/wix/` (root-relative `/js/wix/…`), never a
+relative `./js/wix/`. The frozen page is the first paint; filter, search, and the accordion still run
+client-side on `./js/wix/faq-store.js`. Close with the live URL, the rebuild + release command, and
+one line for the owner: questions edited in the dashboard reach the site when that command runs.
+
+### 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). Route `/faq` → your islands on `useFaq()` (no `initialData` — the store
+fetches on mount and reads `?category=`/`#q-…` from the address bar). Deploy wrote the public client
+id into `wix/config.ts`; nothing else to configure.
+
+Routes on Wix hosting: the host serves files only, so a clean route answers 404 when loaded directly — hash routes, or one HTML file per route, decided before the first route is written; any URL handed to Wix as a return target must be one the host serves (SKILL.md step 1).
+
+## Hard rules
+
+- **Data only through the shipped exports** — never import `@wix/faq` in a component, never
+  re-derive a request shape; extend by adding a function in `wix/faq/` (API contracts: the
+  `wix-docs` skill).
+- **`answerHtml` is HTML, `answerText` is copy** — render the body with `set:html` /
+  `dangerouslySetInnerHTML` on a wrapper you control, and only that field; never interpolate it as
+  text, never innerHTML anything else (question, titles, labels are text).
+- **Search and category filtering are client-side over the loaded set — by design.** The API filters
+  `question` by prefix only and has no full-text search, so the whole FAQ is loaded once (capped at
+  `MAX_QUESTIONS`, 500) and filtered in the store; this is the one vertical where "page at the source"
+  does not apply. Never re-implement search against the API, never raise the cap; render
+  `data.truncated` honestly.
+- **Question and category order is the owner's** (`sortOrder`, already applied) — never sort
+  alphabetically or by length unless the brief says so.
+- **Deep links are `/faq#q-<slug>`** — every question's wrapper carries `id={anchorId(q)}`; links to a
+  question go through `faqDeepLink(q)`; never hand-build them from ids. `shareLink` is Wix's widget
+  URL, not this site's — don't surface it as the share target.
+- **The accordion is accessible by construction**: the question is a `<button aria-expanded
+  aria-controls>` inside a heading, the answer a `role="region"` panel it labels, collapsed with
+  `hidden` (still in the DOM — that is what makes the FAQPage markup honest). Never collapse by
+  unmounting the answer.
+- **Pass the page's SSR props to every island** that calls `useFaq` (the store seeds once) — an island
+  without them renders skeletons on the server and flashes on hydration.
+- Where the shipped components deploy: theme via the `@theme` tokens, your markup in Tailwind utilities
+  on the same tokens; no parallel theme files, no hardcoded palettes. Where they don't (`lib`,
+  `static`, a port): style with what your stack does well, on one token set of your own.
+- Live data or an honest empty state — never mock questions, counts, or "helpful" votes; the DTOs don't
+  carry them.
+- **Call every hook before any conditional return.** Hooks first, branches after.
+
+## Point the user to their dashboard
+
+Hand the owner this link — `{siteId}` is `siteId` in `wix.config.json` (the deploy JSON prints it as
+`dashboardUrl`).
+
+| page | `https://manage.wix.com/dashboard/{siteId}/` + |
+|---|---|
+| FAQ (categories and questions) | `app/14c92d28-031e-7910-c9a8-a670011e062d` — the app-id form, which redirects to the FAQ app's own dashboard page |
+
+Every category and question in the dashboard appears on the site; the API exposes no draft state.
+
+## Seeding
+
+Per `seed/SEED.md` — plain-data `plan.json` into `seed-faq.mjs` from the project root. Seed
+questions that exercise the UI (2–4 categories, 2–4 questions each, at least one answer with a list
+or several paragraphs). A fresh FAQ install carries Wix's sample categories and questions ("General",
+"Setting up FAQs"), and the page shows them. Never delete them, or anything else on the site: the
+result's `preexisting[]` names what is on the page, and the closing message says so with the
+dashboard link so the owner removes them there — never release a site that shows "Setting up FAQs"
+without telling the owner.
+
+## Verification caveats
+
+The FAQ API's reference exists (`https://dev.wix.com/docs/rest/business-management/faq-app/…`) and the
+shipped calls follow it: `POST /faq/v2/categories/query`, `POST /faq/v2/question-entries/query`, the
+`RICH_CONTENT` content format and the `SHARE_LINKS` field set. Not confirmed on a live site, and
+guarded in the code:
+
+- **Anonymous visitor reads.** Both endpoints carry the app's READ scope; the reference's SDK example
+  is elevated. If `fetchFaq` answers 403 for a visitor (the SSR fetch is guarded — the page then
+  renders the empty state), the read belongs behind a narrow server endpoint per
+  `templates/shared/CUSTOM_OPERATIONS.md`; on managed Astro the SSR call already runs server-side.
+- **Answer format.** A question stored as plain text may come back as `plainText` even when
+  `RICH_CONTENT` is requested; the core renders `richContent`, then `plainText`, then a minimal
+  Draft.js read (paragraphs, lists, headings — no inline styles), so every format shows something.
+- **Cursor pages of a filtered query.** Page 2 of `fetchQuestions({ categoryId })` sends the cursor
+  alone (the cursor carries the filter, as Blog's does); `fetchFaq` pages the unfiltered set, so the
+  page never depends on it.
+- **Default content on install** and a question **visibility control** (the reference's sample flow
+  mentions a `status` the entity does not expose): the seed reads before writing and reports what it
+  found; the read layer shows what the API returns.
+- **The dashboard slug** is not confirmed; the app-id link above always redirects to it.