@wix/agent-skills 1.6.0 → 1.8.0

package/skills/wix-headless/references/cms/CMS_FOUNDATIONS.md

@@ -1,225 +1,25 @@
-# CMS Foundations — Shared Patterns for `@wix/data`
+# CMS Foundations — Seeding via `@wix/data` REST (business track)
 
-Core patterns used by all CMS use cases: service module template, `@wix/data` queries, image resolution, elevated access, MCP seeding, and rich-text (Ricos) rendering.
+The **seeding** half of CMS foundations: create collections and insert + verify sample items via the Wix Data REST API. This is frontend-blind business-track work — a collection and its items are the same regardless of what renders them.
 
-> **Import note (read first).** Page code in this plugin uses `import * as items from "@wix/wix-data-items-sdk"` rather than the documented `import { items } from "@wix/data"`. The Wix-headless docs still show the `@wix/data` form, but `@wix/data` 1.0.448 dropped the `items` re-export — only sub-namespaces (`backups`, `collections`, `permissions`, …) remain, and the documented form fails the build with `'items' is not exported by '@wix/data'`. The actual `items` API (with `query`, `insert`, `update`, `remove`, `bulkInsert`, etc.) lives in `@wix/wix-data-items-sdk`, which `@wix/data` depends on transitively. Importing from there directly works on every current `@wix/data` version. The cms vertical pack adds `@wix/wix-data-items-sdk` to the install list so it's always present (`references/verticals/cms.md`). Use the wix-data-items-sdk import everywhere.
+> **Rendering / page code lives in the astro frontend track.** The service-module template, `@wix/data` SDK query patterns, image resolution, Ricos rendering, and category filtering are **not** here — they are in `<SKILL_ROOT>/references/astro/cms/CMS_FOUNDATIONS.md` (the `pages` scope's doc). This file is consumed by the `seed` scope. The `cms/INSTRUCTIONS.md` router points each scope at the right half.
 
-## Rendering Ricos rich-text fields
+## Collection ID Format (seeding-relevant)
 
-Wix CMS stores `RICH_TEXT` / `RICH_CONTENT` fields as **Ricos JSON** — a structured node tree (PARAGRAPH, HEADING, BULLETED_LIST, etc.), not HTML. The dashboard's rich-text editor reads and writes this format.
+Native (user-created) CMS collections use **just the collection name** — no namespace prefix (e.g. `"about-content"`, `"faq"`, `"Projects"`). Only Wix App collections use a `<namespace>/<name>` format. Use the exact `id` you create here; verify with `GET /wix-data/v2/collections?fields=id` (standard REST headers from `../shared/AUTHENTICATION.md`). Never guess — the dashboard display name may differ from the ID.
 
-For SSR Astro pages (about, faq, portfolio, team, resource), import the seeded `renderRicos` util from `src/utils/ricos.ts`. The util is shipped by `seed-utilities.sh` (copied from `<SKILL_ROOT>/shared-utilities/ricos.ts` during Setup), so it's already on disk — do NOT inline a Ricos walker in your page.
+## Seeding via REST (Conditional)
 
-```astro
----
-import * as items from "@wix/wix-data-items-sdk";
-import { auth } from "@wix/essentials";
-import { renderRicos } from "../utils/ricos";
-
-const elevatedQuery = auth.elevate(items.query);
-const { items: results } = await elevatedQuery("about-content")
-  .limit(1)
-  .find();
-const about = results[0];
-const bodyHtml = renderRicos(about?.body);
----
-
-<article class="prose">
-  <h1>{about?.heading}</h1>
-  <div set:html={bodyHtml} />
-</article>
-```
-
-The util covers the common subset (PARAGRAPH, HEADING 1-6, BULLETED_LIST / ORDERED_LIST / LIST_ITEM, BLOCKQUOTE, DIVIDER + BOLD / ITALIC / UNDERLINE / LINK decorations). Anything outside that set renders defensively as a `<p>` with the raw text — never throws.
-
-> **Why not @wix/ricos?** The blog vertical uses `@wix/ricos`'s React `RicosViewer` as a client island because blog posts can carry the full Ricos feature set (galleries, polls, embedded media). For static CMS pages, that's ~80kb of React for paragraphs and lists — overkill. Use the seeded SSR walker instead.
-
-> **Do NOT `set:html={item.body}` directly.** That ships JSON-encoded text into the page (e.g. `[object Object]` or `{"nodes":...}`). Always go through `renderRicos`.
-
-> **Critical Rules — Read Before Starting**
-> 1. **Collection IDs have NO namespace** — user collections use just the name (e.g., `"Projects"`). Only Wix App collections use `<namespace>/<name>`. Verify via MCP: `GET /wix-data/v2/collections?fields=id`.
-> 2. **SDK query pattern** — `items.query("CollectionId").find()`. There is no `items.queryDataItems()` in the SDK.
-> 3. **`auth.elevate` on every query** — without it, restricted collections silently return no items.
-> 4. **CMS only for user collections** — use `@wix/blog` for blog posts, `@wix/stores` for products, `@wix/forms` for form submissions.
-
-## Prerequisites
-
-- `@wix/data` package installed (collected by features orchestrator — do NOT install independently)
-- `@wix/essentials` package installed (for elevation)
-- A data collection created in the Wix dashboard → CMS section
-- No special Wix app installation needed — `@wix/data` works with any Wix Managed Headless project
-
-## Collection ID Format
-
-Native (user-created) CMS collections use **just the collection name** — no namespace prefix.
-
-Example: if the collection is called `Projects`, the collection ID is simply `"Projects"`.
-
-Only Wix App collections (e.g., `Members/PublicData`, `Locations/Locations`) use a `<namespace>/<name>` format. User-created collections never use a namespace.
-
-> **How to verify**: Call `GET /wix-data/v2/collections?fields=id` via MCP and use the exact `id` value from the response. Never guess — the dashboard name may differ from the ID.
-
-## Quick Reference — Inline Query (Simple Pages)
-
-For pages that just need to list items from a collection:
-
-```astro
----
-import * as items from "@wix/wix-data-items-sdk";
-import { auth } from "@wix/essentials";
-
-// Always elevate queries for permission safety
-const elevatedQuery = auth.elevate(items.query);
-const { items: results } = await elevatedQuery("MyCollection")
-  .ascending("sortField")
-  .limit(50)
-  .find();
-
-// Fields are directly on each item (NOT item.data.field)
-const myItems = results.map((item) => ({
-  name: item.name,        // correct
-  // name: item.data.name  // wrong — REST pattern, not SDK
-}));
----
-```
-
-> **Common mistake:** `items.queryDataItems(...)` does NOT exist in the
-> `@wix/data` SDK. The REST API uses `/items/query` with a `dataCollectionId`
-> body field, but the SDK uses `items.query("collectionId")` — a chainable
-> QueryBuilder. Do not confuse REST and SDK patterns.
-
-## Service Module Template
-
-Every CMS use case follows the same `src/lib/{usecase}.ts` pattern — a typed interface and query functions that pages import.
-
-```typescript
-import * as items from "@wix/wix-data-items-sdk";
-import { auth } from "@wix/essentials";
-import { media } from "@wix/sdk";
-
-// -- Collection ID (use exact name from Wix dashboard — no namespace for native collections) --
-const COLLECTION_ID = "collection-name";
-
-// -- Typed interface matching collection fields --
-export interface CollectionItem {
-  _id: string;
-  title: string;
-  slug: string;
-  // ...add fields matching your collection schema
-  coverImage?: string;
-}
-
-// -- Image resolution helper --
-function resolveImage(wixImageUrl: string | undefined, width = 800, height = 600): string | undefined {
-  if (!wixImageUrl) return undefined;
-  return media.getScaledToFillImageUrl(wixImageUrl, width, height, {});
-}
-
-// -- Query all items --
-// Wrap every Wix SDK await in try/catch. If the query throws at SSR, an empty
-// array keeps the page renderable instead of crashing it. (Unguarded SSR
-// awaits truncate Astro's response stream mid-body — nav renders, then blank.)
-export async function queryItems(): Promise<CollectionItem[]> {
-  try {
-    const elevatedQuery = auth.elevate(items.query);
-    const { items: results } = await elevatedQuery(COLLECTION_ID)
-      .ascending("orderIndex")
-      .limit(50)
-      .find();
-
-    return results.map((item) => ({
-      ...item,
-      coverImage: resolveImage(item.coverImage),
-    })) as CollectionItem[];
-  } catch (err) {
-    console.error(`[cms:${COLLECTION_ID}] query failed:`, err);
-    return [];
-  }
-}
-
-// -- Get single item by slug --
-export async function getItemBySlug(slug: string): Promise<CollectionItem | null> {
-  try {
-    const elevatedQuery = auth.elevate(items.query);
-    const { items: results } = await elevatedQuery(COLLECTION_ID)
-      .eq("slug", slug)
-      .limit(1)
-      .find();
-
-    const item = results[0];
-    if (!item) return null;
-
-    return {
-      ...item,
-      coverImage: resolveImage(item.coverImage),
-    } as CollectionItem;
-  } catch (err) {
-    console.error(`[cms:${COLLECTION_ID}] getItemBySlug failed:`, err);
-    return null;
-  }
-}
-```
-
-Key details:
-- `auth.elevate(items.query)` wraps the query for restricted collections — always use this by default since collection permissions vary
-- `media.getScaledToFillImageUrl(url, w, h, {})` resolves `wix:image://` URLs to sized CDN URLs
-- Sort by `orderIndex` (ascending) for manually ordered content, or `_createdDate` (descending) for chronological
-- The interface must match the collection fields — check the dashboard, don't guess
-
-## Multi-Image Resolution
-
-For collections with image arrays (e.g., gallery images):
-
-```typescript
-function resolveImages(imageUrls: string[] | undefined, width = 800, height = 600): string[] {
-  if (!imageUrls || imageUrls.length === 0) return [];
-  return imageUrls
-    .map((url) => media.getScaledToFillImageUrl(url, width, height, {}))
-    .filter(Boolean);
-}
-```
-
-## Category Filtering Pattern
-
-Many use cases filter by category via URL search params (server-rendered, no client JS):
-
-```astro
----
-const activeCategory = Astro.url.searchParams.get("category");
-const allItems = await queryItems();
-const filtered = activeCategory
-  ? allItems.filter((item) => item.category === activeCategory)
-  : allItems;
-const categories = [...new Set(allItems.map((item) => item.category).filter(Boolean))];
----
-
-<nav>
-  <a href="?" class:list={[!activeCategory && "active"]}>All</a>
-  {categories.map((cat) => (
-    <a
-      href={`?category=${encodeURIComponent(cat)}`}
-      class:list={[activeCategory === cat && "active"]}
-    >{cat}</a>
-  ))}
-</nav>
-```
-
-> **Styling note:** Category filter pill styling is created by the design skill. See `COMPONENT_PATTERNS.md` → Category Filter.
-
-## MCP Seeding (Conditional)
-
-If Wix MCP tools are available, check if the collection has data and seed sample items if empty. This is **conditional** — only attempt if MCP is connected.
+Check whether the collection already has data; seed sample items only if empty. Calls go through `curl` against `wixapis.com` with the site-scoped REST token (see `../shared/AUTHENTICATION.md`) — no SDK, no MCP.
 
 1. Query the collection — if items exist, skip seeding
-2. If empty, create the collection and insert sample items via MCP (see templates below)
+2. If empty, create the collection and insert sample items via the REST calls below
 3. Design sample data that matches the business type from the functional plan
 
-> MCP seeding is optional. If MCP tools are not available, instruct the user to add content via the Wix dashboard → CMS section.
-
 ### Create collection (if it doesn't exist)
 
 ```
-<prefix>CallWixSiteAPI: POST https://www.wixapis.com/wix-data/v2/collections
+REST: POST https://www.wixapis.com/wix-data/v2/collections
 body: {
   "collection": {
     "id": "about-content",
@@ -238,7 +38,7 @@ body: {
 **This is the critical step that must include actual field values.** Creating an item without populating the `data` object results in an empty record — the collection schema exists but the item has no content.
 
 ```
-<prefix>CallWixSiteAPI: POST https://www.wixapis.com/wix-data/v2/items
+REST: POST https://www.wixapis.com/wix-data/v2/items
 body: {
   "dataCollectionId": "about-content",
   "dataItem": {
@@ -250,14 +50,14 @@ body: {
 }
 ```
 
-The response returns the created item's `_id` — collect these for the Phase 1 return contract.
+The response returns the created item's `_id` — collect these for the seed return contract.
 
 **Every text field must be populated in the `data` object.** Do not create items with empty `data: {}` and expect Phase 2 or the image agent to fill in text fields — they only handle their own scope (pages and images respectively).
 
 For FAQ items, include both `question` and `answer` plus `sortOrder`:
 
 ```
-<prefix>CallWixSiteAPI: POST https://www.wixapis.com/wix-data/v2/items
+REST: POST https://www.wixapis.com/wix-data/v2/items
 body: {
   "dataCollectionId": "faq",
   "dataItem": {
@@ -270,12 +70,14 @@ body: {
 }
 ```
 
+> **Bulk insert (N ≥ 2 items):** use the `wix-manage` skill's recipe — `wix-manage/references/cms/cms-data-items-crud.md` § "Bulk Insert Items" (`POST /wix-data/v2/bulk/items/insert`, up to 1000/call, one `dataCollectionId` per call → fire one bulk call per collection as a parallel batch). It also documents bulk update/patch/delete. Do not hand-roll N single inserts for a multi-item seed.
+
 ### Verify inserts with a live query (mandatory)
 
 After inserting all items, **query each collection once** and confirm every field you sent is present in the stored `data`. A POST without errors does NOT prove the content persisted — the API has accepted insert bodies with missing fields before, and the failure is invisible until a human opens the page.
 
 ```
-<prefix>CallWixSiteAPI: POST https://www.wixapis.com/wix-data/v2/items/query
+REST: POST https://www.wixapis.com/wix-data/v2/items/query
 body: { "dataCollectionId": "<collection>" }
 ```
 
@@ -287,12 +89,13 @@ For every returned item, confirm its `data` object contains every text field you
 
 A CMS seeder can return `complete` for an about-content item, then Image Phase 2 silently wipes its `heading` + `body` via a destructive full-record PUT. The verify-after-insert step here plus the read-merge-PUT rule in the images agent makes that class of data loss unreachable.
 
-### MCP Seeding with Images
+### Seeding with Images
 
 For use cases with image fields (`photo`, `coverImage`, `galleryImages`),
-follow `../../shared/IMAGE_GENERATION.md` (Steps 1–2) for Wix AI image
-generation and Wix Media import. Image generation is MCP-authenticated
-and always available — do not ask the user for credentials.
+follow `../shared/IMAGE_GENERATION.md` (Steps 1–2) for Wix AI image
+generation and Wix Media import. Image generation goes through the same
+CLI-minted REST token as the rest of this skill — do not ask the user for
+credentials.
 
 **Workflow:**
 
@@ -303,14 +106,14 @@ and always available — do not ask the user for credentials.
 
 ```
 # Step a: read the existing item
-<prefix>CallWixSiteAPI: POST https://www.wixapis.com/wix-data/v2/items/query
+REST: POST https://www.wixapis.com/wix-data/v2/items/query
 body: {
   "dataCollectionId": "CollectionName",
   "query": { "filter": { "_id": { "$in": ["{itemId}"] } } }
 }
 
 # Step b: merge image into existing data and PUT the full record
-<prefix>CallWixSiteAPI: PUT https://www.wixapis.com/wix-data/v2/items/{itemId}
+REST: PUT https://www.wixapis.com/wix-data/v2/items/{itemId}
 body: {
   "dataCollectionId": "CollectionName",
   "dataItem": {
@@ -322,24 +125,24 @@ body: {
 
 `...existingData` must include every non-system field from step a (system fields `_id`, `_owner`, `_createdDate`, `_updatedDate` don't need to be echoed). Skipping the merge wipes seeded text fields and ships an empty About page.
 
-**Prompt templates** — each use-case reference defines its own prompt template (see the "Seed with Images" section in TEAM_DIRECTORY.md, PORTFOLIO.md, RESOURCE_LIBRARY.md). Always incorporate brand context from the discovery/design phases.
+**Prompt templates** — each use-case reference defines its own prompt template (see the "Seed with Images" section in `../astro/cms/TEAM_DIRECTORY.md`, `../astro/cms/PORTFOLIO.md`, `../astro/cms/RESOURCE_LIBRARY.md`). Always incorporate brand context from the discovery/design phases.
 
 **Constraints:**
 - Never block the main flow on image failures — text data is already seeded
 - Runware image URLs are short-lived — import to Wix Media immediately after generation
 - If image generation or import fails for a single item, skip that item and continue with others
-- If all generation fails (credits exhausted, MCP errors), write the sidecar with `Status: partial` and proceed — but always attempt first
-- FAQ_KNOWLEDGE_BASE has no image fields — skip image generation for FAQ use cases
+- If all generation fails (credits exhausted, upstream Runware errors), write the sidecar with `Status: partial` and proceed — but always attempt first
+- `../astro/cms/FAQ_KNOWLEDGE_BASE.md` has no image fields — skip image generation for FAQ use cases
 
 ## Return Results
 
-Emit a structured JSON block at the end of your completion message per `../../shared/RETURN_CONTRACT.md`. Do NOT write sidecar files.
+Emit a structured JSON block at the end of your completion message per `../shared/RETURN_CONTRACT.md`. Do NOT write sidecar files.
 
 ```json
 {
   "status": "complete",
   "phase": "cms-seed",
-  "scope": "seed-seed",
+  "scope": "seed",
   "summary": "Created {N} collections; seeded {M} items; verified every field persisted",
   "data": {
     "collections": [
@@ -359,15 +162,15 @@ Emit a structured JSON block at the end of your completion message per `../../sh
 ```
 
 - `storedFields` MUST match the real keys seen in the verify-after-insert query response's `data` object (see § "Verify inserts with a live query"). Downstream pages agents compare against this — if you return `fields: ["heading", "body"]` but only `heading` was actually stored, pages render empty bodies.
-- `sampleValues` is a single example item's field-to-short-string map. Lets downstream agents spot-check that content is real without another MCP round-trip. Truncate rich-text bodies to the first ~80 characters.
+- `sampleValues` is a single example item's field-to-short-string map. Lets downstream agents spot-check that content is real without another REST round-trip. Truncate rich-text bodies to the first ~80 characters.
 - For collections without image fields (e.g., FAQ), set `imageField: null`.
 - The JSON block MUST be the last content in your message.
 
-## Testing
+## Testing (seed-side)
+
+1. Create a data collection in the Wix dashboard → CMS (or via the REST `POST /collections` above).
+2. Add fields matching the use case schema (see the specific use case reference under `../astro/cms/`).
+3. Add at least 2–3 items with all fields populated, including `slug` and `published` (if applicable).
+4. Run the verify-after-insert query and confirm every field persisted.
 
-1. Create a data collection in the Wix dashboard → CMS
-2. Add fields matching the use case schema (see the specific use case reference)
-3. Add at least 2–3 items with all fields populated, including `slug` and `published` (if applicable)
-4. Run `npx @wix/cli dev`
-5. Navigate to the listing page — should show items
-6. Click an item — should navigate to the detail page
+Page rendering / SDK query patterns for these collections are in `../astro/cms/CMS_FOUNDATIONS.md`.

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

@@ -5,14 +5,14 @@ description: "Implements structured content pages (About, FAQ, portfolios, team
 
 # CMS Implementer
 
-Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, MCP prefix, site.json read pattern, return contract, style conventions, and common failure modes.
+Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, prompt-inlined inputs (read only your `.wix/seeded.json` slice), return contract, style conventions, and common failure modes.
 
 ## Scope routing
 
 | Scope | Phase | Reference |
 |-------|-------|-----------|
-| `seed` | Seed (create collections + seed items via MCP) | `./CMS_FOUNDATIONS.md` (§ seeding) + use-case ref |
-| `pages` | Pages (About + FAQ pages read CMS via @wix/data inline) | `./CMS_FOUNDATIONS.md` (§ code patterns) + use-case ref |
+| `seed` | Seed (create collections + seed items via REST) | `./CMS_FOUNDATIONS.md` (seeding, business half) + use-case ref under `../astro/cms/` (collection schema + seed-with-images) |
+| `pages` | Pages (About + FAQ pages read CMS via @wix/data inline) | `../astro/cms/CMS_FOUNDATIONS.md` (code patterns) + use-case ref under `../astro/cms/` |
 
 No `components` scope — CMS pages SSR content inline via `@wix/data`; no React islands.
 
@@ -20,21 +20,52 @@ No `components` scope — CMS pages SSR content inline via `@wix/data`; no React
 
 Pick based on the business type (the orchestrator names one in your prompt):
 
-- `./FAQ_KNOWLEDGE_BASE.md` — Q&A accordions, category sections, search
-- `./PORTFOLIO.md` — project grid, category filter tabs, project detail
-- `./TEAM_DIRECTORY.md` — department-grouped directory, staff cards
-- `./RESOURCE_LIBRARY.md` — file listings, download buttons, file type badges
+- `../astro/cms/FAQ_KNOWLEDGE_BASE.md` — Q&A accordions, category sections, search
+- `../astro/cms/PORTFOLIO.md` — project grid, category filter tabs, project detail
+- `../astro/cms/TEAM_DIRECTORY.md` — department-grouped directory, staff cards
+- `../astro/cms/RESOURCE_LIBRARY.md` — file listings, download buttons, file type badges
 
 ## Files this vertical creates / contributes
 
 See `<SKILL_ROOT>/references/verticals/cms.md` frontmatter.
 
+## Seed return
+
+The `seed` scope emits this `data` shape in its return JSON (envelope rules in `../shared/RETURN_CONTRACT.md`). Phase 4 CMS page agents reference these collection names; the image agent attaches entity images to CMS items by ID.
+
+```json
+{
+  "status": "complete",
+  "phase": "cms-seed",
+  "scope": "seed",
+  "data": {
+    "collections": [
+      {
+        "name": "about-content",
+        "itemIds": ["665f3363-..."],
+        "fields": ["heading", "body", "image"]
+      },
+      {
+        "name": "faq",
+        "itemIds": ["abc", "def", "ghi", "jkl", "mno", "pqr"],
+        "fields": ["question", "answer", "sortOrder"]
+      }
+    ]
+  }
+}
+```
+
+## Page width (FAQ, About, long-form CMS)
+
+Read `references/shared/STYLING.md` § "Prose / reading width". **Do not** wrap FAQ/About body copy in `max-w-3xl` unless `--container-3xl` exists in `src/styles/global.css` `@theme`. Prefer `container-reading`, `max-w-6xl` (when `--container-6xl` is defined), or `max-w-[48rem]`. A bare `max-w-3xl` with only a spacing scale ships a ~80px column.
+
 ## CMS-specific failure modes
 
 | Wrong | Right |
 |---|---|
 | `items.queryDataItems(...)` / `items.query({ dataCollectionId })` | `items.query("CollectionId").find()` — queryDataItems doesn't exist |
 | React islands for static content pages | SSR inline with `@wix/data`; no islands needed |
+| `max-w-3xl` on FAQ/About wrappers without `--container-3xl` in `@theme` | `container-reading` or `max-w-[48rem]` / `max-w-6xl` per STYLING.md |
 | Return `status: "complete"` without re-querying the collection | Always run the verify-after-insert query (see CMS_FOUNDATIONS.md § "Verify inserts with a live query"); fail fast if any field is missing |
 | Report `fields: [...]` guessed from the insert body | Report `storedFields: [...]` matching the actual keys in the query response's `data` object — pages agents compare against these |
-| Assume text fields survive downstream image PATCHes | Seeder's job is to verify content is present; images agent must preserve via read-merge-PUT (images INSTRUCTIONS.md § "CMS Items") |
+| Assume text fields survive downstream image PATCHes | Seeder's job is to verify content is present; images agent must preserve via read-merge-PUT (images INSTRUCTIONS.md § "CMS Items") |

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.