@wix/agent-skills 1.17.0 → 1.18.0

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

@@ -0,0 +1,86 @@
+# Events — seeding
+
+Seed by **running `seed-events.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 Wix Events app if needed, resolves the site currency, and creates
+everything in the one order that works (create DRAFT → tiers → publish — the registration
+type is immutable and publishing is one-way).
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/references/events/seed/seed-events.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to 3 events** (the seed shows
+the shape; the owner adds the rest in the dashboard) and make them exercise the UI: mix
+`TICKETING` and `RSVP` (≥1 of each), give a ticketed event 2 tiers, and give every event an
+image (an events page without images looks broken) — the default is an `imagePrompt`
+(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 `imagePath` (a file on this machine — uploaded to Wix Media) or `imageUrl`
+(their own hosted URL; verify it with `curl -sI` → 200) — never a stock-photo or guessed URL. Images resolve in parallel and never block the
+seed; a failed image leaves that event text-only.
+
+```json
+{
+  "events": [
+    { "type": "TICKETING", "title": "Summer Synth Festival",
+      "shortDescription": "One night of analog sound under the stars.",
+      "startDate": "2026-11-07T03:30:00.000Z", "endDate": "2026-11-07T07:00:00.000Z",
+      "timeZoneId": "America/Los_Angeles",
+      "location": { "name": "The Echo Lot", "type": "VENUE",
+        "address": { "addressLine": "120 Harbor St", "city": "Seattle", "subdivision": "US-WA", "postalCode": "98101", "country": "US" } },
+      "ticketTiers": [
+        { "name": "General Admission", "price": "45.00", "initialLimit": 200 },
+        { "name": "Front Row", "price": "85.00", "description": "First two rows.", "initialLimit": 40 }
+      ],
+      "category": "Concerts", "imageUrl": "https://…" },
+    { "type": "TICKETING", "title": "Vinyl Mixing Workshop",
+      "shortDescription": "Hands-on turntable session, decks provided.",
+      "startDate": "2026-11-14T18:00:00.000Z", "endDate": "2026-11-14T20:00:00.000Z",
+      "timeZoneId": "America/Los_Angeles",
+      "location": { "name": "Studio B", "type": "VENUE",
+        "address": { "addressLine": "9 Pine Ave", "city": "Seattle", "subdivision": "US-WA", "postalCode": "98101", "country": "US" } },
+      "ticketTiers": [{ "name": "Workshop Seat", "price": "30.00", "initialLimit": 16 }],
+      "category": "Workshops", "imageUrl": "https://…" },
+    { "type": "RSVP", "title": "Community Listening Night",
+      "shortDescription": "Free open-deck evening — bring a record.",
+      "startDate": "2026-11-20T19:00:00.000Z", "endDate": "2026-11-20T22:00:00.000Z",
+      "timeZoneId": "America/Los_Angeles",
+      "location": { "name": "The Back Room", "type": "VENUE",
+        "address": { "addressLine": "120 Harbor St", "city": "Seattle", "subdivision": "US-WA", "postalCode": "98101", "country": "US" } },
+      "category": "Community", "imageUrl": "https://…" }
+  ]
+}
+```
+
+- `type` — `TICKETING` (paid tiers; buyers pay on Wix's hosted checkout) or `RSVP` (free;
+  the built-in name+email form — seed NO form fields). **Immutable after create** — decide
+  from the brief, never plan to convert.
+- **Dates are future ISO-8601 UTC** (`…Z`), `endDate` after `startDate`, `timeZoneId` an
+  IANA tz. A past event isn't registerable and won't show in the live listing; no date in
+  the brief → default ~60–90 days out and say so.
+- `ticketTiers` — TICKETING only, created before publish. `price` is a **decimal STRING**
+  (`"45.00"`, never a number), `name` ≤ 30 chars, omit `initialLimit` for unlimited. Tier
+  currency is the site currency (resolved automatically).
+- `location` — `{ name, type: "VENUE", address }` (address `subdivision` is ISO-3166-2 like
+  `US-WA`, `country` ISO alpha-2), `{ name, type: "ONLINE" }`, or
+  `{ locationTbd: true, name }`.
+- `category` — a name; created and assigned for you. Skip when the brief has no grouping.
+- `rsvpResponseType` — `"YES_AND_NO"` to let guests decline (default `"YES_ONLY"`).
+
+The result JSON carries a `notes` array — when any event is ticketed it reminds that
+**completing a paid purchase needs a premium plan + a configured payment method** in the
+dashboard. That's an owner step, not a seeding failure; relay it.
+
+**Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
+seems needed.
+
+## Escape hatch — individual functions
+`setupEvents` composes exported steps — `installEventsApp`, `getSiteCurrency`, `createEvent`,
+`createTicketTiers`, `publishEvent`, `createEventCategories`, `assignEventsToCategory`,
+`importImage`, `setEventMainImage`, 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-events.md`.

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

@@ -0,0 +1,276 @@
+// 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>/references/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"? }],
+//                  "category"? (name), "imageUrl"? | "imagePrompt"?, "rsvpResponseType"? }] }
+//
+// 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-events.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 EVENTS_APP_ID = "140603ad-af8d-84a5-2c80-a0f60cb47351";
+
+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;
+}
+
+// {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"
+  };
+}
+
+// ---- 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. 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 = {
+      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: t.feeType ?? "FEE_INCLUDED",
+      },
+      fields: ["SALES_DETAILS"],
+    };
+    const r = await req(ctx, "/events/v3/ticket-definitions", { body });
+    return { id: r.ticketDefinition?.id };
+  }));
+}
+
+// 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 = [] } = {}) {
+  await installEventsApp(ctx);
+  const siteCurrency = 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 })))
+      : [];
+    await publishEvent(ctx, e.id);
+    created.push({ ...e, category: ev.category, imageUrl: ev.imageUrl, imagePrompt: ev.imagePrompt, ticketCount: tiers.length });
+  }
+
+  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, 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-fast/references/forms/INSTRUCTIONS.md

@@ -0,0 +1,150 @@
+# Forms — playbook
+
+The machinery ships as files — the schema read flattened into render-ready fields, upload +
+submit, schema-driven validation, and server violations mapped onto controls, correct
+end-to-end. A form is **schema-driven**: the owner picks the fields in their dashboard, so
+every form has a different field set and no "contact form" component could ship for it.
+**You render the fields; you never write the reading, validating or submitting.**
+
+## 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 kind).
+
+| 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/forms/types.ts` | the DTOs (`FormDto`, `FormFieldDto`, `FormValues`, `FormErrors`) — contracts below |
+| `wix/forms/forms.ts` | `getForm`, `listForms` — the raw schema flattened into `FormFieldDto[]` |
+| `wix/forms/submissions.ts` | `uploadFiles`, `toSubmissionValues`, `createSubmission`, `submissionErrors`, `normalizePhone` |
+| `hooks/forms/useWixForm.ts` | the whole form as state — contract below |
+| `styles/global.css` | the design system: Tailwind v4 + the `@theme` token block (shared across verticals) |
+
+There are **no shipped components and no shipped pages** — every control is yours.
+
+## What you build — the design job
+
+Read the seed plan first: its forms and their fields are what the page renders.
+
+1. **A form surface per seeded form** — your layout, your labels' typography, your error
+   styling, mapping `form.fields` to controls. **Never name a field in code**: the owner can
+   rename, reorder, add or require one from their dashboard, and the page must follow with no
+   code change. That is the entire point of this vertical.
+2. **A success state** — the resolved `submit()` IS the confirmation (a visitor cannot read
+   submissions back). Show a thank-you; never a "check your submissions" link.
+3. **The home page and wherever the form lives** — hero, copy, the form section.
+
+Plus the **theme** (`@theme` block, one edit) and the **chrome** (`SiteLayout`, one pass).
+
+### The contracts your components consume
+
+```ts
+// FormDto — one form, ready to render
+// { id, name, fields: FormFieldDto[], submitText }   // submitText "" ⇒ write your own
+
+// FormFieldDto — one visible input, flattened (settings nest 2 levels deep upstream)
+// { target,            // the input's name, the key in values, the root of error keys
+//   label,             // never empty; rich-content labels already flattened to text
+//   control,           // text|textarea|number|rating|email|phone|url|date|time|datetime
+//                      // |select|radio|checkbox|checkboxGroup|tags|address|file|signature
+//                      // |payment|appointment|unknown
+//   required, placeholder?, description?,
+//   defaultValue,      // "" | [] | {} | the owner's prefill — already the right SHAPE
+//   choices: [{ value, label }],        // select/radio/checkboxGroup/tags — else []
+//   addressParts: [{ sub, label, required }],  // address — else []
+//   validation: { format?, minLength?, maxLength?, pattern?, minimum?, maximum?,
+//                 fileLimit?, minItems?, maxItems? },
+//   phoneCountry?,     // phone only
+//   identifier,        // TEXT_AREA, IMAGE_CHOICE, CONTACTS_EMAIL … when control isn't enough
+//   inputType, componentType }
+```
+
+```ts
+// useWixForm(formId, { initialForm? })
+// → { form,        // FormDto | null — null while loading; render a skeleton, not an empty form
+//     values,      // target → value; arrays for multi-choice/files, objects for an address
+//     setValues,   // setValues(v => ({ ...v, [target]: next }))
+//     bind,        // spread onto a text-ish control: <input {...bind(f.target)} />
+//     submit,      // onSubmit handler; resolves TRUE when the submission was created
+//     validate,    // validate(target) | validate("addr/city") | validate() for the whole form
+//     errors,      // target (or target/sub) → visitor-facing message; errors[FORM_ERROR] is form-level
+//     loading }    // loading the schema, or submitting
+```
+
+`bind` covers input / textarea / select. A **checkbox or radio group** carries `checked`
+instead of `value`, and a **file input cannot be controlled at all** — wire those by hand,
+keeping the same `name`, `onBlur: () => validate(target)` and `aria-describedby` contract.
+
+### Which control each field kind wants
+
+| `control` | render |
+|---|---|
+| `text` `email` `url` `phone` | `<input>` with the matching `type` — spread `bind` |
+| `textarea` | `<textarea>` — spread `bind` |
+| `number` `rating` | `<input type="number">`, or your own star control writing a number |
+| `date` `time` `datetime` | `<input type="date" / "time" / "datetime-local">` |
+| `select` | `<select>` over `choices` — spread `bind` |
+| `radio` | one `<input type="radio">` per choice, all sharing `name={f.target}` |
+| `checkbox` | a single `<input type="checkbox">`; its value is a **boolean** |
+| `checkboxGroup` `tags` | one checkbox per choice; the value is an **array** of chosen values |
+| `address` | one control per `addressParts` entry; the value is an **object** keyed by `sub`, and its error keys are `target/sub` |
+| `file` `signature` | `<input type="file">` (uncontrolled) — put the `File` objects in `values[target]`; the hook uploads them on submit |
+| `payment` `appointment` `unknown` | out of scope for a plain form — a payment field needs the payment flow, an appointment field needs the `bookings` vertical. Render a disabled note rather than an input that submits the wrong thing |
+
+### Wiring — Astro (default)
+
+Fetch in frontmatter so the first paint has the schema, and hand it to the island:
+
+```astro
+---
+import { getForm } from "@/wix/forms/forms";
+const form = await getForm(FORM_ID);        // FORM_ID from the seed plan
+---
+<ContactForm client:load initialForm={form} />
+```
+
+The island calls `useWixForm(form.id, { initialForm })` — no second fetch, no loading flash.
+
+### Wiring — React SPA (Vite etc.)
+
+`useWixForm(FORM_ID)` with no `initialForm`; render a skeleton while `form` is null.
+
+## Hard rules
+
+- **Never name a field in code.** Map `form.fields`. A page with `values.email` hardcoded
+  breaks the moment the owner renames or removes that field — and the owner editing fields
+  without a code change is what this vertical is for.
+- **Never build a form without reading the schema.** A hand-built `<form>` posting to Wix Data
+  or an email service silently drops real enquiries and loses the dashboard form builder,
+  spam protection, notifications and CRM contact mapping.
+- **The visitor token is enough.** Both the schema read and the submission return 200 on an
+  anonymous visitor, even though the spec lists them under owner scopes. Never add a backend,
+  a connector token, or `auth.elevate` to make a form work.
+- **Submissions are write-only from a visitor.** Reading them back genuinely 403s. If the app
+  must LIST what visitors submitted, that is the `cms` vertical.
+- **All three success statuses are a success** — `CONFIRMED`, `PENDING`, `PAYMENT_WAITING`
+  all mean the submission exists. Showing an error instead invites a second submit, and the
+  owner gets duplicates for an entry they already have.
+- **Never mock, fail loudly.** A form that cannot load is a setup problem — surface it; never
+  fall back to a hand-built form.
+
+## Point the user to their dashboard
+
+The owner edits fields, sees submissions, and sets notifications at
+`https://manage.wix.com/dashboard/<siteId>/form/forms`. Say so when you hand the site over —
+the whole value of this vertical is that their edits land on the site with no code change.
+
+## Seeding
+
+`seed/SEED.md` is the contract: a plain-data plan in, created forms out. Read it when drafting
+the plan; the seed writes the form ids your pages import.
+
+**⚠️ Build the UI only after the seed has run** — the form id comes from it, and the field set
+you are rendering is the one it created.
+
+## Verify (before declaring done)
+
+- The rendered controls match the seeded fields — same labels, same order, same required marks.
+- A submit with an empty required field shows YOUR inline message, and focus moves to it.
+- A valid submit resolves and shows the thank-you; the entry appears in the owner's dashboard.
+- Renaming a field in the dashboard changes the page on reload, with no code change.