@wix/agent-skills 1.7.0 → 1.9.0

package/skills/wix-headless/references/commands/known-apps.json

@@ -1,5 +1,6 @@
 {
   "wix-stores": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
   "wix-forms": "225dd912-7dea-4738-8688-4b8c6955ffc2",
-  "wix-blog": "14bcded7-0066-7c35-14d7-466cb3f09103"
+  "wix-blog": "14bcded7-0066-7c35-14d7-466cb3f09103",
+  "wix-gift-cards": "d80111c5-a0f4-47a8-b63a-65b54d774a27"
 }

package/skills/wix-headless/references/custom/CONNECTION_PLAN.md

@@ -0,0 +1,142 @@
+---
+name: connection-plan
+description: "Integration-mode subagent: read the brought-in site and emit the connection plan — a binding map (existing dynamic regions to wire to Wix) plus an augmentation spec (the connected component to add when the design has none). The orchestrator feeds this to the per-capability wiring subagents. Input-general: infer from the markup; a Claude-Design bundle is optional enrichment."
+---
+
+# Connection plan (integration mode)
+
+You are a planning subagent for the `wix-headless` skill's **integration mode** (`frontend = "custom"`). The user brought a finished, working site (HTML+CSS/JS) and the skill is connecting it to a live Wix backend. **Your job is to read the site and decide exactly what to connect** — you write **no code**; you return a structured plan the wiring subagents execute.
+
+## Inputs (inlined by the orchestrator)
+
+- The project's file list + the entry HTML path(s).
+- The **inferred capability set** from Discovery (e.g. `["forms"]`, `["stores"]`, `["blog","forms"]`, `["cms"]` for a client-state app).
+- The resolved **`frontendBuild`** (`none` ⇒ read rendered markup; `own` ⇒ read un-built `src/**` source). The entry-HTML shape is enough on its own (see § "What to read"), but this confirms it.
+- Whether a Claude-Design handoff bundle is present (`README.md`, `chats/`).
+
+## What to read — rendered markup OR un-built source
+
+A brought-in frontend comes in **two shapes**, and you read whichever you're given (this is input-adaptation, *not* a framework branch of the flow — the structures you emit are the same regardless of framework):
+
+1. **Rendered markup (static HTML).** The entry HTML carries real content. Read the entry HTML and any other pages. Extract: `<title>`, headings, body copy, `<form>`s, repeated element structures, and the **CSS custom-property token block** (`:root { --… }` — names + values).
+2. **Un-built SPA source.** The entry HTML is a near-empty shell — `<div id="root"></div>` + `<script type="module" src="/src/main.jsx">` — so it has **no rendered content** to detect regions in. **Read the source instead** (`src/**`: the root component, any data/store modules, `*.css`). Identify how the app **persists state today** — a `localStorage` read/write, an in-memory store, a `fetch` to a stub — and the **in-memory data shape** it keeps. This is the signal for a `persistenceSwap` (structure (c)). Detecting this is what stops an SPA from collapsing to the contact-form floor.
+3. **The handoff bundle (opportunistic, if present).** Read `chats/` and `README.md` to sharpen intent — but the plan must stand on the source/markup alone, since most inputs have no bundle.
+
+> **How do you know which shape you're reading?** If the entry HTML has a `<div id="root">`/`<div id="app">` mount + a module script pointing at `src/` and little else, it's un-built SPA source → read `src/**`. Otherwise it's rendered markup. (The orchestrator also passes the resolved `frontendBuild` — `own` ⇒ source, `none` ⇒ markup — but the markup signal alone is enough.)
+
+## Produce two structures
+
+### (a) Binding map — existing dynamic regions to wire
+
+Detect regions the design already shaped for data. **Detection ladder, highest-confidence first:**
+
+1. **Explicit annotations** — `data-wix-*`, semantic `id`/`class` (`product-grid`, `post-list`), schema.org microdata / `itemtype`.
+2. **Repetition + shape** — a container with N near-identical children, each holding image + title-like text + price-like text ⇒ a product list; N dated heading+excerpt blocks ⇒ a post list.
+3. **Form semantics** — a `<form>` with recognizable fields ⇒ a submit target.
+4. **Single-detail** — one entity's worth of fields (gallery + title + price + description) ⇒ a detail view.
+
+One entry per region:
+
+```jsonc
+{
+  "file": "index.html",
+  "anchor": "section.product-grid",     // a stable CSS selector into the existing DOM
+  "entity": "stores.products",          // stores.products | blog.posts | forms.submit | data.items | bookings.services
+  "shape": "list",                       // list | detail | single | submit
+  "template": "article.product-card",   // the repeated child to clone per result (list shapes)
+  "bindings": {                          // DOM node (relative to template) → entity field
+    "img.thumb@src": "media.mainMedia.image.url",
+    "h3.name":       "name",
+    "span.price":    "priceData.formatted.price"
+  },
+  "sampleCount": 3                        // hard-coded samples to remove after wiring
+}
+```
+
+A purely static editorial design (e.g. a wedding invitation) yields an **empty binding map** — that is expected; the augmentation spec carries it.
+
+### (b) Augmentation spec — the connected feature to ADD
+
+Per the **always-connect** rule (`INSTRUCTIONS.md` § "Always connect"), every run must end connected. If the inferred capability has no existing region to wire, emit the connected component to inject. Derive the capability from Discovery's inference; the universal floor is a Wix Forms contact/lead form.
+
+```jsonc
+{
+  "capability": "rsvp",                  // rsvp | lead | contact | (or a read capability if augmenting reads)
+  "app": "wix-forms",
+  "component": "rsvp-form",
+  "injectAt": { "file": "index.html", "anchor": "section.closing", "position": "before" },
+  "fields": [                            // becomes BOTH the Wix Form definition (seed) and the <form>
+    { "name": "fullName", "label": "Your name", "type": "text", "required": true },
+    { "name": "attending", "label": "Will you attend?", "type": "radio", "options": ["Joyfully accepts","Regretfully declines"] },
+    { "name": "guests", "label": "Number of guests", "type": "number" },
+    { "name": "dietary", "label": "Dietary notes", "type": "textarea" }
+  ],
+  "styleFrom": { "selector": ":root", "tokens": ["--terracotta","--sage","--display","--body","--label"] }
+}
+```
+
+- **`injectAt`** — pick a natural seam in the existing layout (before the closing/footer section, after the hero). Use a stable selector that exists in the markup.
+- **`styleFrom`** — list the actual CSS custom-property names you found in the site, so the wiring subagent styles the injected component to match. If the site has no `:root` tokens, list the dominant colors/fonts you observed instead.
+- Multiple capabilities → one augmentation entry each (an array).
+
+### (c) Persistence swap — replace a client-state app's data layer with a CMS collection
+
+For an **app with client/local state** (todo, notes, tracker, planner, kanban — `INSTRUCTIONS.md` § "Always connect" client-state row), the connection is neither a binding map (no rendered regions in the un-built shell) nor an augmentation (nothing to *add* — the UI exists). It is a **persistence swap**: the app's existing load/save data layer is replaced with `@wix/data`, and the in-memory shape becomes a CMS collection schema. Emit one entry per persisted entity-shape:
+
+```jsonc
+{
+  "sourceFile": "src/App.jsx",            // the file holding the data layer (where the swap is applied)
+  "dataLayer": {                            // the functions/effects to rewrite — NAME them, don't rewrite here
+    "load":  ["load() (reads localStorage 'lists')"],
+    "save":  ["useEffect persisting 'lists'", "useEffect persisting 'activeId'"],
+    "storage": "localStorage"               // localStorage | in-memory | fetch-stub
+  },
+  "inferredShape": {                        // the in-memory shape → becomes the collection schema (the seeder reads this)
+    "collection": "Todos",                  // PascalCase collection name to seed
+    "fields": [                             // name + Wix Data field type
+      { "name": "text",   "type": "text" },
+      { "name": "done",   "type": "boolean" },
+      { "name": "listId", "type": "text" }
+    ]
+  },
+  "shared": true                            // ALWAYS true — visitor token ⇒ one shared/public collection (per-user is deferred)
+}
+```
+
+- **One entry per distinct entity-shape.** A todo app with `lists` and `todos` yields **two** persistence-swap entries (a `Lists` collection: `name`; a `Todos` collection: `text`, `done`, `listId`).
+- **`dataLayer`** — *name* the functions/effects the wiring agent will rewrite (with a one-line description of what each does today); do not write replacement code (the wiring agent does that, adapting to the framework idiom).
+- **`inferredShape.fields`** — map each in-memory field to a Wix Data type (`text` | `number` | `boolean` | `datetime` | `url` | `image` | `richText` | `reference`). The **seeder** turns this into a public-read collection; the **cms wiring agent** turns the data layer into `@wix/data` `query/insert/update/remove` calls against it.
+- **`shared`** — always `true`. The visitor token gives no per-user identity, so the collection is shared/public across all visitors. The plan should also surface this in `notes[]` so the orchestrator can caveat it to the user (`INSTRUCTIONS.md` § "Scope — deferred").
+- This is **framework-blind**: a React, Vue, or Svelte SPA all produce the same `persistenceSwap` shape; only the wiring agent's idiom differs.
+
+## When detection is ambiguous
+
+Do **not** guess silently and do **not** call `AskUserQuestion`. Wire the regions you're confident about; for anything unclear, omit it from the binding map and note it in `notes[]` so the wiring subagent can leave a visible `<!-- wix: … -->` comment.
+
+**Choose the right output structure before falling through:**
+- **Un-built SPA with a client-state data layer** → emit a **`persistenceSwap`** (structure (c)). **Do NOT fall through to the contact-form floor** — that is the exact nonsense the client-state row was added to fix (a todo app is not a contact form). The persistence swap *is* the connection.
+- **Rendered markup with dynamic regions** → binding map.
+- **Static design with no dynamic region** → augmentation.
+
+Fall back to the **Forms contact-form floor** (a contact-form augmentation) only when there is genuinely **no** data layer, **no** rendered region, **and** no capability was inferred — not for a client-state SPA (see the bullet above). Never return an empty plan (no binding map AND no augmentation AND no persistence swap) — that would violate always-connect.
+
+## Return
+
+Return a single JSON object per `shared/RETURN_CONTRACT.md` conventions:
+
+```jsonc
+{
+  "status": "ok",
+  "data": {
+    "bindingMap": [ /* (a) entries, possibly empty */ ],
+    "augmentation": [ /* (b) entries — possibly empty when a persistenceSwap carries the connection */ ],
+    "persistenceSwap": [ /* (c) entries — present for client-state SPAs; empty otherwise */ ],
+    "tokens": { "--terracotta": "#B26049", "--display": "\"Cormorant Garamond\", serif" },  // resolved :root/source tokens for styling
+    "notes": [ /* ambiguous regions, omitted-but-noticed structures, the shared-data caveat for any persistenceSwap */ ]
+  }
+}
+```
+
+**Always-connect invariant:** at least one of `bindingMap`, `augmentation`, or `persistenceSwap` MUST be non-empty. (`augmentation` is no longer required ≥1 — a client-state SPA connects via `persistenceSwap` with no augmentation.)
+
+You return data only — no prose to the user, no files written.

package/skills/wix-headless/references/custom/INSTRUCTIONS.md

@@ -1,38 +1,88 @@
 ---
 name: custom-frontend
-description: "Routing target for the custom (non-astro) frontend track. Custom is any frontend the user brings that is not astro. The frontend-authoring track is NOT available yet — astro is the only supported frontend. This stub surfaces the not-available message and records the intended future shape; it does not attempt to author a site."
+description: "Frontend-track playbook for integration mode (frontend = custom). The user brings a finished, working frontend (HTML+CSS/JS from Claude Design or any tool) and asks to connect it to Wix. This track connects the site to a live Wix backend — wiring existing dynamic regions to @wix/sdk and, when the design has none, augmenting it with the connected feature its purpose implies — then publishes via a no-build wix release. Input-general: the site itself is the primary signal, never any one tool's bundle format."
 ---
 
-# Custom (non-astro) frontend — not available yet
+# Custom frontend — integration mode
 
-**Astro is the only supported frontend today.** This doc is the routing target for every non-astro `frontend` value. When the conductor routes here, it does **not** attempt frontend authoring — it surfaces the message below and stops the frontend track.
+The user already built a working website **outside** this skill (Claude Design, v0, Lovable, a static-site generator, or hand-coding) and wants it connected to Wix. The skill does **not** design or scaffold anything here — it **connects the brought-in site to a live Wix backend** and publishes it.
 
-## What to tell the user
+This is the frontend-track entry doc for `frontend = "custom"`. The **business track is unchanged** — Setup (`SETUP.md`) and Seed (`SEED.md`) run their normal frontend-blind path; only this frontend track differs from astro.
 
-> Custom (non-astro) frontends are not available yet — **astro is the supported frontend**. Re-run with the astro frontend, or check back later.
+## Two locked principles
 
-Do **not** scaffold, design, compose, or wire anything. Do **not** fall back to a half-built site. There is no per-pack custom authoring to dispatch — that work is deferred (see "Intended future shape" below).
+1. **Always connect.** Every integration run must end with the site reading from or writing to Wix. `init` + `release` of a static page with **no** backend connection is **not** an acceptable outcome — that is just hosting static HTML, which is not the point. If the design has no dynamic region to wire, **add** the connected feature its purpose implies (see § "Always connect").
+2. **Input-general.** The skill connects *whatever* the user brings — it is **not** a Claude-Design integration. The **primary signal is always the site itself** (markup, copy, CSS tokens, file/route layout), which every input has. A Claude-Design handoff bundle (`README.md` + `chats/` transcript + `project/*.html`), when present, is **opportunistic enrichment** — read it to sharpen intent inference, but never require it.
 
-## Why this is a stub
+## The technical spine (read before wiring)
 
-The frontend track is the only track that branches on the `frontend` axis (`PLAN.md` § "Two tracks"). It routes to exactly one of:
+A brought-in frontend connects to Wix with the **browser SDK + anonymous visitor session** — `createClient` + `OAuthStrategy`, no `@wix/astro`, no server runtime, no middleware. This connection model is **framework-blind**: the SDK *calls* are identical whether the brought-in frontend is loose static HTML, a Vite/React/Vue/Svelte SPA, or an already-built astro project. **How `@wix/sdk` physically reaches the page** (a CDN `<script>` vs a bundled `import`) and **how/whether the project builds** before release are *not* this file's concern — they are the **framework-build-class** (`frontendBuild`), resolved in Discovery and owned by the Build layer (`BUILD-own-build.md`). Connect never branches on framework; Build does.
 
-| `frontend` | Frontend-track instructions | Status |
-|---|---|---|
-| `astro` | `<SKILL_ROOT>/references/astro/` (full playbook) | **Supported** |
-| custom (anything else) | this file | **Not available yet** |
+The runtime shape (the static/`none` form shown; an SPA bundles the same calls instead):
 
-Astro is the one Wix-preferred frontend the skill builds end-to-end. Every other frontend is the user's own choice; standing up the authoring track for those is deferred until the custom track is prioritized.
+```html
+<script type="module">
+  import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk";
+  import { submissions } from "https://esm.sh/@wix/forms";   // or @wix/stores, @wix/blog, @wix/data
+  const wix = createClient({
+    modules: { submissions },
+    // clientId === appId from wix.config.json (init sets WIX_CLIENT_ID = appId)
+    auth: OAuthStrategy({ clientId: "<appId from wix.config.json>" }),
+  });
+  // OAuthStrategy mints + caches visitor tokens in the browser — no cookie plumbing of our own.
+  // …read (queryProducts / queryPosts / query items) or write (createSubmission) against Wix.
+</script>
+```
 
-## Intended future shape (documented, not built)
+This covers reads (products, posts, CMS items) **and** writes (form submissions) and cart-via-redirect. The published origin is already allow-listed on the OAuth app by `init`, so the visitor flow works from the deployed URL with no extra call.
 
-When the custom track is prioritized, it will follow the premise below. **None of this runs today** — it is recorded here as the target so the eventual build has a spec.
+> **How `@wix/sdk` reaches the page differs per framework-build-class** (CDN `esm.sh` for `none`; bundled `npm import` for `own`) — but that mechanic is the Build layer's concern (§ "The technical spine" above). Either way the `clientId`/`appId` is inlined from `wix.config.json` (no `WIX_CLIENT_ID` env at runtime).
 
-1. **Scaffold** — `npm create @wix/new@latest init` wraps the user's *existing* project (vs `headless` for astro), writes `wix.config.json`, and sets `site.outputDirectory` to the directory containing the entry file. (`wix release` is framework-tolerant via `wix.config.json.site.outputDirectory`.)
-2. **Business track (shared, frontend-blind)** — Setup (app installs from a project analysis, `env pull` if needed) and Seed run the **same** frontend-blind path as astro. Per the two-track model, a product/collection/post/form is the same regardless of what renders it, so this track does not change for custom.
-3. **Frontend authoring (the deferred new work)** — per-pack wiring guides under `references/custom/<pack>/…` that inject `@wix/sdk` calls into the user's existing files, **additive-only**, via a heuristic inject-point ladder: explicit `data-wix-*` attribute → semantic class → return a recommendation rather than guessing. This is what the custom track delivers when it is built.
-4. **Release** — `npx @wix/cli@latest release` directly, **no build** (the user's project is published as-is, or the user runs their own build first).
+## The flow
 
-### Historical reference
+The conductor interleaves these; the business track (steps 3–5) runs frontend-blind, concurrent with the connection-plan pass (step 2).
 
-The retired "Integrate" (Path B) flow — `SETUP.md` § "Existing project flow" E1–E6, especially the **E4 SDK-wiring recipe** — is the closest prior art for step 3 above. It is kept as a **historical reference only**, not a Beta deliverable. Do not dispatch it; the conductor no longer routes non-astro frontends into it.
+1. **Discovery (already done by the conductor).** `DISCOVERY.md` parsed the site, inferred the **domain**, derived the Wix **capability + apps**, and got approval. The resolved capability list + the site's file/token map arrive here.
+2. **Connection plan** — **for `none`, first rename the entry HTML to `index.html`** if it isn't already (Wix serves `index.html` at the site root; any other name publishes but errors at runtime — `BUILD-own-build.md` § "connect × none" owns the rule; do it before this plan so the binding map keys on `index.html`). Then read the site and emit the binding map (existing dynamic regions) + the augmentation spec (the connected component to add). See `references/custom/CONNECTION_PLAN.md`.
+3. **Init** — `npm create @wix/new@latest init` <!-- REVIEW: verify this command/subcommand syntax against the current Wix CLI — `npm create @wix/new@latest` may not take an `init` positional. Left unchanged pending check. --> (non-interactive when logged in) writes `wix.config.json` (`Site`, `appId`, `siteId`, `site.outputDirectory`). **Point `outputDirectory` at the dir that holds the deployable** — for `none` that's where the brought-in `index.html` lives; for `own` it's the project's build output (`dist/`), set after the build. (Init defaults it to `./dist`; the framework layer fixes it — `BUILD-own-build.md`.) Source files untouched at this step.
+4. **Setup (shared business track, `SETUP.md`)** — install the inferred apps (app-install curl, with `x-wix-request-id` capture per the project policy). **Skip** `env pull` (integration inlines `appId` from `wix.config.json` — no `WIX_CLIENT_ID` needed; the `init` project has no `env` command). The per-pack `npm install` decision is framework-keyed (see § "The technical spine"): `none` skips it (CDN imports); `own` instead `npm install`s `@wix/sdk` + the capability modules so the bundler includes them.
+5. **Seed (shared business track, `SEED.md`) — DISPATCH seeders as subagents.** Same per-pack dispatch model as astro: one seeder subagent per capability with a seed recipe, fired as a concurrent background batch. Each creates the backend its capability needs — the **Wix Form definition** (forms), a **CMS collection + items** (cms), sample products/posts (stores/blog) — and returns the IDs / form IDs. **Do not seed inline:** the seeder count scales with the brought-in site's content (unpredictable), so inlining serializes the work and bloats the orchestrator context. Seeded IDs flow into wiring.
+6. **Wiring — writer count is a RUNTIME decision keyed on file topology.** Each capability's `references/custom/<capability>/WIRING.md` is the how-to (wire existing regions to `@wix/sdk` reads, and inject the connected component — e.g. an RSVP `<form>` → `@wix/forms createSubmission` — styled from the design's CSS tokens; additive, never restructure). But **how many writers run depends on whether capabilities share a file**: a single brought-in `index.html` carrying several capabilities (a form *and* a feedback list) must be wired by **one writer** (inline or a single subagent handling all of them) — **never parallel agents on the same file**, or they clobber each other and double the SDK bootstrap. Only capabilities mapping to *distinct* files may be wired by parallel subagents. (Contrast with **seeding**, which always dispatches — backend work, no shared file.)
+7. **Release** — the **shared release tail** (`BUILD.md` § "Shared release tail"). Whether a build runs first is framework-keyed (see § "The technical spine"): `none` has no build (the static `outputDirectory` is already the deployable — run `npx @wix/cli@latest release` directly); `own` runs the project's own `npm run build` first, then points `outputDirectory` at the build output, then releases. **Never `wix build`** — that is astro-only. Extract the published URL from `Site published on <url>`; retry transient release errors serially (`references/shared/PRODUCTION_SHARP_EDGES.md`). Emit the production + dashboard URLs.
+
+## Always connect: design intent → Wix capability
+
+`DISCOVERY.md` infers the domain and picks the capability; this table is the shared source of truth. **Wix Forms is the universal floor** — when nothing richer fits, a domain-appropriate form is the minimum viable connection.
+
+| Inferred domain | Connected feature (wire and/or add) | App(s) | Wiring guide |
+|---|---|---|---|
+| Wedding / event invitation | **RSVP form** (+ optional responses CMS) | Wix Forms (+ CMS) | `custom/forms/WIRING.md` |
+| Store / product mock | product catalog (wire existing grid) | Wix Stores + eCom | `custom/stores/WIRING.md` |
+| Blog / publication | post list + detail (wire existing) | Wix Blog | `custom/blog/WIRING.md` |
+| Salon / spa / studio / coach landing | services list + availability + book (Wix-hosted bookings checkout) | Wix Bookings | `custom/bookings/WIRING.md` |
+| Restaurant / venue landing | reservation / contact form; optional menu CMS | Wix Forms (+ CMS) | `custom/forms/WIRING.md` |
+| SaaS / product landing | lead / waitlist signup form | Wix Forms | `custom/forms/WIRING.md` |
+| Portfolio / agency | contact form; optional projects CMS | Wix Forms (+ CMS) | `custom/forms/WIRING.md` |
+| **App with client/local state** (todo, notes, tracker, planner, kanban — typically a framework SPA persisting to `localStorage`/in-memory) | **persist its state to a Wix CMS collection** (`@wix/data`); the collection schema mirrors the app's in-memory data shape. **The anonymous visitor token gives no per-user identity ⇒ the collection is shared/public** (every visitor reads/writes the same data, not per-user, not cross-device-isolated); tell the user plainly. True per-user storage needs member auth, which is **deferred** (§ "Scope — deferred"). | Wix CMS (Wix Data) | `custom/cms/WIRING.md` § "Framework SPA — persistence swap" |
+| Anything else | contact form (the floor) | Wix Forms | `custom/forms/WIRING.md` |
+
+> **Reconciling "connect, don't design."** Augmentation injects the **one connected component** the backend connection requires (an RSVP/lead/contact `<form>`), styled from the design's tokens so it reads as native. It does **not** redesign or re-lay-out the site. "Connecting the dots" includes adding the one dot the design omitted.
+
+> **Three connection kinds, not two** (this is a connection-*model* distinction — what to connect — not a framework fork). Beyond **wire an existing region** (swap the data source behind dynamic markup) and **augment with a component** (inject the one connected feature a static design omits), an **app with client/local state** needs a third: **persistence swap.** Such an app already *has* a working data layer (e.g. `localStorage` or in-memory state); the connection **replaces that layer with `@wix/data`** — the UI, component tree, and styling are untouched; only the load/save functions change. A todo app is not "anything else → contact form" (nonsense) — it is a persistence swap onto a CMS collection. The connection planner emits this as a `persistenceSwap` structure (`CONNECTION_PLAN.md` § "(c) Persistence swap"); the cms wiring agent executes it (`custom/cms/WIRING.md` § "Framework SPA — persistence swap"). *How* the swap is mechanically applied (CDN `<script>` vs bundled source) is the Build layer's concern (§ "The technical spine"). The resulting collection is **shared/public** — see the client-state row in the table above for the per-user caveat to surface to the user.
+
+## Wiring discipline (applies to every `custom/<cap>/WIRING.md`)
+
+- **Additive only.** Never restructure the user's layout or CSS. Swap the *data source* behind a region; inject new components self-contained. For a persistence swap, change only the load/save functions — leave the component tree and styling untouched.
+- **Style from the design's tokens.** Read the site's CSS custom properties (`:root { --… }`) and reuse them verbatim in any injected component so it looks designed-in.
+- **Inline `appId` literally** from `wix.config.json` as the `OAuthStrategy` `clientId`. No env vars at runtime.
+- **The wiring *mechanic* is framework-keyed** (CDN `<script>` for `none`, bundled `import` + source edit for `own`) — the Build layer's concern, not fixed here (see § "The technical spine"). The per-capability guides describe the SDK *call shapes* (framework-blind); the Build cell decides the injection form. (For `none`: one `<script type="module">` per capability, or a shared client bootstrap + per-region render calls.)
+- **Guard every SDK call** in try/catch. On a read error, leave the original sample markup visible; the injected component degrades gracefully if the backend is unreachable.
+
+## Scope — deferred (tell the user plainly when relevant)
+
+- **Member authentication** (login/logout, member-gated content, **per-user data isolation**) — needs the server OAuth callback routes `@wix/astro` provides; not possible on a pure static/SPA client. Consequence for client-state apps: the persistence-swap collection is shared/public (per-user is the deferred member-auth follow-on) — see the client-state row in the "Always connect" table for the caveat to surface.
+- **SSR cart/session persistence across reload** — client-side cart works via `@wix/ecom` + checkout redirect; cookie-backed persistence needs the server runtime.
+- **`auth.elevate` CMS queries** — elevation needs the app secret (server-only). CMS integration is **public-read + visitor-write collections only**.
+- **Full re-design / re-layout** — out of scope; augmentation adds one connected component, never a redesign.
+- **SSR frameworks the user hand-wrote** (Next.js / Nuxt / Remix and other server-rendered frameworks) — deferred; `wix release` uploads a static `outputDirectory`, and SSR needs a runtime host this track doesn't provide. **Pure client-build SPAs (Vite + React/Vue/Svelte and similar — `frontendBuild: own`) ARE supported** — bundled `@wix/sdk`, source-edit wiring, and the project's own `npm run build` before release, all the Build layer's concern (see § "The technical spine"). Connect stays framework-blind; the framework-build-class is what differs.
+- **Custom domains** — out of scope; the skill releases to the default `*.wix-site-host.com` origin (which `init` already allow-lists). Attaching a custom domain later requires registering the new origin on the OAuth app separately — the skill does not do this.

package/skills/wix-headless/references/custom/blog/WIRING.md

@@ -0,0 +1,52 @@
+---
+name: custom-blog-wiring
+description: "Integration-mode wiring subagent for the blog capability. Connects a brought-in static site's article markup to Wix Blog — replaces hard-coded post cards/snippets with live @wix/blog queries, rendered into the existing DOM template, client-side via @wix/sdk from CDN. Ricos rich content rendered to HTML on the client."
+---
+
+# Blog wiring (integration mode)
+
+You wire the **blog capability** into a brought-in static site (`frontend = "custom"`). Replace hard-coded post snippets with live `@wix/blog` posts, rendering into the existing markup. Client-side vanilla JS, `@wix/sdk` from CDN, no build. Read `INSTRUCTIONS.md` § "The technical spine" + § "Wiring discipline", and `references/custom/stores/WIRING.md` § "The read-and-render pattern" — blog reuses it; only the entity differs.
+
+## Inputs
+
+- **`appId`** — `OAuthStrategy` `clientId`.
+- **Binding-map entries** for `blog.posts` (list and/or `detail`).
+- **Seeded post IDs/slugs** (from Seed).
+
+## List
+
+```html
+<script type="module">
+  import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk@1";
+  import { posts } from "https://esm.sh/@wix/blog@1";
+
+  const wix = createClient({ modules: { posts }, auth: OAuthStrategy({ clientId: "REPLACE_WITH_APP_ID" }) });
+
+  const list = document.querySelector("[data-blog-list], .post-list");   // binding-map anchor
+  const tpl  = list?.querySelector(".post-card");                         // binding-map template
+  if (list && tpl) {
+    try {
+      const { posts: items } = await wix.posts.queryPosts().limit(10).find();
+      const proto = tpl.cloneNode(true);
+      list.replaceChildren(...items.map((post) => {
+        const card = proto.cloneNode(true);
+        const t = card.querySelector(".title");   if (t) t.textContent = post.title ?? "";
+        const ex = card.querySelector(".excerpt"); if (ex) ex.textContent = post.excerpt ?? "";
+        const link = card.querySelector("a");      if (link && post.slug) link.href = `/post/${post.slug}`;
+        const img = card.querySelector("img");     if (img && post.media?.wixMedia?.image) img.src = post.media.wixMedia.image.url ?? img.src;
+        return card;
+      }));
+    } catch (err) { console.error("[wix-blog] post query failed:", err); }
+  }
+</script>
+```
+
+Apply the binding-map's actual selectors/field paths.
+
+## Detail + Ricos
+
+For a `detail` region (slug from `location.pathname`): `wix.posts.getPostBySlug(slug)` (or `queryPosts().eq("slug", slug)`), bind title/date, and render the post's **rich content**. Ricos content (`post.richContent`) is a structured document — render it to HTML client-side with `@wix/ricos` (`import { RicosViewer } from "https://esm.sh/@wix/ricos@1"` is React-based; for a no-framework site prefer the post's pre-rendered HTML field when available, else mount a minimal Ricos-to-HTML conversion). If rich rendering is heavy for a static site, bind the post's plain `contentText`/HTML excerpt and link out. **Note this tradeoff in the return.**
+
+## Discipline & return
+
+Additive; render into the existing template; inline `appId`; guard calls (samples are the fallback). Return per `shared/RETURN_CONTRACT.md`: files edited, anchors wired, whether full Ricos or excerpt rendering was used.

package/skills/wix-headless/references/custom/bookings/WIRING.md

@@ -0,0 +1,146 @@
+---
+name: custom-bookings-wiring
+description: "Integration-mode wiring subagent for the bookings capability. Wires a services list + availability + a schema-driven booking form into a brought-in site, then books via the ecom Cart V2 sequence (createBooking → cart → placeOrder / hosted-checkout redirect). Client-side @wix/sdk; no server runtime, no confirmBooking."
+---
+
+# Bookings — integration wiring (own / static)
+
+You wire the **bookings capability** into a brought-in site (`frontend = "custom"`).
+Client-side `@wix/sdk` — CDN imports for `none`-build, bundled for `own`-build
+(same calls). Read `INSTRUCTIONS.md` § "The technical spine" + § "Wiring discipline".
+
+> **The logic is shared.** The step model, the booking SDK sequence, the
+> schema-driven form, and the gotchas are in `../../bookings/FLOW.md` — read it
+> first. The astro vertical's React examples
+> (`../../astro/templates/bookings/*` incl. `bookingDriver.ts`) are the reference
+> implementation; here you run the **same SDK calls** through an `OAuthStrategy`
+> visitor client (adapt the React idiom to whatever framework the site uses).
+
+> **Scope (same as the astro vertical — the astro/own distinction collapses).**
+> Services display + a week-calendar availability picker + a schema-driven booking
+> form + the **ecom Cart V2 booking sequence**, all client-side under the visitor
+> identity (no server elevation): `createBooking` (→ `CREATED`) → `createCart` →
+> `calculateCart` → `isCheckoutRequired ? ecomCheckout redirect : placeOrder`.
+> **No `confirmBooking`** — the cart holds the seat, so a client-only site
+> completes the whole flow.
+
+## Inputs (inlined in your prompt)
+- **`appId`** — `OAuthStrategy` `clientId`.
+- **Seeded services** — read your `bookings` slice from `.wix/seeded.json`.
+- The site's CSS token names (style additively from them).
+
+## The client (acquire once)
+```js
+import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk@1"; // bundled for own-build
+import { services, availabilityTimeSlots, eventTimeSlots, bookings } from "https://esm.sh/@wix/bookings@1";
+import { forms } from "https://esm.sh/@wix/forms@1";
+import * as cartV2 from "https://esm.sh/@wix/auto_sdk_ecom_cart-v-2@1";
+import { redirects } from "https://esm.sh/@wix/redirects@1";
+
+const wix = createClient({
+  modules: { services, availabilityTimeSlots, eventTimeSlots, bookings, forms, redirects, ...cartV2 },
+  auth: OAuthStrategy({ clientId: "REPLACE_WITH_APP_ID" }),
+});
+```
+
+## Render services
+```js
+// The filter MUST include appId; pass conditionalFields, then .find().
+const BOOKING_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+const { items } = await wix.services.queryServices({
+  query: { filter: { appId: BOOKING_APP_ID }, paging: { limit: 100 } },
+  conditionalFields: ["STAFF_MEMBER_DETAILS"],
+}).find();
+const visible = items.filter((s) => !s.hidden);
+// name s.name · tagline s.tagLine · slug s.mainSlug?.name ·
+// duration s.schedule?.availabilityConstraints?.sessionDurations?.[0] ·
+// price s.payment?.fixed?.price ({ value, currency } — value is a string).
+```
+
+## Availability (week calendar)
+Render a **week calendar** (day strip → the day's times), not a flat grid — see
+`../../bookings/FLOW.md` § 5. `fromLocalDate`/`toLocalDate` are **local** strings
+(`YYYY-MM-DDThh:mm:ss`, no `Z`) + a `timeZone`.
+```js
+// APPOINTMENT — serviceId is a single GUID STRING:
+const a = await wix.availabilityTimeSlots.listAvailabilityTimeSlots({ serviceId, fromLocalDate, toLocalDate, timeZone, bookable: true, cursorPaging: { limit: 100 } });
+// slots a.timeSlots[] — localStartDate/localEndDate/scheduleId at the TOP level.
+// CLASS — different namespace, PLURAL serviceIds; slots carry eventInfo.eventId, no scheduleId:
+const c = await wix.eventTimeSlots.listEventTimeSlots({ serviceIds: [serviceId], fromLocalDate, toLocalDate, timeZone, includeNonBookable: false });
+```
+
+## Booking form — schema-driven
+The booking form is a `@wix/forms` form on the service (`service.form._id`). Read
+its schema and render fields by `componentType`, collecting values keyed by
+`target` (`../../bookings/FLOW.md` § 4):
+```js
+const { form } = await wix.forms.getForm(service.form._id);
+const RENDERABLE = ["TEXT_INPUT", "PHONE_INPUT", "DROPDOWN"];
+const fields = (form.formFields ?? []).filter(
+  (f) => f.fieldType === "INPUT" && !f.hidden &&
+         RENDERABLE.includes(f.inputOptions?.stringOptions?.componentType),
+);
+// render each by f.inputOptions.stringOptions.componentType; collect values by f.inputOptions.target.
+// SKIP complex object-valued fields (e.g. multi-line ADDRESS, no string componentType) —
+// sending a string for them fails createBooking with "must be object". Only
+// first_name/last_name/email are enforced, so skipping optional complex fields is safe.
+```
+
+## Book — the ecom Cart V2 sequence
+Mirror `../../astro/templates/bookings/bookingDriver.ts` (the exact payloads).
+Run the same sequence through `wix.*`; the cart holds the seat, so no elevation.
+```js
+const BOOKING_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+const STAFF_MEMBER_RESOURCE_TYPE_ID = "1cd44cf8-756f-41c3-bd90-3e2ffcaf1155";
+
+// Build the slot. APPOINTMENT carries scheduleId; CLASS carries eventId (Wix
+// derives the rest). No staff chosen → the ANY_RESOURCE fallback.
+const slot =
+  slotType === "CLASS"
+    ? { serviceId, eventId, timezone }
+    : {
+        serviceId, scheduleId, startDate, endDate, timezone,
+        resourceSelections: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, selectionMethod: "ANY_RESOURCE" }],
+        location: { locationType: "OWNER_BUSINESS" },
+      };
+
+// selectedPaymentOption must match the service: online-only → ONLINE,
+// in-person-only → OFFLINE, else ONLINE. DERIVE it — do not hardcode ONLINE: a
+// free / pay-in-person service booked ONLINE is rejected by the cart with
+// INSUFFICIENT_INVENTORY (it's the only service kind that reaches placeOrder).
+const o = service.payment?.options;
+const selectedPaymentOption =
+  o?.online && !o?.inPerson ? "ONLINE" : !o?.online && o?.inPerson ? "OFFLINE" : "ONLINE";
+
+// 1. createBooking → CREATED. Arg 1 is the BOOKING object (slot nested under
+//    bookedEntity); formSubmission/sendSmsReminder go in the options arg.
+const { booking } = await wix.bookings.createBooking(
+  { selectedPaymentOption, totalParticipants: 1, bookedEntity: { slot } },
+  { formSubmission, sendSmsReminder: true }, // formSubmission keyed by each field's `target`
+);
+// 2. createCart — one catalog item per booking._id, catalogReference.appId = BOOKING_APP_ID, channel WEB.
+const cart = await wix.createCart({ catalogItems: [{ quantity: 1, catalogReference: { catalogItemId: booking._id, appId: BOOKING_APP_ID } }], cart: { source: { channelType: "WEB" } } });
+// 3. calculateCart → { cart, summary }, then compute the checkout decision.
+const { cart: calc, summary } = await wix.calculateCart(cart._id);
+const checkoutRequired =
+  service.bookingPolicy?.cancellationFeePolicy?.enabled
+    ? true
+    : Number(summary?.priceSummary?.total?.amount ?? 0) === 0
+      ? false
+      : calc?.lineItems?.[0]?.paymentConfig?.paymentOption !== "FULL_PAYMENT_OFFLINE";
+// 4. paid → redirect (ecomCheckout.checkoutId = cartId) ; free/offline → placeOrder.
+if (checkoutRequired) {
+  const { redirectSession } = await wix.redirects.createRedirectSession({ ecomCheckout: { checkoutId: cart._id }, callbacks: { postFlowUrl: window.location.href } });
+  window.location.href = redirectSession.fullUrl;
+} else {
+  await wix.placeOrder(cart._id); // booked — no redirect
+}
+```
+
+> Confirm the `@wix/auto_sdk_ecom_cart-v-2` function registration shape on a
+> CDN/own client at wiring time; the payloads above match the astro `bookingDriver.ts`.
+
+## Out of v1
+Waitlist and on-site manage/cancel — out of scope (same as the astro vertical).
+Show bookable slots only; post-booking self-service is handled by the Wix-hosted
+flow / member area.

package/skills/wix-headless/references/custom/cms/WIRING.md

@@ -0,0 +1,97 @@
+---
+name: custom-cms-wiring
+description: "Integration-mode wiring subagent for the cms capability. Connects a brought-in static site's repeated content (portfolio items, team, FAQ, resources) to a Wix CMS (Wix Data) collection — live queries rendered into the existing DOM template, client-side via @wix/sdk from CDN. PUBLIC-READ collections only (no auth.elevate on a static site)."
+---
+
+# CMS wiring (integration mode)
+
+You wire the **cms capability** into a brought-in (`frontend = "custom"`) frontend. There are **two shapes**, keyed on `frontendBuild` (the *mechanic* is the Build layer's call — `BUILD-own-build.md` § "Wiring cell"; this guide gives the SDK call shapes for both):
+- **Static HTML (`none`)** — replace hard-coded repeated content (portfolio grid, team list, FAQ, resource cards) with live `@wix/data` collection items rendered into the existing markup. Client-side vanilla JS, `@wix/sdk` from **CDN**, no build. (§ "List" below.)
+- **Framework SPA (`own`)** — a **persistence swap**: rewrite the app's source data layer (or write a fresh data module) to call `@wix/data`, `@wix/sdk` **bundled** via `npm`. (§ "Framework SPA — persistence swap" below.)
+
+Read `INSTRUCTIONS.md` § "The technical spine" + § "Wiring discipline", and `references/custom/stores/WIRING.md` § "The read-and-render pattern" — the static cms path reuses it.
+
+> **Public-read collections ONLY.** A static site has no server, so **`auth.elevate` is not available** — it needs the app secret. The seeded collection MUST have **public read** permission for anonymous visitors, and integration-mode CMS is **read-only on the client** (visitor writes only via Forms). Seed sets the collection's read permission to public; if a collection isn't public-readable, the query returns nothing — surface that, don't try to elevate.
+
+## Inputs
+
+- **`appId`** — `OAuthStrategy` `clientId`.
+- **Binding-map entries** for `data.items`: `{ anchor, template, bindings }` + the **`collectionId`** (from Seed).
+- **Seeded `collectionId` + `itemIds`**.
+
+## List
+
+```html
+<script type="module">
+  import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk@1";
+  import { items } from "https://esm.sh/@wix/data@1";
+
+  const wix = createClient({ modules: { items }, auth: OAuthStrategy({ clientId: "REPLACE_WITH_APP_ID" }) });
+
+  const COLLECTION = "REPLACE_WITH_COLLECTION_ID";
+  const grid = document.querySelector("[data-cms-list], .portfolio-grid");   // binding-map anchor
+  const tpl  = grid?.querySelector(".item-card");                            // binding-map template
+  if (grid && tpl) {
+    try {
+      const { items: rows } = await wix.items.query(COLLECTION).limit(50).find();
+      const proto = tpl.cloneNode(true);
+      grid.replaceChildren(...rows.map((row) => {
+        const card = proto.cloneNode(true);
+        // bind by the binding-map field paths (collection field keys)
+        const title = card.querySelector(".title"); if (title) title.textContent = row.title ?? "";
+        const img = card.querySelector("img");       if (img && row.image) img.src = row.image;
+        const body = card.querySelector(".body");    if (body) body.textContent = row.description ?? "";
+        return card;
+      }));
+    } catch (err) { console.error("[wix-data] collection query failed:", err); }
+  }
+</script>
+```
+
+Apply the binding-map's actual selectors and the seeded collection's actual field keys. The `items` API is the `items` named export of `@wix/data` (CDN-pinned in the snippet above) — `items.query/insert/update/remove` plus the `bulk*` helpers. (See the import callout under § "Framework SPA — persistence swap" for the package rule.)
+
+## Framework SPA — persistence swap (`frontendBuild: own`)
+
+When the brought-in (or scaffolded) frontend is a **client-build SPA** with a client-state data layer, the connection is a **persistence swap**, not a `<script>` injection: you **rewrite the source data layer** to call the Wix Data `items` API. The SDK is **bundled** (the app `npm install`ed `@wix/sdk @wix/data`), so you `import` it — **never the CDN `esm.sh` form**. The component tree, JSX, and styling are untouched; only the load/save functions change. This dispatch is keyed on the connection plan's `persistenceSwap` entries (`CONNECTION_PLAN.md` § "(c)"), one per `sourceFile`.
+
+> **Shared/public collection — say so.** The visitor token gives no per-user identity, so the collection is **shared across all visitors** (not per-user, not cross-device). The collection is seeded **public-read + visitor-write**; surface the shared-data caveat (the orchestrator already told the user). Per-user storage needs member auth — deferred.
+
+**Inputs:** `persistenceSwap` entries (`{ sourceFile, dataLayer: {load, save}, inferredShape }`), the seeded `collectionId` per entity-shape, and `appId`.
+
+> **Items API: `import { items } from "@wix/data"`.** The Wix Data items API is the `items` named export of **`@wix/data`** (`items.query/insert/update/remove`, `items.bulk*`). Import it, elevate via `createClient({ modules: { items } })`, and call `wix.items.*`. **Do not** import a namespace from `@wix/wix-data-items-sdk` — `@wix/data` is the single documented package the whole skill uses (`references/astro/cms/CMS_FOUNDATIONS.md`, `SETUP.md`).
+
+> **🛑 `update()` REPLACES the whole item — it does NOT patch.** Per the [docs](https://dev.wix.com/docs/sdk/business-solutions/data/items/introduction): *"Updating a data item replaces the existing item entirely. If the existing item had fields with values and those fields aren't included in the updated item, the values in those properties are lost."* So `update(COLLECTION, { _id, done })` **wipes `text`, `listId`, and every other field** — the classic "toggling done erases the name" bug. **Always send the FULL item** on `update`. A client-state SPA already holds the whole record in memory — pass all of it. (Same footgun the images phase documents for the REST `PUT` — `images/INSTRUCTIONS.md` § "CMS Items".)
+
+**The bundled client + CRUD call shapes** (framework-blind — adapt the *idiom* to React/Vue/Svelte, the calls are identical):
+
+```js
+import { createClient, OAuthStrategy } from "@wix/sdk";        // bundled import — NOT esm.sh
+import { items } from "@wix/data";                            // Wix Data items API (query/insert/update/remove/bulk*)
+
+const wix = createClient({ modules: { items }, auth: OAuthStrategy({ clientId: "REPLACE_WITH_APP_ID" }) });
+const COLLECTION = "REPLACE_WITH_COLLECTION_ID";
+
+// load()  — was: read localStorage / in-memory
+export const load = async () => {
+  const { items: rows } = await wix.items.query(COLLECTION).limit(100).find();
+  return rows;                       // map _id ↔ the app's id field as the app expects
+};
+// create — was: push to array + persist
+export const add    = (item)      => wix.items.insert(COLLECTION, item);            // returns the created item (has _id)
+// update — FULL REPLACE: pass the ENTIRE item, not just the changed field(s)
+export const update = (item)      => wix.items.update(COLLECTION, item);            // item MUST carry _id + every field to keep
+// delete — was: filter out + persist
+export const remove = (id)        => wix.items.remove(COLLECTION, id);
+```
+
+> **Partial update?** If you only have the id + the one changed field (not the full record), use **`items.bulkPatch(COLLECTION, [id]).setField("done", value).run()`** — `bulkPatch` modifies *only* the named fields and leaves the rest intact (unlike `update`). For the common SPA case the full record is already in state, so a full `update(item)` is simpler and correct.
+
+**Two operations, same call shapes:**
+- **connect × own** — *rewrite* the existing data layer in `persistenceSwap.sourceFile`: replace the named `load`/`save` functions/effects with the calls above. Keep the app's existing call sites and state shape; only the bodies change. Map the app's `id` to Wix Data's `_id`. **On every update/toggle, send the full item** (read it from local state and spread all fields) — never `{ _id, oneField }`.
+- **create × own** — *write a fresh* data module (e.g. `src/wixData.js`) exposing the `load`/`add`/`update`/`remove` surface the generated components import. No archaeology — the skill controls the source.
+
+**Local-state vs `@wix/data` sync** (optimistic local update + async write-through, vs read-through on every change) is a **per-app judgment the wiring agent makes at runtime** — not a pattern this guide prescribes. Pick what fits the app; keep edits surgical and diffable.
+
+## Discipline & return
+
+Additive; for static (`none`) render into the existing template, for SPA (`own`) rewrite only the data-layer functions; inline `appId` + `collectionId`; guard calls; **public-read only** (no elevate). Return per `shared/RETURN_CONTRACT.md`: files edited, the connection kind (`binding` | `persistenceSwap`), `collectionId`(s), and a flag if the collection wasn't public-readable.