@wix/agent-skills 1.13.0 → 1.15.0

package/skills/wix-headless/references/IMAGE_GENERATION.md

@@ -0,0 +1,69 @@
+# Image generation (opt-in, all project types)
+
+A single reusable capability: generate an image with **Wix AI (Runware)** via the `wixapis.com` proxy, import it into Wix Media, and attach it where it's needed. **Opt-in** — only runs when `imagery` is on (resolved in `DISCOVERY.md`; default off → text-only). It's **agnostic to the project type**: it uses `$TOKEN`/`$SITE_ID` from the provided authentication mechanism, exactly like every other call.
+
+Use it **intelligently, by need** — there's no fixed slot list:
+- **Entity images** — during Seed, attach images to seeded image-bearing entities (e.g. stores products, blog covers, CMS items, bookings services, restaurant items, portfolio projects + collection covers, event heroes — illustrative, not a write-shape index; each capability's recipe pins its own attach shape, see §3). **Attaching the generated image to the entity is a required second step** — a seeder creates the entity in pass 1 (text-first), then a pass-2 update/patch writes the image onto it. An entity is not "done" until its image is attached (or the attach is skipped because imagery is off / it failed — then it stays text-only, which is fine).
+- **Contextual / decorative images** — when the skill is building a frontend (the create/connect flows) and the agent or user decides a surface needs one (e.g. a homepage hero, an about-section visual). Generate only what the page actually uses, up to the per-run `imageCap` (`DISCOVERY.md` §4); a slot over the cap or off gets the **themed-block fallback** (below), not an empty gap.
+
+## 1 · Generate
+
+```
+POST https://www.wixapis.com/runwareschemaless/v1/request
+body: [
+  { "taskType": "imageInference", "taskUUID": "<UUIDv4>", "outputType": "URL",
+    "outputFormat": "PNG", "positivePrompt": "<prompt>",
+    "width": 1024, "height": 1024, "model": "google:4@2", "numberResults": 1 }
+]
+```
+
+Auth: the universal call shape (`Authorization: Bearer $TOKEN`, `wix-site-id: $SITE_ID`, `Content-Type: application/json`). Extract `data[0].imageURL` (short-lived — import it immediately).
+
+- **`taskUUID`** must be a real UUIDv4 (`uuidgen`); slugs return `400 invalidTaskUUID`.
+- **Allowed dimensions** (per model): `1024×1024` (square — products, squares), `1376×768` (16:9 — heroes/banners), `1200×896` (4:3 — editorial). Free-form sizes 400.
+- **Forbidden for `google:4@2`**: `steps`, `CFGScale` (→ `400 unsupportedParameter`). Alternatives if it keeps failing: `bfl:5@1`, `runware:400@1`.
+
+### Batching
+- **`google:4@2`** times out (`504`) when one request bundles **N≥3** tasks. Fire **N parallel 1-task requests** as concurrent sibling `curl` calls in a single batch — never N≥3 tasks in one body, never sequential one-per-turn.
+- **`bfl:5@1` / `runware:400@1`** can batch multiple tasks in one request body.
+
+## 2 · Import to Wix Media
+
+```
+POST https://www.wixapis.com/site-media/v1/files/import
+body: { "url": "<imageURL from generate>", "mimeType": "image/png", "displayName": "<name>.png" }
+```
+
+Keep two values from the `file` object: **`file.url`** (the full permanent `wixstatic.com` URL) and **`file.id`** (the WixMedia file id, e.g. `<hash>~mv2.jpg`). Some entities bind by url, others by id — **which one a given entity uses is the recipe's concern** (§3), not this common section's. (The import response has **no `fileUrl` field** — the id is `file.id`.)
+
+## 3 · Attach (by entity type)
+
+The pass-2 **write shape is per-entity earned knowledge and lives in each capability's seed recipe** — right next to the create shape the seeder already reads (`inline-recipes/setup-<capability>.md`). **That recipe is authoritative** — read the exact shape there (field paths, any required companion fields, silent-drop warnings, confirm-by-requery), not here. This section is navigation only and carries no shapes:
+
+| Entity | Recipe | Section |
+|---|---|---|
+| Store product | `setup-online-store.md` | **Attach images** |
+| Blog post cover | `setup-blog.md` | **Attach images** |
+| CMS item | `setup-cms.md` | **Attach images** |
+| Bookings service | `setup-bookings.md` | **Attach images** |
+| Portfolio project / collection | `setup-portfolio.md` | **Attach images** (cover + gallery) |
+| Restaurant menu item | `setup-restaurants.md` | **Attach images** |
+| Event hero (`mainImage`) | `setup-events.md` | **Attach images** |
+| *(any entity whose recipe doesn't pin one)* | — | discover live via `DOC_DISCOVERY.md` |
+
+- **Frontend** (when building a site) — drop `file.url` into the `<img src>` / CSS `background-image` of the page being built.
+
+## Prompts
+
+Brand-contextual, never generic. Include: subject; the brand aesthetic/mood; the palette (real tones, e.g. "warm cream and forest green"); style/lighting; and always **"no text, no watermarks"** (AI-rendered text is garbled). Pull context from the brand + the entity (product name/description, post topic, page purpose).
+
+## Credits, cost & the not-generating fallback
+
+Each generated image costs **1 Wix AI credit**, billed at the account level regardless of project type (the account behind the metasite must have credits). Volume is bounded in `DISCOVERY.md` §4 — carry those two values through:
+
+- **Cost is surfaced** — the pre-work line states the plan in credits (*"~N images ≈ N credits"*). Keep the running count honest with that estimate.
+- **Honor the per-run `imageCap`** (default ~12, from Discovery). Generate up to the cap by priority (hero/most-visible surfaces first); **beyond the cap, don't generate — render the themed-block fallback** and log what was capped. Never silently exceed the cap on a "throughout"-style phrase.
+
+**Themed-block fallback (the not-generating path).** Whenever a **frontend** image isn't generated — imagery off, over the cap, declined, or a generation failure — render a **styled `div` that follows the site's design tokens** (palette, radius, spacing, an optional label/gradient) in the slot, never an empty gap or a broken `<img>`. It's deterministic, needs no input, never hangs — so it's the safe default for any non-interactive run and keeps the layout on-brand at zero credits. (A *seeded backend entity* with no image just stays text-only — there's no div to render server-side; `SEED.md` § "Entity images".)
+
+**Never block the run on image failure**: on `unsupportedParameter`/`unsupportedDimensions` fix and retry once; on model/5xx/credit-exhaustion, **skip that image and continue** — a frontend slot falls back to a themed block, a seeded entity stays text-only (the user can add their own later).

package/skills/wix-headless/references/SDK_HANDOFF.md

@@ -0,0 +1,97 @@
+# SDK-integration handoff
+
+**This is the last step — reach it only after Setup and Seed have run.** The guide below is filled from the `seeded` map (created IDs), which exists only because Seed executed; if you're here without having installed the apps and seeded content, go back and do that first. The guide *describes* the backend the earlier steps built.
+
+The skill **returns this document** describing how to call Wix from the frontend, then **exits**. The host agent — which owns the frontend, the framework, and the build — does the wiring. We describe what to use and **link to the live Wix SDK docs for the API shapes**; the host decides where they go.
+
+> **Link to the docs for API shapes; don't inline examples.** The Wix SDK docs are versioned and complete; hand-written snippets under-specify the hard parts (rich-content rendering, package versions, types) and lead the host to build against a wrong shape. The handoff supplies what the docs can't: the **seeded IDs**, the **`clientId` source**, and the **package set**. The package set is the **inlined map in §3** — the SDK doc `.md` pages don't surface the `@wix/*` import string to navigation, so the map is the source of truth for *which* packages; the **inline recipe** each row points to is the source of truth for *how* to call them (current API shape + version).
+>
+> **The linked docs are the source of truth for current API shapes and versions — read them for the integration. Existing code (in this or any other project) is not a substitute: it may target a different SDK version and silently mislead.**
+
+Emit the document as the skill's final message (a Markdown block the host can act on or save). Fill it from the run's `verticals[]`, the `seeded` map, the OAuth app's public `clientId`, and — for each loaded capability — its **Required site features** and **Implementation checklist** from `references/CAPABILITIES.md` (§6). Include **only** the loaded capabilities. The guide isn't just "here are the IDs and packages"; it's the spec for a *complete* site, so the host builds real features (author, comments, dates…) rather than a bare data dump.
+
+## What the document contains
+
+### 1 · Packages to install
+The always-on package is **`@wix/sdk`** (provides `createClient` + `OAuthStrategy`). Add the union of the loaded capabilities' runtime packages from the **map in §3**. **Runtime packages only** (no scaffold/build deps). For install details and current versions, link: <https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/install-sdk-packages.md>.
+
+### 2 · Client setup (and the clientId source)
+With a **manual client** the frontend authenticates as an **anonymous visitor** via `OAuthStrategy`, with `clientId` = the OAuth app's **public client id**. This is the model for **host-owned** frontends (this guide is emitted) and the skill's **non-Astro** path (`references/non-astro.md`). **Managed-Astro is the exception** — it auto-authenticates with **no client at all** (`references/astro.md`); skip this section's `clientId` wiring there. Two facts hold whenever a client *is* used: the `clientId` is **not secret** (it's the public OAuth id), and the **`client_secret` never reaches the frontend.** Two type-independent steps:
+
+1. **Obtain the `clientId`** via the provided authentication mechanism — **see `<TYPE_DIR>/AUTHENTICATION.md`** (each type names where the public id comes from; don't re-mint or re-fetch it if the type already provides it).
+2. **Get the `clientId` into the client bundle** — this depends on **who owns the frontend**, not on the project type:
+   - **The host owns the frontend** (this guide is *emitted* — backend-only: self-managed, stripe, or managed backend-only) → the host exposes the value to client code via its framework's public-env convention (`NEXT_PUBLIC_*`, `VITE_*`, `PUBLIC_*`, …).
+   - **The skill owns the frontend** (this guide is *applied* — managed create/connect) → **how the frontend authenticates is framework-specific, so follow the frontend reference, not this bullet.** On **Astro** (the default) authentication is automatic — there is **no client and no `clientId` to wire** (`references/astro.md`). On a **non-Astro** frontend you build a manual client (`references/non-astro.md`): wire the `clientId` in via the framework's public-env convention if one exists, otherwise inline the public id into the client code/bundle.
+
+For the current `createClient` + auth-strategy shape, link:
+- <https://dev.wix.com/docs/sdk/articles/set-up-a-client.md>
+- <https://dev.wix.com/docs/sdk/articles/set-up-a-client/authorization-strategies.md>
+
+> **Confirm the `clientId` reached the built bundle before deploying.** Public-env wiring fails silently — a mis-wired public var inlines as `undefined`, and then *every* visitor token call from the live site 400s with no other clue. After the production build, verify the **actual `clientId` value** is present in the built output (check that the value resolves — not merely that the variable *name* appears somewhere). Doing this pre-deploy stops it from being mistaken for an origin/CORS problem afterward.
+
+### 3 · Per-capability packages + API docs (package from the map; recipe for shapes)
+For each loaded capability, give the host the **package(s)** from the map below and point it at the capability's **inline recipe** (`references/inline-recipes/how-to-code-*.md`) — the pinned API shape, methods, version, and failure modes live there; don't re-summarize them here. The map is the source of truth for *which* packages; the recipe is the source of truth for *how* to call them. **The recipes are local — Read them with the file tool, don't curl.**
+
+| Capability | Package(s) | Recipe — the pinned frontend contract |
+|---|---|---|
+| stores | `@wix/stores` (+ `@wix/ecom`, `@wix/redirects` for cart/checkout) | `how-to-code-a-store.md` — Catalog V3 read + cart/checkout. |
+| blog | `@wix/blog` (+ `@wix/ricos` to render `richContent`; **`@wix/comments` + `@wix/members`** when the blog has comments/members; `@wix/blog` `likes` when the site has members) | `how-to-code-a-blog.md` — Blog V3 read/render + member features (likes, comments). Supplement: <https://dev.wix.com/docs/sdk/business-solutions/blog.md>. |
+| cms | `@wix/data` | `how-to-code-cms.md` — `items.query` read contract. |
+| forms | `@wix/forms` | `how-to-code-forms.md` — schema-driven render (read the live form schema, visitor token/no elevate) + Form Submissions v4 write contract. |
+| events | `@wix/events` (+ `@wix/redirects` for the ticketed hosted-checkout redirect) | `how-to-code-events.md` — Events V3 read + the `TICKETING`-vs-`RSVP` branch. |
+| bookings | `@wix/bookings` (+ `@wix/auto_sdk_ecom_cart-v-2`, `@wix/redirects` for the cart/checkout that holds the seat; `@wix/forms` for the schema-driven booking form) | `how-to-code-bookings.md` — Services V2 read + `createBooking → ecom Cart V2 → checkout-or-place`. |
+| pricing-plans | `@wix/pricing-plans` (+ `@wix/members` — login is a hard dep; and for the Bookings-membership integration `@wix/bookings` + `@wix/ecom` (+ `@wix/redirects`)). **Use `@wix/pricing-plans`, NOT the Wix-site `@wix/site-pricing-plans` (`startOnlinePurchase` is site page-code, not headless).** | `how-to-code-pricing-plans.md` — Plans V3 grid + login-gated order/subscribe + book-with-membership. |
+| restaurants | `@wix/restaurants` (menu display — **no `@wix/ecom`** unless online ordering is in the run; reservations are a separate app) | `how-to-code-restaurants.md` — Menus V1 display-only read. |
+| restaurants — online ordering (add-on; only when the Orders app is in the run) | add `@wix/ecom` + `@wix/redirects` to the row above | `how-to-code-restaurant-orders.md` — ordering cart/checkout on top of the menu display. |
+| portfolio | `@wix/portfolio` (+ `media` from `@wix/sdk` to resolve image strings; **no** `@wix/ecom`/`@wix/redirects` — display-only) | `how-to-code-portfolio.md` — Portfolio v1 display-only read. |
+| restaurants — table reservations (add-on; only when the Table Reservations app is in the run) | `@wix/table-reservations` (a **distinct** package from `@wix/restaurants`; **no ecom/redirects** — a reservation is a hold, not a purchase) | `how-to-code-restaurant-reservations.md` — book-a-table hold→reserve. |
+
+> **Cross-cutting packages** (`CAPABILITIES.md` § "Cross-cutting capabilities"): these aren't per-vertical rows but get added to the package list when the run used them. If **coupons** were seeded, add `@wix/marketing`. The eCommerce checkout packages (`@wix/ecom`, `@wix/redirects`) are already folded into the stores row above — include them once when any purchase-flow vertical is present.
+
+> **members (cross-cutting — add when the site has login / account / gated content, or whenever pricing-plans is loaded).** Package: **`@wix/members`** (current member / profile via `getCurrentMember` — **not** the dev-preview `@wix/site-members`); auth is the `OAuthStrategy`/session methods on the always-on **`@wix/sdk`**. **The API shape lives in the axis recipe — Read the one that matches the frontend, not both:** `how-to-code-members-astro.md` (Astro: built-in `/api/auth/login` + `/api/auth/logout`, no client) or `how-to-code-members-non-astro.md` (non-Astro: manual `OAuthStrategy` handshake). Both are the **Wix-hosted login page** (the default). **Only if the brief explicitly asks for a custom/branded login form or custom sign-up fields**, Read `how-to-code-members-custom-login.md` instead — the surface is chosen by intent, not by project type.
+
+> **Why a map and not navigation:** the SDK doc `.md` pages don't expose the `@wix/*` import string to a reader (it's only in the page's interactive UI), so the package column is inlined here as the source of truth. If a package name ever drifts, reconcile it against the SDK install article (§1) — not by guessing from the module URL. The linked pages remain authoritative for the API itself.
+
+### 4 · Seeded schema (what the host binds to — names + field keys, not content IDs)
+The host binds to **schema**, not to a frozen list of content IDs. **Content is discovered live**: every listing is a query-all (`queryProducts`/`queryPosts`/`queryEvents`/`queryServices`/`queryPlans`/`items.query`/`listMenus`…), every detail page resolves a `[slug]`/`[...slug]` route from the URL at request time (the frontend is SSR — no `getStaticPaths`), and category/nav is a live query. So the frontend never needs the seeded per-item id/slug arrays — and **not carrying them is deliberate**: an id the host was never handed is an id it can't hardcode, so content the owner adds later in the backoffice flows through by construction (see §6).
+
+Carry only the **structural** carve-outs the coding step genuinely reads — the collection/form *names and keys* you must know to query and bind, which do **not** change when an owner adds a row:
+- **cms:** `collectionId` + field keys per collection
+- **forms:** **`formId` only.** The field set, order, labels, `required`, validation format, and dropdown options are **read live from the form schema at render time** (visitor token, no elevate — `how-to-code-forms.md`), so the handoff no longer carries per-field `target` keys. Reading the schema live is the source of truth: it closes the seed↔site drift by construction (a field the owner adds/removes/relabels in the dashboard reflects on the site with no code change) and is the more v2-aligned "host resolves everything else live" shape. (For a bespoke, design-led form where dashboard-editability isn't the value prop, the host may still hardcode inputs from the known `target`s — `how-to-code-forms.md` covers that mode — but the default and the carry is `formId` only.)
+
+Everything else the host resolves live from the queries in §3. (Static platform constants — Stores/Bookings app IDs, the Blog appDefId — and the public `clientId` are needed too, but they're identical for every site, not seed output; they're in §2/§3.)
+
+### 5 · Integration notes (headless-auth specifics the per-module docs won't frame)
+- The visitor token has **no per-user identity** → seeded **CMS collections are public/shared** across all visitors (not per-user, not cross-device). Per-user storage needs member auth.
+- Frontend CMS access is **read**; visitor writes go through **Forms** submissions.
+- **Blog comments are member-gated — read public, write authenticated.** Querying/rendering comments is public, so list them server-side in SSR. **Submitting** needs a logged-in member, so don't gate the form behind an upfront login check (that branch is what burns deliberation): render the form always and resolve identity at submit — POST to a backend endpoint (`src/pages/api/*.ts`) that calls `createComment` with the request session; if the caller isn't a member, redirect to the built-in `/api/auth/login?returnUrl=…`. **Do not build the comment form as a client island** — the API-endpoint + session path is the documented shape and avoids the browser-auth detour. The comment API keys (post `referenceId`, Blog appDefId, author lookup via `post.memberId`) are in `how-to-code-a-blog.md`.
+- **Member auth is one mechanism split on the frontend axis (the §3 members note routes to the right recipe), and orthogonal to elevation.** Sign-up and log-in are the *same* flow (the Wix login page logs in **or** registers); log-out is its inverse. Two layers stay separate: **identity** (logged-in vs not — no app install) vs **profile** (name/photo/roles — needs the **Wix Members Area app** installed, `SETUP.md`). **pricing-plans is a hard dependency**: subscribing requires a logged-in member; for the other verticals, member login is a soft add-on for their "my …" surfaces only. **A member reading their own data (own orders/bookings/subscriptions, plan-gated content) uses the member token with NO `auth.elevate`** — elevation is the separate admin/permission axis (site-wide reads, server-side only), not something member features need.
+- **Gating is a LIVE signal, never a hardcoded id list.** Whenever content is gated (members-only articles, plan-eligible class booking, any "premium" surface), decide eligibility from a signal read **at request time** — a queryable flag carried on the content (a `members-only` blog category/tag or a boolean CMS field) and live coverage/eligibility (`checkout.membershipOptions.eligibleMemberships`, or the member's active-order `planId`s matched against **live** Benefit-Program coverage). **Never** gate on a frozen set of "premium" slugs/ids or a seed-time `plan→service` map: a gated post or a newly-covered service the owner adds later would silently read as public/ineligible. See `how-to-code-a-blog.md` (member features) and `how-to-code-pricing-plans.md` (coverage read).
+
+### 6 · What a complete site must include (per loaded capability)
+For each loaded capability, carry its **Required site features** and **Implementation checklist** from `references/CAPABILITIES.md` into the guide — in plain product language, lightly tailored to what was seeded. **This is the build spec, not optional polish:** the host should build every *required feature* and cover every *checklist* item. For example, a blog must show the **author** (name + photo), the publish date and reading time, the cover image, and the **full formatted content** (not flattened text) — a posts-list-plus-plain-text-body is incomplete. The host maps these onto its own components using the packages/docs in §3 and the seeded schema in §4.
+
+- State them as the *what* (product behaviour), not the *how* (no component code, no API calls) — the host owns the build.
+- If a *required feature* depends on backend support that **Seed** enabled (e.g., comments), note it's available so the host wires it. If Seed could **not** enable it, say so plainly rather than implying the site is complete.
+- **When pricing-plans is loaded, `login / account / gated content` is a *required* feature, not optional polish** — a plans grid with no way to log in and subscribe is incomplete (subscribing requires a member; §5 member-auth note). Point the host at the matching `how-to-code-members-*.md` recipe. For the other verticals, a "my …" surface (my orders / my bookings / my registrations) is a member-gated *enhancement* — list it only if the run's intent calls for an account view, and flag it needs the same login mechanism.
+- **Curation / hero / nav must come from a LIVE query, never a pinned slug/id.** A "featured" or "latest" item, a hero, and every nav/category bar must be driven by a query — "next upcoming" (`queryEvents` filtered to `UPCOMING`/`STARTED`, sorted by start date), "newest" (`queryPosts`), `queryCategories`, etc. — resolved at request time. A pinned "featured event" slug not only fails to rotate as the owner adds content, it can go **stale/past**. Even a **single-item** site (one event, one product) must drive its homepage from the *listing query*, not a hardcoded lone slug — so a second item the owner adds later surfaces automatically instead of staying invisible.
+- **State the residual limitation honestly — don't over-claim a "self-maintaining" site.** New **content** flows through live with no code change and no re-publish: a product, post, event, service, plan, menu item, or category the owner adds in the backoffice appears via the live queries above. **Forms are schema-driven, so an added/removed/relabelled form *field* of a supported input type (text/email/phone/url/textarea/dropdown) — or a tightened validation rule (`required`, `minLength`/`maxLength`/`pattern`, format) — also reflects live with no code change** (`how-to-code-forms.md`). But **new content *types / collections / ticket-tier semantics*, and a form field of a *novel type the renderer doesn't handle yet*, require a code change** — the frontend renders an authored schema, so a new CMS field, a new collection, a novel ticket structure, or an unsupported form field type won't render until coded. Say this plainly in the guide rather than implying the site maintains itself beyond that.
+- **Before finishing, verify nothing is pinned.** Confirm no route, listing, gate, or nav is filtered against a seed-time id/slug array held in code — every such filter must key off a **stable id used in a live query** (a `categoryId` from `queryCategories`, a `slug` from the URL/query result), not a frozen membership list. A pinned array is the one way owner-added content silently fails to appear.
+
+## How to navigate the Wix docs
+
+> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
+> - Pages are either content pages (article/reference text) or menu pages (a list of links to child pages).
+> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/business-solutions.md`).
+> - Top-level index of all portals: <https://dev.wix.com/docs/llms.txt>
+> - Full concatenated docs: <https://dev.wix.com/docs/llms-full.txt>
+> - **§3 points at a local inline recipe per capability — Read it first (first priority); it's already curated, so read it as-is rather than re-discovering the shape.** For a pinned SDK doc link (inside a recipe, or the blog supplement in §3), `curl` its `.md` directly.
+> - **`SearchWixSDKDocumentation` is second priority — for *discovering* a method the recipe doesn't pin, or when a menu hides the runtime functions.** Curling a module *menu* (e.g. `…/sdk/business-solutions/blog.md`) often surfaces only dashboard/extension pages, not the runtime query functions — `SearchWixSDKDocumentation "blog query posts"` returns the actual `posts.queryPosts`/`listPosts` shapes (with `?apiView=SDK` schema links) the menu doesn't expose.
+
+## After deploy: finalize per the project type
+
+The guide describes the backend; how the site is published and how its origin is allowed to call Wix depend on the project type. After deployment, **finalize per `<TYPE_DIR>/DEPLOYMENT.md`** — it carries the type-specific steps (and tells you whether anything is required of the user).
+
+## After emitting the document
+
+Once the guide is emitted and the deployment checklist is done — site published, origin registered (or the user has been flagged) — the skill's work is done. Close with a short plain-prose summary of what was set up (apps installed, content seeded per capability, site published, origin registered or pending). What happens with the guide — installing packages, wiring components, choosing a framework — is the host's to decide.

package/skills/wix-headless/references/SEED.md

@@ -1,214 +1,70 @@
-# Seed
+# Seed — create the backend content
 
-This article seeds backend data. Every loaded pack with a seed recipe gets its own seeder subagent; the orchestrator collects each seeder's JSON return (per `references/shared/RETURN_CONTRACT.md`) into a `seeded` map keyed by pack. (For the business-vs-frontend track model, see `PLAN.md` § "Two tracks". For run flow — dispatch timing, waits, batching, transitions — see `BUILD.md`.)
+For each resolved capability, create the backend content its *what* names. This file carries **only the *what*** (entities, counts, policy) and points at each capability's **inline recipe** for the API *how*. **No endpoints, payloads, field templates, caps, or batching mechanics live here** — those are inlined in the per-capability recipe (`inline-recipes/setup-*.md`, mapped in §2); read them there.
 
----
+Use `$TOKEN` / `$SITE_ID` from the provided authentication mechanism (see `<TYPE_DIR>/AUTHENTICATION.md`). The capabilities are **independent** — no cross-capability ordering or shared data (**two exceptions:** (a) **pricing-plans depends on bookings' service IDs**, so seed bookings before pricing-plans; (b) **restaurants online ordering depends on the restaurants menu** — the ordering add-on binds each menu to an operation, so the menu must be seeded before ordering — both in §2). For each one: read its inline recipe (§1; §2 maps each capability to its `setup-*.md`), build the body from `intent.<cap>` + `brand`, execute against `wixapis.com` with the universal call shape (Bearer `$TOKEN` + `wix-site-id` — see `SETUP.md` §1), and collect the created IDs into a `seeded` map keyed by capability.
 
-## Step 1 — Build the dispatch list
+> **Concurrency is an optional optimization, never a requirement.** Seeding the capabilities **one after another always works** — that is the safe default, and an agent doing everything itself simply seeds each in turn. Because the capabilities are independent (above), **if** your runtime can run work concurrently you **may** seed several at the same time to save wall-clock. Treat this strictly as "you may," never "you must": a correct seed must never *depend* on parallelism.
+>
+> **These constraints hold whether you seed serially or concurrently:**
+> - **Bookings before pricing-plans.** The plan→service coverage step needs the created service IDs, so keep the two in order and seed them together.
+> - **Restaurants menu before its online ordering.** The ordering add-on (`setup-restaurant-orders.md`) verifies/reshapes the auto-provisioned ordering setup for each menu. Installing the Orders app auto-enables ordering for menus that exist *and* for menus created after install, so ordering binds either way — but seed the menu first, then the ordering, as one unit, so the verify step has a menu to confirm against. If you split this work off to run concurrently, hand over the seeded `menuId`s and seed menus-then-ordering together.
+> - **Intra-recipe serial rules stay.** Store categories are created one at a time (they share the `@wix/stores` tree revision; concurrent creates `409`), and pricing-plans' sub-steps stay ordered.
+>
+> **Read a capability's recipe only if you're going to seed it yourself; if that capability is seeded as a separate concurrent unit, that *unit* reads the recipe — you don't.** Don't read all the seed recipes into your own context and *then* hand the work off — that loads each recipe twice (once wasted) and bloats working memory. Read-if-you-seed applies equally to the do-it-all-yourself path (read each recipe once, when you seed that capability) and the split-off path (only the unit that seeds a capability reads its recipe).
 
-The recipe map and per-pack input notes are inlined below — **do NOT separately `Read references/seed-recipes.md`**. The Step 1 table here is canonical for the run; `seed-recipes.md` exists only as a human-readable index of the same data, and reading it adds a turn and a thinking gap before the dispatch batch.
+## 1 · Where the *how* comes from — the inline recipes
 
-From the `verticals` list in orchestrator scratch (captured in Discovery), build the dispatch list. For each loaded pack:
-- If the pack has a recipe in the table below (`stores`, `cms`, `blog`, `forms`, `bookings`) → add to the dispatch list.
-- If the pack has no recipe (`gift-cards`, `ecom`) → record a phase entry as `{phase: "seed-<pack>", status: "skipped", notes: "no seed surface for this pack"}` directly. No subagent.
+Each built capability's create flow lives in a **self-contained local recipe** at `inline-recipes/setup-<capability>.md` (§2 maps each capability to its file). The recipe inlines every endpoint, request body, and representative response — **open it with the file Read tool and seed from it alone**; it supersedes the live REST doc pages, so don't go fetch them. **Read a recipe once per run** — if you already opened it while planning, proceed from what you have — and only read a capability's recipe if you're going to seed it yourself (a separate concurrent unit reads its own; see the concurrency note above).
 
-Resolve absolute recipe paths by joining `<wix-manage-root>` (already in scratch from Phase 2 Step 4 — do **not** re-invoke `Skill(name="wix-manage")` here) + the relative paths in this table.
+For a capability with **no** inline recipe (e.g. `coupons`), or for a field/error/endpoint a recipe doesn't cover, **`DOC_DISCOVERY.md` is the fallback** — never the first move.
 
-### Recipe map
+Two cautions apply to every capability regardless of recipe:
 
-| Pack       | Recipes                                                                                                                                                                                                                                                                      | Returns                                                                             |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| stores     | (relative to `<wix-manage-root>`) `references/stores/setup-online-store-catalog-v3.md` (idempotent catalog setup) + `references/stores/bulk-create-products-with-options.md` (single bulk call for N products)                                                              | `productIds[]`, `categoryIds[]` (when `intent.stores.categoriesNamed` is non-empty) |
-| cms        | (relative to `<wix-manage-root>`) `references/cms/cms-schema-management.md` (collection create) + `references/cms/cms-data-items-crud.md` (item create per collection) + `references/cms/cms-references-and-relationships.md` (only when a collection's `intent.cms.collections[N]` declares cross-references) | `collectionIds{}`, `itemIds{<collection>: []}`                                      |
-| blog       | (relative to `<wix-manage-root>`) `references/blog/how-to-create-blog-posts.md`                                                                                                                                                                                              | `postIds[]`, `categoryIds[]`                                                        |
-| forms      | (relative to `<wix-manage-root>`) `references/forms/create-form.md`                                                                                                                                                                                                          | `formIds[]`                                                                         |
-| bookings   | (within skill) `<SKILL_ROOT>/references/bookings/SERVICES_DATA.md` — service creation + optional staff. Recipe path uses `<SKILL_ROOT>`, NOT `<wix-manage-root>`.                                                                                                           | `services[{id, slug, name, type, durationMinutes, price, currency}]`, `staff[{id, resourceId, name}]` |
-| gift-cards | — (no seed surface; activation lives in Phase 2 app-install)                                                                                                                                                                                                                 | `{status: "skipped"}`                                                               |
-| ecom       | — (cart/checkout vertical; no seed surface)                                                                                                                                                                                                                                  | `{status: "skipped"}`                                                               |
+> **Public host, not `/_api/`.** Some method pages show an internal `https://www.wixapis.com/_api/<service>/...` URL in the schema header while the examples use the bare `https://www.wixapis.com/<service>/...`. Always call the **public (non-`/_api/`) form** — that's the external/headless endpoint; the `/_api/` prefix is internal and may be rejected.
 
-### Per-pack input notes
+> **Imagery is opt-in.** When `imagery` is **off** (the default), create entities **text-only** — omit image fields or use the placeholder the recipe documents; don't source imagery. When `imagery` is **on**, still create the entities text-first here, then attach generated images in the "Entity images" step below. This applies to **every** vertical, stores included — there is no per-vertical exception.
 
-These notes reduce dispatch-time guesswork. The recipe itself is the source of truth for the API shape — these notes are about how to translate `intent.<pack>` + `brand` into the recipe's input.
+## 2 · What to seed per capability
 
-**stores:**
-- Bulk recipe wants `products: [{name, slug, sku, price, options?, variants?}]`. Populate `name` and `slug` from `intent.stores.productCount` and `brand` (e.g. for a coffee shop with `productCount: 3`, generate three product names that fit the brand vibe).
-- `sku` defaults to `<slug>-001`; `price` is a positive brand-appropriate value (don't default to $1).
-- When `intent.stores.categoriesNamed` is non-empty, the subagent creates those categories via the Categories API after the bulk product create and assigns products into them. **Fire the N category-create calls as one parallel batch** (independent calls — they don't need to serialize). When the array is empty, skip categories entirely (do not invent a default set).
-- 5-product cap on the bulk endpoint. If `intent.stores.productCount` exceeds it, fan out into batches of 5.
-- Text-only seeding: do not generate or attach product images. Follow the recipe's documented placeholder pattern.
+Each entry states only the entities, where their count/content comes from, the policy that is genuinely the skill's call, the IDs to keep, and **which inline recipe carries the calls** — read that recipe (local; Read it, don't curl — it's self-contained and supersedes the doc pages) for everything else.
 
-**cms:**
-- Schema recipe wants one `POST /wix-data/v2/collections` call per collection in `intent.cms.collections`. Field shape comes from `collection.purpose` — e.g. `purpose: "about"` → single-row text collection with `title` + `body`; `purpose: "faq"` → repeated `question` + `answer` rows.
-- After all collections exist, the items recipe inserts `intent.cms.collections[N].itemCount` rows per collection, content generated from `brand`.
-- `cms-references-and-relationships.md` is consulted **only** when a collection's intent block declares cross-references. Otherwise skip it.
-- Return shape: `collectionIds: { <purpose>: <id> }` and `itemIds: { <purpose>: [<id>, ...] }`. Keying by `purpose` (not display name) lets Phase 4 wire pages without re-deriving slug ↔ id.
+- **stores** — *A product catalog.* Recipe: **`setup-online-store.md`**. `intent.stores.productCount` products whose names/prices fit `brand`. If `intent.stores.categoriesNamed` is non-empty, create exactly those categories and assign products into them; **if empty, create none** (skill policy — overrides any docs default). **Variant cardinality — keep it small by default:** unless `intent.stores` calls for specific options, give each product **at most one option with ≤3 choices** (so ≤3 variants/product); many products legitimately have **no** options (a single variant). Seeding cost scales with the variant Cartesian product and the field count per variant, so don't manufacture options the brief doesn't need — but **honor a larger/explicit option set when intent names one** (this default is a floor, not a cap). Text-only by default (images only when `imagery` is on — §1, §4). **Keep (seed-time only):** `categoryIds[]` to assign products into their categories; **nothing goes to the handoff** — the frontend lists products and categories **live** (`queryProducts` / `searchProducts` / `queryCategories`), so owner-added products/categories appear with no code change.
+- **blog** — *Initial posts.* Recipe: **`setup-blog.md`**. `intent.blog.postCount` posts on `intent.blog.topics` (or brand-derived topics). Text-only (no covers). **Keep:** nothing for the handoff — posts are discovered **live** (`queryPosts`, `[...slug]` routes). Track created post ids only transiently (to confirm success / assign categories).
+- **cms** — *Content collections.* Recipe: **`setup-cms.md`**. One collection per `intent.cms.collections` entry; `itemCount` items each, content from `brand`. Collections are **public-read** (visitor reads on the frontend) by default. **(Opt-in, members only)** if the brief calls for per-user-private or member-only data **and** members login is in the run, seed that collection **member-scoped** instead (per-user or member-only — see `setup-cms.md`); a per-user collection is seeded **empty** (members populate it), since admin-seeded rows are owned by the admin. **Keep (→ handoff):** `collectionIds{<name>}` + each collection's **field keys** — this is *structural* (the frontend must know the collection name and its fields to query and bind; it doesn't change when an owner adds a row). `itemIds{<name>:[]}` only transiently, for wiring multi-references during seeding.
+- **forms** — *Lead-capture forms.* Recipe: **`setup-forms.md`**. One form per `intent.forms.forms` entry; fields from the entry; `purpose` names the form. **Keep (→ handoff):** `formIds[]` + each form's field **`target`** keys — *structural* (the frontend sets input `name` = target to submit).
+- **events** — *A ticketed or RSVP occasion, or upcoming events.* Recipe: **`setup-events.md`**. Each event is **either `TICKETING`** (paid — it has ticket tiers) **or `RSVP`** (free — the registration form is built-in, so don't seed form fields) per intent. For an **RSVP occasion** (a wedding, party, gathering): one RSVP event with the occasion's real details (title, a **future** date/time, location). For a **ticketed** event: the event plus its ticket tiers (default a single `"General Admission"` tier if none named). For a **listing** site: `intent.events.eventCount` events with brand-appropriate titles and **future** start dates (a default location/timezone is fine). Text-only. **Keep:** nothing for the handoff — events and tiers are discovered **live** (`queryEvents`, `getEventBySlug`, `queryAvailableTickets`); track `eventIds`/`ticketDefinitionIds` only transiently.
+- **bookings** — *Bookable services.* Recipe: **`setup-bookings.md`**. `intent.bookings.serviceCount` services (name + short description fitting `brand`, a simple duration and price); keep the schedule minimal. **Keep:** `serviceIds[]` as **seed-time state** (pricing-plans' coverage step keys on them, below); nothing for the handoff — services are discovered **live** (`queryServices`).
+- **pricing-plans** — *Membership tiers.* Recipe: **`setup-pricing-plans.md`**. `intent.pricing-plans.planCount` recurring plans (name, price, a monthly billing cycle) fitting `brand`. **When bookings is also in this run and the intent is a membership that covers services** (a studio/gym/class pass), also **attach the covered bookings services to the plan** — seed the bookings services first, since coverage keys on their service ids (see the recipe). **Keep:** the bookings coverage only transiently, to wire it during seeding; nothing for the handoff — plans are discovered **live** (`queryPlans`) and plan→service coverage is read **live** at checkout, never from a frozen map (see `how-to-code-pricing-plans.md`).
+- **restaurants** — *A menu.* Recipe: **`setup-restaurants.md`** (add-ons have their own recipes, below). Create the `itemCount` items per section first (name, description, price fitting `brand`), then the `intent.restaurants.sections` referencing those item ids, then the menu referencing the section ids — **items → sections → menu** (build bottom-up: a section is created with its `itemIds`, a menu with its `sectionIds`, so each child must exist before its parent — see `setup-restaurants.md` STEP 1–3). Text-only. **Keep (seed-time only):** `menuId`, `sectionIds[]`, `itemIds[]` to build the tree; nothing goes to the handoff — the frontend reads menus **live** (`listMenus`/`listSections`/`listItems`). **Online ordering (add-on, on demand)** — only when the request calls for ordering (not just a displayed menu): install the Orders app (per `SETUP.md` §2) and follow **`setup-restaurant-orders.md`**; **seed the menu FIRST, then ordering, in the same unit** (ordering auto-provisions per menu either way — see the concurrency note above — but keeping them one unit gives the ordering verify a menu to confirm against). **Keep:** nothing for the handoff — read **live** (`listOperations`/`listFulfillmentMethods`); track `operationId`/`fulfillmentMethodIds[]` transiently. **Table reservations (add-on, on demand, INDEPENDENT of ordering/menu)** — only when the request calls for reservations: install the Table Reservations app (per `SETUP.md` §2) and follow **`setup-restaurant-reservations.md`**; **no menu dependency** (reservations bind to a location, not a menu — do NOT apply the menu-first rule) and **nothing to bulk-seed** (visitors create reservations at runtime); enabling online reservations is **premium-gated** (record the precondition, don't fail). **Keep:** nothing for the handoff — read **live** (`listReservationLocations`); track `reservationLocationId` transiently.
+- **portfolio** — *A project showcase.* Recipe: **`setup-portfolio.md`**. Create the `intent.portfolio.collections` (title + short description fitting `brand`), then `intent.portfolio.projectCount` projects assigned to them — **collections before projects** (a project's `collectionIds` must hold real collection ids; see the recipe). Text-only by default (omit `coverImage`; images only when `imagery` is on — §1, §4). **Keep (seed-time only):** `collectionIds{<name>}` to assign projects into their collections; nothing goes to the handoff — the frontend lists collections and projects **live** (`collections.queryCollections` / `projects.queryProjects`), so owner-added content appears with no code change.
 
-**blog:**
-- Part 0 (member ID lookup) is mandatory. One `GET /members/v1/members?paging.limit=1`; reuse the returned id for every post.
-- `intent.blog.postCount` posts created. Topics from `intent.blog.topics` when present; otherwise pick brand-appropriate topics from `brand.description`.
-- **Use the bulk endpoint** `POST https://www.wixapis.com/blog/v3/bulk/draft-posts/create` for any `postCount ≥ 2`. The recipe's single-post curl is for demonstration; the bulk URL is the production path. (Skipping this and using N single-post creates costs ~30s per post.)
-- Text-only: cover images use the recipe's documented placeholder pattern; no Media Manager import.
+> **Cross-cutting (on demand).** `coupons` is not a standalone capability (`CAPABILITIES.md` § "Cross-cutting capabilities") — there's no app to install and it's not in `verticals[]`. If intent calls for discounts **and** a parent vertical (stores / bookings / events / pricing-plans) is in this run, create coupons scoped to that parent and add the coupon to the `seeded` map (`seeded.coupons = { couponIds[] }`). **Coupons has no inline recipe** — read the create shape from the docs (`DOC_DISCOVERY.md` is the fallback): every coupon needs a scope with a namespace and its parent vertical's app installed (<https://dev.wix.com/docs/api-reference/business-solutions/coupons/about-wix-coupons.md>), and the create-coupon spec needs name/code/start + a scope namespace + exactly one coupon-type field (<https://dev.wix.com/docs/api-reference/business-solutions/coupons/coupons/create-a-coupon.md>). eCommerce needs no seeding — it's the runtime checkout layer that rides along.
 
-**forms:**
-- One `POST /form-schema-service/v4/forms` call per entry in `intent.forms.forms`. Map `intent.forms.forms[N].fields` (string array) into the recipe's `formFields` payload using the documented field templates (`CONTACTS_FIRST_NAME`, `CONTACTS_EMAIL`, etc.).
-- `purpose` ("contact", "lead", "signup") drives the form's `name` — e.g. `"contact"` → `"Contact Form"`.
-- Wix Forms app is pre-installed via Phase 2; don't reinstall.
+> **members — nothing to seed.** Member login is the identity layer (`CAPABILITIES.md`): members **self-register** through the Wix login page, so there is **no member to create** at seed time and nothing lands in `seeded`. The frontend wiring is the `how-to-code-members-*.md` recipes (pick per `SDK_HANDOFF.md`), surfaced via the Handoff. *Optionally* — and **only** if a run's prompt explicitly asks to exercise the pricing-plans purchase path end-to-end — seed one test member; keep this **off by default** so headless runs stay deterministic and don't stall on an interactive login. Do **not** seed a member just because pricing-plans is present.
 
-**bookings:**
-- Recipe path is `<SKILL_ROOT>/references/bookings/SERVICES_DATA.md` — NOT under `<wix-manage-root>`. Resolve the path with `<SKILL_ROOT>` (same root as all other skill references).
-- `intent.bookings.serviceCount` services (default 3). Names + descriptions from `brand`.
-- `intent.bookings.serviceType` (`"APPOINTMENT"` or `"CLASS"`) determines the service `type` field. Default `"APPOINTMENT"`.
-- `intent.bookings.hasStaff === true` → create 2 staff members (names from brand). Skip if false or absent.
-- Wix Bookings app is pre-installed via Phase 2 (app ID `13d21c63-b5ec-5912-8397-c3a5ddb27a97`); don't reinstall.
-- Return `seeded.bookings.services[{id, slug, name, ...}]` + `seeded.bookings.staff[{id, resourceId, name}]`.
+> **Simple seeds (experiment).** For these newer capabilities, create the minimum that demonstrates the shape — a couple of entities with required fields only. The recipe (§2) says which fields are *required* — stop there; don't seed optional structure (variants, multi-session schedules, perks) the host's app won't exercise.
 
----
+## 3 · Enable the backend-backed required features
 
-## Step 2 — Seed domain (recipes, inputs, prompt templates)
+A capability's **Required site features** (`references/CAPABILITIES.md`) are part of a complete site, and some of them need a backend feature switched on — not just content created. The clearest case — **only when the brief asks for it** — is **blog comments** (readers commenting on posts): comments are intent-gated, not a baseline blog feature (`CAPABILITIES.md` blog entry), but when requested they need their backend feature available. For each loaded capability, check its *Required site features*:
 
-The seeders and Image Phase 1 below are launched as one concurrent background batch — that dispatch flow (timing, single-batch discipline, the two-dispatch trap) is owned by the conductor (`BUILD.md`, which routes to the active mode's seed step) / `PLAN.md` § "Batching discipline". This step defines only the seed domain: the pre-batch utilities script, the dispatch rows, the recipe map, the per-pack input notes, and the prompt templates.
+- If one depends on a backend feature that isn't on by default, enable it via the method its recipe documents (or `DOC_DISCOVERY.md` if the recipe doesn't cover it).
+- If it's already on by default, there's nothing to seed — but record it as **available** so the Handoff tells the host to surface it.
+- If it genuinely can't be enabled, note that, so the Handoff doesn't imply the site is complete.
 
-**Pre-batch — `seed-utilities.sh` (project prep):** run the project-prep script once (idempotent). Astro is the only frontend built, so the template is always `astro`:
+Don't silently skip a required feature — a bare list-and-detail with none of its required features is the "half-built site" this is meant to prevent. (Purely presentational items — showing the author, the date — need no backend and belong to the Handoff's *Implementation checklist*, not here.)
 
-```bash
-bash "<SKILL_ROOT>/scripts/seed-utilities.sh" --template astro
-```
+## 4 · Entity images (opt-in)
 
-Execute from the **project directory** (== CWD — the scaffold was flattened in, no subdir). (This is frontend-track project prep, not seeding — custom frontends route to the stub and never reach this article.)
+**Only if `imagery` is on** (from `DISCOVERY.md`). For each seeded image-bearing capability — stores products, blog covers, CMS items, **bookings services**, restaurant items, **portfolio projects + collection covers**, event heroes — generate a brand-contextual image per entity and **attach it as a required pass-2 step** (the seeder created the entity text-first in §2; this writes the image onto it), following `references/IMAGE_GENERATION.md` (generate → import to Wix Media → attach). **The per-entity attach shape lives in that capability's own seed recipe** (`setup-<capability>.md`), next to its create shape — read it there; `IMAGE_GENERATION.md` §3 is a navigation table (entity → recipe → step) that carries no shapes. Use the IDs already in the `seeded` map. Image failures never block — skip and continue (the entity stays text-only). When `imagery` is off, skip this step entirely.
 
-### Wave 3 dispatch table
+## Aggregate
 
-| Subagent                       | Mode | Instruction file                                 | Scope                      |
-| ------------------------------ | ---- | ------------------------------------------------ | -------------------------- |
-| Per-pack seeders (Step 1 list) | bg   | wix-manage recipes (see seeder template)         | `seed` / recipe-driven     |
-| Image Phase 1 Decorative       | bg   | `<SKILL_ROOT>/references/images/INSTRUCTIONS.md` | `image-phase-1-decorative` |
+Hold a `seeded` map in scratch — `seeded[<capability>] = { …kept IDs… }` — as **seed-time working state** (it feeds intra-seed steps like image attach in §4 and cross-capability wiring like pricing-plans coverage). **What crosses into the handoff is only the *schema* carve-outs**, not the per-item content ids: **cms** `collectionId` + field keys, and **forms** `formId` + field `target`s (see `SDK_HANDOFF.md` §4). Everything else the frontend rediscovers with a live query, so it need not be surfaced — carrying a per-item id/slug list into the handoff only tempts the host to hardcode it. Whether to also write a sidecar file is a host-preference choice (default: return-only, in the handoff message).
 
-### Image Phase 1 gate (imagery flag)
+On a per-capability error, keep the other capabilities' results and surface the failing REST-call response verbatim; partial state is fine — a targeted re-run is bounded.
 
-Whether the Image Phase 1 Decorative subagent is dispatched at all (the `ai-generated` vs `themed-blocks` branch) is owned by the conductor (`BUILD.md`). The decorative prompt template below is the seed-side domain for that subagent when it does run.
+## Proceed to Handoff
 
-For each pack on the dispatch list, dispatch a seeder subagent (`Agent` tool with `subagent_type: "general-purpose"`) with the prompt template below. Use `run_in_background: true`.
-
-### Subagent prompt template
-
-```
-You are seeding <pack> content into a Wix site as part of the wix-headless skill's Phase 1 Seed.
-
-Inputs (do not re-derive these — every value is inlined here):
-- brand: <brand JSON — inline from orchestrator scratch>
-- pack: <pack name>
-- intent.<pack>: <intent.<pack> JSON — inline from orchestrator scratch>
-- recipe path(s): <absolute path(s) joined from <wix-manage-root>>
-- siteId: <siteId — inline from orchestrator scratch>
-
-Every input you need is inlined above — do not read any shared state file. Read **only** your own `seeded.json` slice (the one read-only exception, per `IMPLEMENTER.md`).
-
-Steps:
-
-1. **Open with one concurrent batch** (single assistant message, multiple tool calls):
-   - One `Bash` to mint and capture the site-scoped REST token: `TOKEN=$(npx @wix/cli@latest token --site "<siteId>")`. Use `npx @wix/cli@latest token …` (not bare `wix token …`): `@wix/cli` may not be globally installed in every harness.
-   - One `Read` per absolute recipe path you were given. If you have N recipe paths, issue N Reads as siblings — do not serialize them.
-   No narration, no "Reading recipe and minting token:" preamble. Issue the batch.
-
-   > **Mint the token EXACTLY ONCE. Never re-mint.** Inline the captured `$TOKEN` value into every subsequent `curl` and reuse it for the entire seed phase. `npx @wix/cli@latest token --site "<siteId>"` returns a **byte-identical** string on every call within a run (the CLI caches it) **and** each call costs ~1.25 s of CLI startup — so re-minting is pure wasted wall that changes nothing. This holds on errors too: if a call fails, re-minting gives you the same token and the same failure. Do not re-mint to "get a fresh token," do not re-mint "to be safe," do not re-mint as a reaction to any error. One mint, reused everywhere.
-
-2. Fire the recipe's REST calls via `curl` against `wixapis.com`. Every call carries the headers documented in `<skill-root>/references/shared/AUTHENTICATION.md` — `Authorization: Bearer $TOKEN` (the token from Step 1), `wix-site-id: <siteId>`, and `Content-Type: application/json` — plus the recipe's documented body. Construct request bodies from intent.<pack> + brand. **When the recipe documents N independent calls** (e.g., creating N categories, adding products to N categories), issue them as one parallel batch — not sequentially.
-
-   **On any error (401/403/4xx), do NOT re-mint the token** — per the mint-once rule above, the re-minted token is byte-identical and will produce the same result. The token is not the cause. Retry the same call once as-is (covers a transient blip); if it still fails, return `status: "error"` with the response body. Do **not** spend turns debugging the auth call shape or cycling tokens — if the single retry fails, the issue is upstream (expired CLI session, missing app install, or a resource that requires a provisioning step the recipe didn't run), and neither re-minting nor header A/B-testing will recover it.
-
-3. Text-only seeding only — do not call media-manager import or generate AI imagery. Use the placeholder image patterns the recipes document.
-
-4. Collect the IDs the recipe returns and emit them in your return JSON (Return contract below).
-
-Return contract (your sole output channel — end your message with this fenced JSON block, no trailing prose):
-{
-  "phase": "seed-<pack>",
-  "status": "ok" | "error",
-  "seeded": { <pack-specific keys per the SEED.md recipe map "Returns" column> },
-  "recipeCalls": [{ "url": "<endpoint>", "status": <http-status> }, ...]
-}
-
-On error: status="error", include the failing recipe-call response verbatim under "error". Do not retry beyond what the recipe documents — orchestrator owns recovery.
-
-Do NOT write coordination files (`.wix/seed-returns/`, sidecars, etc.). The JSON above is parsed directly from your message by the orchestrator.
-```
-
-The subagent decides per-call payloads from `intent.<pack>` + `brand`. The orchestrator does **not** pre-decompose the intent into per-call payloads; that defeats the point of having a subagent read the recipe.
-
-`gift-cards` and `ecom` have no seed surface, so the orchestrator dispatches no subagent for them and simply moves on. No files involved.
-
-### Image Phase 1 Decorative subagent prompt (background)
-
-Always dispatch in the **same batch** (background). No Phase 1 Seed dependency.
-
-```
-Instruction file (absolute path): <SKILL_ROOT>/references/images/INSTRUCTIONS.md
-Scope: image-phase-1-decorative
-Project directory: <project dir>
-site-root: <site-root>
-siteId: <siteId>
-Brand context: <same as designer prompt>
-decorativeSlots: <string[] — REQUIRED; must match designer vocabulary exactly>
-  Always: ["hero", "about"]
-  Plus "productsHeader" if stores loaded
-  Plus "cmsHeader" if cms loaded (optional page-header decorative)
-```
-
----
-
-## Step 3 — Subagent return contract
-
-Every seeder ends its message with a fenced JSON block per `references/shared/RETURN_CONTRACT.md`:
-
-```json
-{
-  "phase": "seed-<pack>",
-  "status": "ok" | "skipped" | "error",
-  "seeded": { /* pack-specific keys — see Step 1 "Recipe map" Returns column */ },
-  "recipeCalls": [{ "url": "https://...", "status": 200 }]
-}
-```
-
-**Strict on:** `phase` (must equal `seed-<pack>`), `status` (must be `ok`, `skipped`, or `error`).
-
-**Permissive on:** `seeded` keys. Known keys (per the recipe map) pass through verbatim. Unknown keys are kept on `seeded[<pack>]` in orchestrator context so Phase 4 can surface them if needed.
-
-**On error:** the subagent's return additionally carries `error: <failing recipe-call response verbatim>`. The orchestrator keeps that field on the entry it holds.
-
-There are no seed-coordination files **between agents** — seeders return JSON inline, and no seeder writes or reads `.wix/seed-returns/<pack>.json`; the agent return *is* the contract. (This is distinct from `.wix/seeded.json`, which the **orchestrator** writes once at the seed gate from the aggregated returns — not a seeder-authored sidecar. Seeders never touch it; it's a read-only consumer handoff. See Step 4.)
-
----
-
-## Step 4 — Aggregate the seeded map
-
-The seed gate — waiting on seeders + `npm_handle`, and the decorative-slot patch — is owned by the conductor (`BUILD.md`). (`compose.mjs` writes the six design-system files synchronously in the Setup-window bridge; there is no Composer subagent to wait on.) (For npm install failures, see `SETUP.md § npm install recovery`.) This step defines only the aggregation shape.
-
-**Aggregate seeder returns in orchestrator context.** Each seeder's return JSON is in your session context (the harness surfaces it when the subagent completes). Build a `seeded` map keyed by pack from those returns and hold it in scratch.
-
-For each return:
-- `status: "ok"` — keep the `seeded` payload under `seeded[<pack>]`.
-- `status: "skipped"` — record `seeded[<pack>] = {status: "skipped"}`.
-- `status: "error"` — surface the `error` field verbatim. Do **not** autonomously retry; partial state for other packs is intact, so a targeted re-run is bounded.
-
-**Then write the aggregated map to `.wix/seeded.json` — once, at the gate (the conductor owns the timing; see `BUILD-astro.md` § "4. Seed gate" + § "The `.wix/seeded.json` handoff").** This is the producer→consumer handoff the per-vertical readers (astro Phase 4 Pages, own-build wiring) pull their slice from — the orchestrator no longer inlines `seeded.<vertical>` slices into those prompts. (Image Phase 2 is a single dispatch and keeps its inlined slice.) Exactly one writer, written before any reader is dispatched; it carries seeded entity IDs only. The orchestrator is the aggregator **and** the sole writer of this file.
-
----
-
-## Step 5 — Summary sentence
-
-Per `PLAN.md` § "User-facing output", emit one short plain-prose sentence naming what was seeded per pack — no tables, no machinery:
-
-> *"Seeded `<brand>`: `<N>` products in stores, `<M>` items across `<C>` CMS collections, `<P>` blog posts, `<F>` forms. Continuing with components and page build…"*
-
-Adapt the sentence to whichever packs were loaded — drop the irrelevant clauses.
-
----
-
-## Recovery
-
-| Failure mode                                       | What the orchestrator does                                                                                                                                                              |
-| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| One subagent returns `error`                       | Surface the `error` payload verbatim; do not retry. Other packs' `seeded` data is intact in orchestrator scratch, so a re-run of the failing pack alone is bounded.                     |
-| Subagent return has no fenced JSON block           | Per `RETURN_CONTRACT.md` § "Observed failure mode" — the harness falls back to narrative parsing, which is fragile. Surface the issue; retry the failing seeder once with the same prompt. |
-| Recipe path drifted (Read fails inside a subagent) | The subagent should return `status: "error"` with the Read error in `error`. Surface it; the fix is to correct the recipe path in the Step 1 table (and the wix-manage recipe), not retry.                                               |
-| Bulk product create rate limit                     | The stores recipe documents the limit; the subagent fans out into batches of 5 internally. If it still hits a limit, returns `error`.                                                   |
+With `seeded` populated, continue to **`SDK_HANDOFF.md`** to produce the document the host wires from.