@wix/agent-skills 1.7.0 → 1.9.0

package/skills/wix-headless/references/BUILD-astro.md

@@ -0,0 +1,244 @@
+# Build — astro framework class (`frontendBuild === "wix"`)
+
+The post-approval conductor for the **astro-native** class (`create × astro` — the skill scaffolds and writes the site). Opened from `BUILD.md` when the run routes on `frontendBuild === "wix"`. Owns the astro flow: Setup → design-system bridge → Seed → build wave → Build → Release. Read top to bottom from approval.
+
+This file hosts the astro-create **bootstrap cell** (run-step 0: `scaffold.sh` → `npm create @wix/new@latest headless`) and **wiring cell** (the build wave). Shared with the own-build class via `BUILD.md`: **Subagent rate / credit limits**, the **parallel-batch diagnostic**, the **Final Message** (summary + `AGENTS.md`), and the **Shared release tail**. Pre-approval flow + the **Two tracks** / **Batching discipline** / **User-facing output** rules live in `PLAN.md`.
+
+## Phase axis
+
+Each phase is one of the two tracks (`PLAN.md` § "Two tracks"); all are background.
+
+| Phase | Track | Tier | What | When |
+|---|---|---|---|---|
+| **1 — Seed** | business | Fast | Per-pack seeders → orchestrator collects `seeded` map in scratch | Seed wave |
+| **2 — Design System** | frontend | Default (Designer) | **Designer** returns tokens + brand-voice JSON (authors `DESIGN.md`, no other files); **`compose.mjs`** (script, no subagent) writes the 6 files from it | Designer: run-step 0 · compose.mjs: Setup-window bridge |
+| **Image 1 — Decorative** | frontend | Fast | Hero/about/page-header decoratives | Seed wave (imagery-gated) |
+| **3 + 4 — Components + Pages (merged)** | frontend | Default | One merged "build" agent per vertical writes its islands **then** the routes that mount them | Build wave (§ "Step 4.5") |
+| **Image 2 — Entity** | business | Fast | Product/blog/CMS images PATCHed onto Wix entities | Build wave (imagery-gated) |
+
+> **Set the model tier on every dispatch** (`SKILL.md` § "Subagent model tier", by table lookup). Tier is the dispatch primitive's model parameter, not the prompt — omit it and Default-tier roles silently run under-powered.
+
+## The run from approval (Setup → Release)
+
+The contract lives in scratch — no disk snapshot. Nothing is dispatched yet (the funnel presented the plan fast).
+
+### 0. Dispatch scaffold + Designer (background, one concurrent batch on entry)
+
+Independent — fire together (`PLAN.md` § "Batching discipline"):
+- **Scaffold** — `scaffold.sh <folder-name> "<brand>" --frontend <value>` (background; capture `scaffold_handle` + its stderr tempfile). Folder-name + command shape: `DISCOVERY-create.md` § "After Q1". It **flattens the project into CWD** — one folder, one `.wix/`, no subdir to `cd` into (`SKILL.md` § "Path resolution"). `npm install` is **not** chained here (Setup Step 4c). The stderr tempfile is for post-hoc error inspection only — not a progress file to poll.
+- **Designer** — background; capture `designer_handle`. Instruction file = `<SKILL_ROOT>/references/DESIGN_SYSTEM.md` (the subagent opens it — do **not** Read it in the orchestrator). Inline Discovery's aesthetic craft from scratch (brand, aesthetic direction, palette, type, mood, page color strategy). Pass `designMdPath` = `<cwd>/DESIGN.md`. The Designer **authors `DESIGN.md`** (frontmatter = the tokens) and returns only `data.shell` + `designMdPath` — tokens never round-trip through your output. Judgment-only (~10–15 s). Do **not** pass application inputs (packs, nav links) — those go to `compose.mjs`.
+
+### 1. Setup Step 1 (foreground)
+
+`SETUP.md` Step 1 only: wait `scaffold_handle` (load `wix-manage` in the same batch), then hold `siteId`/`appId` (from `wix.config.json`) in scratch. Do **not** run Setup Step 4 yet — it goes in run-step 2. **Wait = await the harness completion notification; never sleep-poll a handle**.
+
+### 2. Setup window — bridge + platform batch as ONE concurrent message
+
+The whole Setup window is a single message of sibling `Bash` calls — **emit them, don't plan them.** It is order-free; the only failure mode is spending a turn deciding an order it doesn't have. The moment Setup Step 1 returns and the Designer has returned, fire the bridge **and** the platform batch together. `designer_handle` authored `DESIGN.md`; the bridge scripts read it directly — never re-emit tokens in your output.
+
+**Frontend bridge — one `Bash` call, two deterministic scripts (both read `DESIGN.md`):**
+
+1. `emit-design-tokens.mjs <project-dir>` — projects `.wix/design-tokens.css` + `.wix/site.d.ts` from `DESIGN.md` frontmatter (format: `references/shared/DESIGN_MD.md`). Does not write `DESIGN.md`.
+2. `compose.mjs` — app inputs on **stdin**, project dir as `argv[2]`. Reads `DESIGN.md` frontmatter (the single token source; roles map to the wix `--color-*` vocabulary) and substitutes into the six pinned skeletons — `global.css`, `astro.config.mjs` (anchored **merge**, not clobber), `Layout.astro`, `Navigation.astro`, `Footer.astro`, `index.astro`. Prints a `{status, phase:"compose", data, files}` manifest to **stdout** — parse it there. **astro-only** (defensive — non-astro classes never reach here); else record `{phase:"compose", status:"skipped"}`. Idempotent; derives any role the Designer omitted as a fail-safe.
+
+   ```bash
+   node <SKILL_ROOT>/scripts/emit-design-tokens.mjs "<project-dir>"
+
+   node <SKILL_ROOT>/scripts/compose.mjs "<project-dir>" <<'COMPOSE'
+   {
+     "shell": { ...the Designer's data.shell... },
+     "brand": { "name": "<brand>", "description": "<one-line context>" },
+     "navLinks": [ { "href": "/", "label": "Home" }, ... ],
+     "loadedPacks": ["stores", "cms", ...],
+     "packsWithComponents": ["stores", "ecom", ...],
+     "disabledPacks": ["gift-cards", ...]
+   }
+   COMPOSE
+   ```
+
+   The compose-input shape is documented in `scripts/compose.mjs`'s header.
+
+**In the SAME message — the business Setup Step 4 batch** (frontend-blind; `SETUP.md` owns recipes/package set). These overlap the bridge's `compose.mjs` (~20 s) so it adds no serial wall:
+
+3. `Bash` × N — app installs, one curl per `pack.apps[*]` → `SETUP.md` § Step 4a. Packs with no `apps[*]` (`cms`, `ecom`, `gift-cards`) install nothing — skip them.
+4. `Bash` — `npx @wix/cli@latest env pull --json` → `SETUP.md` § Step 4b (`--json` suppresses the spinner that bloats context).
+5. `Bash` (background) — `npm install …`, capture `npm_handle` + stderr tempfile → package set in `SETUP.md` § Step 4c. Trust the exit code at the seed gate — do not probe `node_modules`.
+
+### 3. Seed wave + 4. Seed gate
+
+See § "Wave 3" below for the dispatch. The **seed gate**: wait on the seeders + `npm_handle`; aggregate seeder returns into the `seeded` scratch map. Run `patch-decorative-slots.mjs` only when `imagery === "ai-generated"` and Image Phase 1 returned; else skip + record `{phase:"decorative-slot-patch", status:"skipped"}`.
+
+**Write `.wix/seeded.json` here — once, at the gate, before any reader dispatches** (one `Write`, conductor is sole writer). It is the producer→consumer handoff the build-wave readers pull from (§ "The `.wix/seeded.json` handoff"). The gate barriers all seeders before this write and the build wave dispatches only after it, so no reader sees a missing/partial file. Skipped packs → `{"<pack>": {"status":"skipped"}}` so a reader can tell "seeded nothing" from "not written yet" (the latter must never happen).
+
+### 5. Continue → the build wave (§ "Step 4.5") → Build & Release → Final message.
+
+## Imagery gates
+
+`imagery` (`"ai-generated"` | `"themed-blocks"`, captured `DISCOVERY.md` Q2.5, default `"themed-blocks"`) gates **both** image phases. The conductor owns the gate.
+
+- **Image Phase 1 — Decorative** (Wave-3 batch): dispatch the `image-phase-1-decorative` subagent (`<SKILL_ROOT>/references/images/INSTRUCTIONS.md`) **only on `ai-generated`**. On `themed-blocks`: don't dispatch (slots render as tokenised color blocks via compose-emitted CSS), record `{phase:"image-phase-1-decorative", status:"skipped", notes:"themed-blocks mode"}`, and skip `patch-decorative-slots.mjs`. Dispatching regardless wastes ~140–175 s + ~0.3–0.5 Wix AI credits.
+- **Image Phase 2 — Entity** (build-wave batch): same gate — dispatch only on `ai-generated`; on `themed-blocks` skip + record `{phase:"image-phase-2-entity", status:"skipped"}`. Dispatch + build gate: § "Step 4.5" and § "Wait: build wave → Build".
+
+---
+
+## Wave 3 — Seed + frontend prep + Image Phase 1
+
+One concurrent batch (`PLAN.md` § "Batching discipline"). No design-system work here — `compose.mjs` already wrote the six files in the bridge.
+
+- `seed-utilities.sh --template astro` — frontend project prep (idempotent), from the project dir. `SEED.md` § "Pre-batch".
+- Per-pack seed subagents (background) — `SEED.md` recipe map + seeder prompt template.
+- Image Phase 1 Decorative (background) — only on `ai-generated` (§ "Imagery gates").
+
+### Subagent dispatch
+
+Base prompt fields: `SEED.md` § "Subagent prompt template". Each merged build agent is dispatched with *"read your `<vertical>` slice from `.wix/seeded.json`"* — the page side reads its slice itself (§ "The `.wix/seeded.json` handoff") — and *"read `.wix/design-tokens.css` for the token vocabulary"*; the orchestrator does **not** inline the token block (§ "Styling contract coordination"). (Image Phase 2's single slice stays inlined.) Subagents read no shared state except their own `.wix/seeded.json` slice and the on-disk design-token artifacts (read-only).
+
+**`Instruction file` per loaded vertical** (one merged build agent each, writes components then pages in one dispatch):
+- `stores/INSTRUCTIONS.md` — components + pages (private pages merge; `pages-home-and-nav` is the serialized shell agent)
+- `ecom/INSTRUCTIONS.md` — components + cart/thank-you pages + CartBadge nav mount (shell chain; passive, required by stores)
+- `cms/INSTRUCTIONS.md` — CMS pages (no components scope)
+- `blog/INSTRUCTIONS.md` — components + pages (private — own `src/pages/blog/*`)
+- `forms/INSTRUCTIONS.md` — components + pages (private)
+- `bookings/INSTRUCTIONS.md` — components + pages (shell chain — patches `Navigation.astro` `<!-- nav:links -->` + `index.astro` `<!-- home:bookings -->`)
+- `gift-cards/INSTRUCTIONS.md` — components + pages (shell chain; passive/dashboard-gated)
+- `images/INSTRUCTIONS.md` — `image-phase-1-decorative` + `image-phase-2-entity` (image subagents also get: page list, entity types to cover)
+- `DESIGN_SYSTEM.md` — Phase 2 Designer (no Composer subagent — `compose.mjs` writes the six files)
+- `astro/designer/INSTRUCTIONS.md` — page-design spec applied by the merged build agents while writing routes (not a separate dispatch)
+
+Merged build agents **read `.wix/design-tokens.css` from disk** for the token vocabulary (gate-verified present at § "Step 4.5") — the orchestrator does **not** inline the styling-contract block (§ "Styling contract coordination").
+
+**Every subagent ends with the return contract** (`references/shared/RETURN_CONTRACT.md`); the orchestrator parses each return as it arrives. Put the closing line in the dispatch prompt **verbatim** — it's the only copy a leaf agent is guaranteed to see:
+
+```
+Return contract (your sole output channel — end your message with this fenced JSON block; it MUST be the last content, no trailing prose, no "**What was done:**" recap after it):
+{ ...the data shape for your scope, per references/shared/IMPLEMENTER.md § "Return contract"... }
+```
+
+---
+
+## The `.wix/seeded.json` handoff
+
+Seeded entity IDs reach the build-wave Page readers through a **write-once, read-only shared artifact** — not by re-inlining a slice into every prompt. The conductor writes it once at the seed gate; each reader reads its own `<vertical>` slice. (Image Phase 2 keeps its inlined slice; Phase 3 Components need no seeded IDs.) It is a safe exception to the "inputs inlined / don't read shared state" rule.
+
+**Scope of the exception (all three must hold):**
+- exactly one writer — the conductor at the seed gate, before any reader dispatch;
+- readers read only their own `<vertical>` slice; no reader writes the file;
+- it carries seeded entity IDs only, never observability fields.
+
+**Location:** `.wix/` (outside the Astro/Vite bundler root, so it never ships to `dist/` — same as `.wix/design-tokens.css`). Readers `Read` it to author code (slugs, `getStaticPaths`, demo content); pages query the live SDK at request time and **must not `import` it** into route files.
+
+**Schema** — one top-level key per loaded pack, mirroring the `seeded` scratch map:
+
+```json
+{
+  "stores": { "products": [{ "id": "...", "name": "...", "slug": "...", "variantId": "...", "price": 0 }], "productIds": ["..."], "categoryIds": ["..."] },
+  "cms":    { "collectionIds": { "about": "...", "faq": "..." }, "itemIds": { "about": ["..."], "faq": ["..."] } },
+  "blog":   { "postIds": ["..."], "categoryIds": ["..."] },
+  "forms":  { "formIds": ["..."] }
+}
+```
+
+Packs that seeded nothing → `{"<pack>": {"status":"skipped"}}`. Exact per-pack keys = the seeders' `Returns` column in `SEED.md` § "Recipe map".
+
+**Reader failure mode (fail loud):** a reader asserts its slice is present before using it. If the file or slice is absent → `status:"partial"`, `errors:[{code:"SEEDED_JSON_SLICE_MISSING", missing:"seeded.<vertical>"}]`. Do **not** render an empty page or fall back to re-querying via curl — a missing slice means an upstream phase didn't complete.
+
+---
+
+## Step 4.5 — the build wave (Components + Pages merged per vertical) + Image Phase 2
+
+ONE wave of per-vertical "build" agents, each writing its **components first, then the pages that mount them** — the within-agent write-order replaces the old cross-agent barrier, so the orchestrator never re-enters between components and pages. Image Phase 2 rides this wave. All background.
+
+**Gate (from the seed gate):** `seeded` populated, `.wix/seeded.json` written, bridge run. Verify **both** `.wix/design-tokens.css` **and** `.wix/site.d.ts` exist on disk, and `compose.mjs` wrote `src/layouts/Layout.astro` + `src/styles/global.css`. If a design-tokens file is missing, do not dispatch — surface the path and stop. (Each merged build agent reads `.wix/design-tokens.css` itself for the token vocabulary — the orchestrator does **not** read it or inline it into dispatch prompts, which would re-emit the full token block once per agent for no benefit; the cascade reaches components through `global.css`, not the prompt.)
+
+### Pre-batch (same message, before dispatches) — ALL pre-copies up front
+
+**1 · Per-pack component-CSS templates** (deterministic `cp`; static `var(--token)` CSS, no subagent). `compose.mjs`'s Layout imports `src/styles/components-<pack>.css` for every pack with `components`; **skip this and `astro build` fails with `Could not resolve "../styles/components-<pack>.css"`.** For each loaded pack with a `components` scope (today: `stores`, `ecom`, `blog`, `forms`, `gift-cards`, `bookings`):
+
+```bash
+for pack in <loaded packs with components>; do
+  cp "<SKILL_ROOT>/references/astro/templates/$pack/components-$pack.css" \
+     "src/styles/components-$pack.css"
+done
+```
+
+Idempotent. Packs without a template (`cms` — SSR inline) are skipped silently.
+
+**2 · Pre-copied utility templates** (both components- and pages-phase utils, since one agent imports both). Each vertical's INSTRUCTIONS lists files under "Pre-copied by the orchestrator (do NOT write these yourself)":
+
+```bash
+# stores (loaded)
+cp "<SKILL_ROOT>/references/astro/templates/stores/back-in-stock.ts" "src/utils/back-in-stock.ts"
+cp "<SKILL_ROOT>/references/astro/templates/stores/categories.ts"     "src/utils/categories.ts"
+# ecom (loaded)
+cp "<SKILL_ROOT>/references/astro/templates/ecom/discounts.ts"        "src/utils/discounts.ts"
+# bookings (loaded) — the booking SDK module + SeoTags
+cp "<SKILL_ROOT>/references/astro/templates/bookings/bookingDriver.ts" "src/components/bookingDriver.ts"
+cp "<SKILL_ROOT>/references/astro/templates/bookings/SeoTags.astro"    "src/components/SeoTags.astro"
+```
+
+`categories.ts` is imported by `pages-categories`/`pages-products`/`pages-home-and-nav`; `back-in-stock.ts` by stores components; `discounts.ts` by ecom components + stores product pages; `bookingDriver.ts` (the ecom-Cart-V2 booking sequence — `book()`/`navigateToCheckout()`) by the bookings islands, and `SeoTags.astro` by `services/[slug].astro`. Static, brand-agnostic SDK wrappers — if not pre-copied, multiple scopes race to author them.
+
+### Dispatch the wave — one concurrent batch (private agents) + a serialized shell chain alongside it
+
+One merged "build" agent per loaded vertical (Instruction file = that vertical's `INSTRUCTIONS.md`), owning its `components` scope **and** its private `pages` scopes, written islands-first then pages. Split by whether the agent's scopes touch a **shared shell** (`src/components/Navigation.astro` or `src/pages/index.astro`):
+
+**A · Concurrent batch — agents that own only private files:**
+- **stores-build** — `components` (AddToCartButton, ProductPurchase, BackInStockForm, SeoTags) → `pages-categories` (`category/[slug].astro`, `CategoryRail.astro`) → `pages-products` (`products/index.astro`, `products/[slug].astro`, `ProductCard.astro`). **Write order matters: islands → `pages-categories` (writes `CategoryRail.astro`) → `pages-products` (mounts it)** — every import a later scope mounts is already on disk.
+- **blog-build** — `components` (blog service module, RicosViewer, consts) → `pages` (listing, detail, RSS, BlogPost layout, all under `src/pages/blog/*`). No `home:` marker → no shared-shell patch, stays concurrent.
+- **cms-build** — `pages` (About + FAQ wired to live `@wix/data`). No `components` scope.
+- **forms-build** — `components` (ContactForm island) + `pages` (`contact.astro`, private).
+
+**B · Serialized shell chain — agents that patch `Navigation.astro` / `index.astro`** (read-modify-write a shared file → concurrent dispatch trips the staleness guard `File has been modified since read`, **per-file, not per-marker**). **Launch one, wait for its return, launch the next** — each sees the previous one's insertion. Runs **alongside** batch A, not after it. The shell-patchers (today): **ecom, stores `pages-home-and-nav`, bookings, gift-cards** — exactly the packs with `nav:`/`home:` markers:
+- **ecom-build** — `components` (CartView, CartBadge) → `pages` (`cart.astro`, `thank-you.astro` private, **+ CartBadge mount in `Navigation.astro` at `<!-- nav:actions -->`**).
+- **stores-home-and-nav** — patch `index.astro` product grid at `<!-- home:stores -->` + `Navigation.astro` Shop submenu at `<!-- nav:links -->`. Writes no islands; pure shell-patcher.
+- **bookings-build** — `components` (AvailabilityCalendar, BookingForm, ServiceBookingFlow islands; `bookingDriver.ts` + `SeoTags.astro` are pre-copied) → `pages` (`services/index.astro`, `services/[slug].astro`, `ServiceCard.astro`, `booking-confirmation.astro` private, **+ Services link in `Navigation.astro` at `<!-- nav:links -->` / services teaser in `index.astro` at `<!-- home:bookings -->`**).
+- **gift-cards-build** — `components` (probe util, GiftCardPurchase island) → `pages` (gift-cards landing + `Navigation.astro` `<!-- nav:links -->` / `index.astro` `<!-- home:gift-cards -->`).
+
+Cross-vertical imports (`stores-home-and-nav` importing `CategoryRail`/`ProductCard`/`utils/categories.ts`) resolve at **build time**, not write time, so they impose no write-ordering between the chain and batch A. The only ordering: (i) shell-patchers serialize against each other (per-file), (ii) everything is on disk before Build.
+
+**C · Image Phase 2 Entity** (imagery-gated) — same batch, background. Not dispatched on `themed-blocks`. On `ai-generated` with entities in `seeded`, dispatch it; the prompt **inlines** the `seeded.<pack>` slice (entity IDs + names + descriptions) + brand context (`images/INSTRUCTIONS.md` § "Scope: image-phase-2-entity"). It overlaps the whole wave, gated only at Build.
+
+### Merged-agent prompt additions (per vertical)
+
+```
+Scopes (write in this order — islands/components FIRST, then pages, and a page-scope that writes a shared component before the page-scope that mounts it): <e.g. components, pages-categories, pages-products>
+Files to own (absolute paths): <union of the scopes' files from the vertical's pack frontmatter>
+Phase 1 Seed data: read your `seeded.<vertical>` slice from `.wix/seeded.json` (written once at the seed gate; do NOT import it into route files — use it to resolve slugs / getStaticPaths / demo content, then query the live SDK at request time). Fail loud (status: "partial", errors:[{code:"SEEDED_JSON_SLICE_MISSING", missing:"seeded.<vertical>"}]) if your slice is absent — do not render an empty page.
+Styling contract: read .wix/design-tokens.css (on disk, gate-verified) for the token vocabulary — it is NOT inlined. Components do not write CSS (components-<pack>.css is already on disk, and global.css supplies the tokens to the build); use the token names only as the var(--token) / Tailwind utility vocabulary your markup references.
+```
+
+Merged agents MUST NOT:
+- Modify files outside their declared scopes (the union in their prompt)
+- Modify CSS (`global.css` owned by `compose.mjs`; `components-<pack>.css` is pre-copied — never authored)
+- Patch a shared shell unless they are the chain agent assigned to it
+
+---
+
+## Wait: build wave → Build
+
+Wait on **all** build-wave agents — batch A and the full serialized chain B — then:
+- **`ai-generated`** (wave dispatched `image-phase-2-entity`): wait that handle, hard **120 s timeout** from when build agents finish; on timeout, note it and proceed. (It's been running since the wave opened, so the timeout rarely fires.) Skipping this ships previews with entity images still attaching.
+- **`themed-blocks`**: no wait — proceed immediately.
+
+Ensure the background `npm install` (`npm_handle`, waited at the seed gate) exited 0 before Build. On non-zero, follow `SETUP.md` § "npm install recovery".
+
+## Build & Release
+
+1. `npx @wix/cli@latest build` — on failure, inspect `.wix/debug.log`, fix, retry (§ "Build failure modes"; Astro/React build-blockers in `IMPLEMENTER.md`).
+2. `npx @wix/cli@latest release` — extract the published URL from `Site published on <url>`. Also populates the **Frontend link** in headless settings natively. Transient errors (`ECONNRESET`, `ETIMEDOUT`, `EAI_AGAIN`, `STATE_MISMATCH`, `temporarily unavailable`, `try again shortly`) — retry serially up to 3× with `attempt * 5`s backoff. Do **not** retry build failures — those are code bugs.
+
+Then **Final Message** (`BUILD.md` § "Final Message" — summary + `AGENTS.md` turn).
+
+## Styling contract coordination
+
+`.wix/design-tokens.css` + `.wix/site.d.ts` are the coordination artifacts. **`DESIGN.md` is the single source of truth:** the Designer authors it (run-step 0); `emit-design-tokens.mjs` projects the `.wix` artifacts from it; `compose.mjs` reads it to write `global.css` + the other 5 files (run-step 2 bridge). The contract exists before the build wave launches; each merged build agent **reads `.wix/design-tokens.css` from disk** for the token vocabulary (gate-verified present at § "Step 4.5"). The orchestrator does **not** read it or inline it — inlining re-emits the full token block into every dispatch prompt (~one block per vertical per run) for no benefit, since the token cascade reaches components through `global.css`/`@theme`, not the prompt. The on-disk file is the single read source for the agent's token vocabulary.
+
+## Build failure modes
+
+Inspect `.wix/debug.log` after a failed build:
+
+| Failure | Detect | Fix |
+|---------|--------|-----|
+| `Legacy HTML single-line comments` | build stderr | An agent emitted HTML comments in `.astro` frontmatter — replace with `//` or `/* */` |
+| `Missing environment variable WIX_CLIENT_ID` | build stderr | `npx @wix/cli@latest env pull --json` then retry |
+| `Cannot find module '@wix/…'` | build stderr | npm install missed it; check the pack's `packages` list |

package/skills/wix-headless/references/BUILD-own-build.md

@@ -0,0 +1,167 @@
+# Build — own-build framework class (`frontendBuild ∈ {none, own}`)
+
+The post-approval conductor for the **non-astro** framework classes. Opened from `BUILD.md` the moment the run routes on `frontendBuild === "none"` (static HTML, no build) or `frontendBuild === "own"` (own-build SPA — Vite/React/Vue/Svelte, the project's own `npm run build`). This file owns the **framework spine** (install, build) for those classes; the **(operation × framework) bootstrap/wiring cells** and the **shared release tail** are owned by `BUILD.md` and detailed for this file's cells below.
+
+The cross-cutting operational sections both framework conductors share — **Subagent rate / credit limits**, the **parallel-batch diagnostic**, the **Final Message** (summary + `AGENTS.md`), and the **Shared release tail** — live in `BUILD.md`. The pre-approval flow is `PLAN.md` → `PLAN-create.md`/`PLAN-connect.md`; the three cross-cutting rules referenced below — **Two tracks**, **Batching discipline**, **User-facing output** — live in `PLAN.md`. Set the model tier on every dispatch (`SKILL.md` § "Subagent model tier").
+
+> **This file is framework-routed; the *operation* (create/connect/extend) reaches it only through the two cells.** The install/build spine below is operation-blind — it reads only `frontendBuild`. The Bootstrap cell and Wiring cell sections are the operation-specific halves (they read the contract's operation section). Live (operation × framework) pairings on this file: **connect × none** (a brought-in static HTML site), **connect × own** (a brought-in framework SPA), and **create × own** (the skill scaffolds a framework SPA — the companion case). The `extend` operation column is reserved.
+
+## Framework spine — `none` (static HTML)
+
+Operation-blind. The brought design ships as-is; there is **no build**, and `@wix/sdk` loads from a CDN at runtime, so the usual install steps are skipped:
+
+- **Install** — apply `SETUP.md` Step 4a (app installs per inferred capability, with `x-wix-request-id` capture) **only**. **Skip** `env pull` (Step 4b — CDN `@wix/sdk` inlines the `appId` from `wix.config.json`, needs no `WIX_CLIENT_ID`, and the `init`-bootstrapped project has no `env` command), **skip** the Step 4c per-pack `npm install` (CDN imports), and **skip** `scaffold.sh` / `seed-utilities.sh`.
+- **Build** — **none.** The HTML is the deployable. Proceed straight to the shared release tail.
+
+## Framework spine — `own` (own-build SPA)
+
+Operation-blind. A client-build single-page app (Vite + React/Vue/Svelte or similar) that ships its **own** build. `@wix/sdk` is **bundled**, not CDN-loaded, and the app is **built before release**.
+
+**Framework-agnostic by construction — read this before touching anything framework-specific.** The skill carries **no per-framework instructions** (there is no `references/vite/`, no `references/vue/`):
+- **Runtime is identical across every framework.** All of them call Wix through the same `@wix/sdk` modules (`createClient`, `OAuthStrategy`, `@wix/data`/`@wix/forms`/…). The wiring writes the *same SDK calls* whether the host is React, Vue, or Svelte — only the surrounding idiom differs (`useEffect` vs `onMounted` vs a store). The wiring agent adapts the idiom to whatever framework it finds.
+- **Build is framework-dependent and derived, never hardcoded.** Each framework builds differently and `wix build` builds **astro only** — so for `own` you run the **project's own build command**. Derive the specifics from the project itself — its `package.json` scripts (`build` is the near-universal name), the framework config file (`vite.config.*`, `svelte.config.*`, …), and the framework's official docs via whatever doc source is available (web search, or a docs MCP **only if the user has one — never assume it**). React + Vite is the eval fixture, never a special case.
+
+- **Install** — `SETUP.md` Step 4a (app installs per inferred capability, with `x-wix-request-id` capture). Then **bundle the SDK**: in the project dir, `npm install @wix/sdk` + the capability modules the connection needs (`@wix/data` for a CMS persistence swap, `@wix/forms`, `@wix/stores`, `@wix/bookings` + `@wix/redirects` for bookings, …) as real dependencies, so the bundler includes them. **Skip** `env pull` (the `appId` is inlined from `wix.config.json`, no `WIX_CLIENT_ID` at runtime) and **skip** the CDN-only `none` path. Capture timing as a `npm-install` phase.
+  - **One install, backgrounded, never verified.** Run this as a **single** `npm install` (all `@wix/*` modules in one command — do **not** split into per-module installs) **in the background** (capture `npm_handle`, wait it at the seed gate, like astro's `SETUP.md` Step 4c). The `npm install` exit code is authoritative — **do not** follow it with filesystem probes (`ls node_modules`, "check `package.json` for the deps", "confirm packages landed in the right dir"). This verification burns orchestrator wall for zero signal; trust the exit code. The app's own **framework** deps (e.g. `react-router-dom`) are **not** the orchestrator's job — the app-gen subagent installs whatever it imports (see § "create × own (companion case)"), so there is no second orchestrator `npm install` after app-gen returns.
+- **Build** — run the **project's own build** (`npm run build`, confirmed against `package.json` `scripts`), producing the static output dir (commonly `dist/`). Then point `wix.config.json.site.outputDirectory` at that dir. This is **step 1 of the shared release tail** for `own`; never `wix build`. A build failure is a **code bug** — fix it (or report it), do **not** retry blindly (`BUILD-astro.md` § "Build failure modes").
+
+## The run from approval — `none` tenant (connect × none)
+
+The user just approved; the contract lives in scratch — no disk snapshot. **Nothing is dispatched yet.** The frontend-track playbook is `<SKILL_ROOT>/references/custom/INSTRUCTIONS.md` (the conductor follows its § "The flow"; the subagents open the per-capability guides). The run:
+
+1. **Bootstrap cell (connect × none)** — see § "Bootstrap cell" below.
+2. **Setup (business track) — app installs only.** Apply the framework-spine install rule above (`SETUP.md` Step 4a; skip 4b/4c).
+3. **Seed (business track) — DISPATCH seeders as subagents, do NOT inline.** This is the **same per-pack seeder-dispatch model as astro** (`SEED.md` + `BUILD-astro.md` § "Wave 3"): fire **one seeder subagent per capability** that has a seed recipe, as a single concurrent background batch; capture a handle per seeder. Backend creation the augmentation needs — the **Wix Form definition** (forms), a **CMS collection + items** (cms), products/posts (stores/blog), services + staff + CLASS sessions (bookings, recipe within-skill at `references/bookings/SERVICES_DATA.md`) — is each a seeder subagent. **Never run seeding inline in the orchestrator:** the number of seeders is unpredictable (it scales with the brought-in site's content), and inlining serializes the work and bloats the orchestrator's context — exactly the failure the per-pack dispatch exists to prevent. Collect each seeder's returned IDs / form IDs at the gate, then write the aggregated map **once** to `.wix/seeded.json` before dispatching any wiring / Image Phase 2 reader — the same write-once handoff as astro (`BUILD-astro.md` § "The `.wix/seeded.json` handoff"). Wiring + Image Phase 2 read their slice from that file instead of receiving seeded IDs inlined.
+   - **A simple connection plan does NOT license inline seeding — these are independent decisions.** When a site has no dynamic regions (e.g. a one-page invite whose only connection is a single RSVP form), it is fine to *reason out the connection plan inline* — an empty binding map + one augmentation needs no subagent. **But that says nothing about seeding.** The Form/collection/products **still get created by a seeder subagent**, even when there is exactly one seeder and the schema is obvious. Do not generalize "the plan was trivial, so I'll do it all myself" into running the form-schema build + create-form API call inline — that is the `integration-inline` regression (inline Forms-install-retry + RSVP-schema work bloating the orchestrator's context). The floor is: **plan inline if trivial → seed via subagent always.**
+4. **Wiring cell (connect × none)** — see § "Wiring cell" below.
+5. **Release** — the **shared release tail** (`BUILD.md` § "Shared release tail"): `none` has no build, so run `npx @wix/cli@latest release` directly. See § "Release" below.
+
+## The run from approval — `own` tenant
+
+The user just approved; the contract lives in scratch — no disk snapshot — and `frontendBuild: own` is in scratch. The frontend-track playbook is still `<SKILL_ROOT>/references/custom/INSTRUCTIONS.md` (the connection model is framework-blind); only the *mechanics* below differ from `none`. The run differs by **operation**:
+
+1. **Bootstrap cell** — `connect × own` (a brought-in SPA: connection plan + `init` over the source) or `create × own` (the companion case: two concurrent tracks — a foreground **`scaffold → init`** siteId track and a background **Designer → tokens → app-gen** frontend track). See § "Bootstrap cell". **`init` is the run's gate — run it first; Setup begins the moment it returns the siteId, not when the whole bootstrap finishes.**
+2. **Setup (business track) — app installs + bundle the SDK.** Apply the `own` framework-spine install rule above: `SETUP.md` Step 4a app installs, then `npm install @wix/sdk` + capability modules in the project dir. Skip `env pull`. **Gated only on the siteId from `init`** — start as soon as `init` returns; do not wait on the Designer / app-gen track, which runs in parallel.
+3. **Seed (business track) — DISPATCH seeders as subagents** (+ Image Phase 1 Decorative, gated). Same per-pack seeder-dispatch model as the `none` tenant and astro (`SEED.md`). Fires right after Setup, still concurrent with the frontend track. For a **persistence swap**, the cms seeder creates a **public-read CMS collection** whose schema is the connection plan's `persistenceSwap.inferredShape` (one collection per entity-shape — e.g. `Lists` + `Todos`), and returns the `collectionId`(s). In the **same concurrent batch**, dispatch `image-phase-1-decorative` when `imagery === "ai-generated"` (§ "Imagery gates (own)"). Collect seeder IDs + the Phase-1 slot→URL map at the gate; at the gate, write that map to `src/decorative-images.json` (see § "Imagery gates (own)").
+4. **Wiring cell** — `connect × own` (rewrite the source data layer to `@wix/data`) or `create × own` (write a fresh data module). See § "Wiring cell". In the message that opens this cell (post seed-gate, entities exist), also dispatch **Image Phase 2 Entity** when `imagery === "ai-generated"` (§ "Imagery gates (own)").
+5. **Build + Release** — the **shared release tail** (`BUILD.md` § "Shared release tail"): for `own`, step 1 runs the project's own `npm run build` and points `outputDirectory` at the build output (`dist/`), then `npx @wix/cli@latest release`. See § "Release" below. **On `ai-generated`, wait the Image Phase 2 handle (120 s cap) *before* `npm run build`** (§ "Imagery gates (own)").
+
+## Bootstrap cell
+
+> **(operation × framework) cell.** Owned conceptually by `BUILD.md` § "The two (operation × framework) cells"; the content lives here (read-isolation — only the own-build conductor loads it). Three live tenants: **connect × none**, **connect × own**, **create × own**.
+
+### connect × none
+
+**Normalize the entry HTML to `index.html` FIRST — before dispatching the connection plan.** Wix static hosting serves `index.html` at the site root (`/`); an entry under any other name publishes but the live root URL has no document to serve and errors at runtime — a failure `release` does **not** catch (it only confirms the upload). So as the first action of this cell, if the entry HTML is not named `index.html`, rename it (`mv "<entry>.html" index.html`) and fix any internal references to the old name. Doing this before the connection plan keeps the binding map, the wiring cell, and `outputDirectory` all keyed on `index.html`.
+
+**Connection plan (background) + init (foreground), as the entry batch:**
+- **Connection plan** — dispatch one subagent with Instruction file `<SKILL_ROOT>/references/custom/CONNECTION_PLAN.md`; inline the site's file list (now keyed on `index.html`) + inferred capabilities (from the contract's operation section / Discovery scratch). Capture `connplan_handle`. It returns the binding map + augmentation spec (JSON).
+- **Init** — `npm create @wix/new@latest init` in the project dir (foreground; non-interactive when logged in). Then **fix `wix.config.json.site.outputDirectory`** to the dir holding the (now-`index.html`) entry HTML (init defaults it to `./dist`), and hold `siteId`/`appId` in scratch (durable source: `wix.config.json`) (`SETUP.md` Step 1 shape). Init registers the OAuth app's `allowedDomains` for the published origin — **no separate OAuth call needed.**
+
+### connect × own
+
+A brought-in framework SPA. **Connection plan (background) + init (foreground), as the entry batch** — same shape as connect × none, with two `own` differences:
+- **Connection plan** — dispatch the `CONNECTION_PLAN.md` subagent as for `none`, but inline `frontendBuild: own` so it reads **un-built `src/**` source** and emits a `persistenceSwap` (not an empty binding map). Capture `connplan_handle`.
+- **Init** — `npm create @wix/new@latest init` in the project dir (the SPA repo). **Do NOT fix `outputDirectory` to the source dir** — for `own` it points at the **build output** (`dist/`), set later by the release tail *after* the build. Hold `siteId`/`appId` in scratch (durable source: `wix.config.json`). The source SPA is untouched at bootstrap (wiring edits it later).
+
+### create × own (companion case — scaffold a framework SPA)
+
+No brought-in site; the prompt explicitly named a framework (`DISCOVERY.md` Wave 0 resolved `operation: create`, `frontendBuild: own`). Bootstrap runs **two concurrent tracks**, both opened in the **first dispatch message** after approval.
+
+> **Open both tracks in ONE message.** Put the foreground scaffold/init Bash and the background Designer Agent in the **same** dispatch message — they run concurrently (the foreground Bash blocks that message until it returns; the background Agent keeps running). Scaffold+init is the critical path; the Designer rides alongside.
+
+- a **siteId track** (foreground, **the critical path**): `scaffold → init` — produces the **siteId**, which **every backend step is blocked on** (Setup app-installs, all seeders, both image phases). Nothing on this track depends on the Designer, the tokens, or the generated app.
+- a **frontend track** (background): `Designer → emit tokens → generate app` — produces the SPA the wiring cell edits.
+
+**Run `init` as early as possible — it is the run's true gate.** Its only dependency is the scaffolded project dir + the user's approval; it does **not** wait on the Designer. So: scaffold, then `init`, **immediately and in the foreground**, while the Designer runs in the background. **The moment `init` returns the siteId, kick off run-step 2 (Setup) → run-step 3 (Seed + Image Phase 1)** — do **not** wait for the frontend track. The two tracks rejoin at the **Wiring cell** (needs app-gen done *and* seed done).
+
+**siteId track — `scaffold → init` (foreground, FIRST):**
+- **Scaffold** — run the framework's own create command, non-interactively, in the working dir, then `npm install`. Derive the exact command from the named framework (it is **not** hardcoded — pick the framework's documented create command; e.g. `npm create vite@latest … -- --template react` for React/Vite, the analogous command for Svelte/Vue/etc.). This replaces astro's `scaffold.sh` (astro-only). **Do not** use a `npm create @wix/new` template flag — scaffold-then-`init` is framework-general.
+  - **Single-folder requirement — the project MUST end up in the current directory, not a nested subdir** (one `.wix`, CWD == project == site-root, same as astro — `SKILL.md` § "Path resolution"). Scaffolders differ, so handle whichever you get: if the create command can scaffold **in place** (a `.` target or `--cwd`/in-place flag), use that. Otherwise scaffold into a **temp subdir** and run **`bash <SKILL_ROOT>/scripts/flatten.sh <temp-subdir>`** — the framework-agnostic, tested flatten that moves every entry (incl. dotfiles) up into CWD and folds the scaffold's `.wix/` into the existing one without clobbering existing `.wix/` entries (`mv -n`). Don't hand-write the `mv`/`rsync` logic; `flatten.sh` is the equivalent of what `scaffold.sh` does for astro.
+- **Init** — `npm create @wix/new@latest init` over the scaffolded project (now in CWD), **the moment it exists** (do not gate it on `designer_handle`). Hold `siteId`/`appId` in scratch (durable source: `wix.config.json`); point `outputDirectory` at the build output later (release tail). This is the step that unblocks the entire business track — treat its return as the signal to start Setup.
+  - **Run `init` bare — no flags.** `npm create @wix/new@latest init` takes **no `--business-name`** (that flag is the astro `headless` scaffolder's, not `init`'s) and no other positional args here; the site is created under the logged-in account. Do **not** speculate about flags — run it as written.
+  - **`init` writes `wix.config.json` (`siteId`, `appId`) — read them into scratch; nothing else to reconcile.** It writes `wix.config.json` and its own `.wix/` entries: `init` → read `wix.config.json` → hold `siteId`/`appId` in scratch. There is no clobber to guard against.
+
+**frontend track — `Designer → emit tokens → generate app` (background, concurrent with the siteId track):**
+- **Designer (background, dispatched in the same first message as the scaffold).** Dispatch the Designer (`<SKILL_ROOT>/references/DESIGN_SYSTEM.md`), inlining the vibe/aesthetic craft held in scratch from Discovery — **identical to the astro branch** (`BUILD-astro.md` run-step 0). It **authors `DESIGN.md`** at the `designMdPath` you pass (`<site-root>/DESIGN.md` — the run dir, which exists) and returns `data.shell` + the `designMdPath` — framework-agnostic, identical to the astro branch (`BUILD-astro.md` run-step 0), so the tokens never round-trip through your output. Capture `designer_handle`. **Only the astro `compose.mjs` (the 6 astro files) is skipped on this branch — not the Designer.**
+- **Emit design tokens + placeholder decorative map** — once `designer_handle` returns and the project dir exists, run `node <SKILL_ROOT>/scripts/emit-design-tokens.mjs "<project-dir>" --design-md "<site-root>/DESIGN.md"` (the Designer wrote `DESIGN.md` at `<site-root>` in run-step 0; `--design-md` points the projector at it explicitly, robust whether the project flattened into CWD or a scaffolder left it nested): projects `.wix/design-tokens.css` + `.wix/site.d.ts` into the project from its frontmatter. **Do NOT run `compose.mjs`** — it writes astro files. Then write a **placeholder decorative map**: `: | node <SKILL_ROOT>/scripts/write-decorative-json.mjs "<project-dir>"` (empty stdin → `src/decorative-images.json = {}`), so the generated app builds and renders themed blocks even if Image Phase 1 never runs (themed-blocks mode, or a Phase-1 failure). The real URLs overwrite this at the seed gate (§ "Imagery gates (own)").
+- **Generate the initial app (first cut: minimal scaffold).** Produce a small, clean app — a few components — that **imports `.wix/design-tokens.css`** (or copies it into the app's styles) so the brand palette/type apply as CSS custom properties (`var(--color-paper)`, `var(--font-display)`, …) and `data.shell` strings fill the hero/nav copy. This is the **brand's look on the SPA** — real tokens, not invented ones. **Decorative images:** the app must `import` `src/decorative-images.json` and render a **`hero`** image from `decorativeImages.hero` and an **`about`** section image from `decorativeImages.about` — when the value is present render `<img src={…} alt="" loading="lazy" />`, when **empty/absent render a themed block** (`background: var(--color-paper-warm)` with the hero copy over it). **Exactly these two slot keys (`hero`, `about`) — do not invent others** (they must match the `["hero","about"]` set Image Phase 1 is asked for and the credit estimate in `DISCOVERY-create.md` §2.5.1). Astro's framework-specific *component composition* (`compose.mjs`'s 6 files) is **not** re-homed (deferred — SPA plan § Companion case 4b); the **tokens + imagery are**. The app generation is a normal subagent dispatch (inline the DESIGN.md token vocabulary + `data.shell`); the connection then runs over it via the spine below. **App-gen owns the deps it imports** — if it adds a framework library (e.g. `react-router-dom`), it runs that `npm install` itself inside its scope, so the orchestrator never does a follow-up install after it returns.
+  - **Dispatch app-gen the instant `emit-design-tokens.mjs` returns — in the background, concurrent with the *entire* business track** (Setup app-installs, the SDK `npm install`, and all seeders). App-gen depends on none of them (it imports `.wix/design-tokens.css` + `src/decorative-images.json`, both on disk, and calls a data module the Wiring cell writes later); the two tracks rejoin only at the Wiring cell. Fire it early; let it overlap.
+- **Rendering contract for live Wix data — inline these two rules into the app-gen dispatch** (the SPA *owns* its markup + CSS, so unlike astro it gets no pre-sized templates; without these, real data breaks the layout):
+  1. **Constrain every Wix image.** Wix media URLs serve full-resolution images; an `<img>` with no sizing renders at intrinsic size and **overflows its card onto the text**. Every image (product, hero/decorative, CMS) must sit in a slot with a fixed `aspect-ratio` (or `height`) and use `width: 100%; height: 100%; object-fit: cover` — mirror the astro rule in `references/astro/templates/stores/components-stores.css` (`.product-card-media > img`). Never render a Wix image unconstrained.
+  2. **Rich-text fields are HTML — render the plain variant.** A Wix Stores product `description` (and many CMS rich fields) is **HTML/ricos**; rendered as text it shows literal `<p>…</p>` tags. Bind the **plain** field: products → **`product.plainDescription`** (fall back to `description.replace(/<[^>]*>/g, "")` if absent); never bind raw `description` into `textContent`/`{…}`. (The astro path does this at `references/astro/templates/stores/products/[slug].astro`.) Per-capability field paths (product image/price/slug, CMS fields) live in `references/custom/<cap>/WIRING.md` — follow them.
+
+## Wiring cell
+
+> **(operation × framework) cell.** Owned conceptually by `BUILD.md` § "The two (operation × framework) cells"; the content lives here (read-isolation). Three live tenants: **connect × none**, **connect × own**, **create × own**.
+
+### connect × none
+
+**Wiring gate → wire (parallelism is a RUNTIME decision keyed on file topology).** Wait `connplan_handle` + all seeder handles. Each capability's `<SKILL_ROOT>/references/custom/<capability>/WIRING.md` is the how-to; *how many writers* run is decided from the connection plan's `injectAt.file` / region `file` set:
+- **Capabilities share a file (the common single-page case — e.g. one `index.html` with both a form and a feedback list):** wire them with a **single writer** — either inline, or one subagent handling *all* capabilities for that file. **Never dispatch parallel agents at the same file** — they clobber each other's edits and duplicate the SDK bootstrap. This mirrors the astro shared-shell-patcher discipline (serialize writers to a shared file).
+- **Capabilities map to distinct files:** dispatch one wiring subagent per file (concurrent batch) — no conflict.
+
+Inline each agent with its binding-map/augmentation-spec slice + the site's CSS token names; the agent reads its **seeded IDs from `.wix/seeded.json`** (its `<capability>` slice — written once at the seed gate, not inlined). Each injects client-side `@wix/sdk` `<script type="module">` (additive; styled from the design's tokens). The orchestrator decides writer count from the plan; the WIRING guides don't dictate it. (When wiring is run *inline* by the orchestrator rather than dispatched, the orchestrator already holds the seeded IDs in scratch — `.wix/seeded.json` is the read channel for *dispatched* wiring agents.)
+
+### connect × own
+
+The brought-in SPA's data layer is **rewritten in source** to call `@wix/sdk` — **not** a `<script>` injection. The connection plan's `persistenceSwap` entries name the source file + the load/save functions to replace and the seeded `collectionId`(s).
+- **Wire per `persistenceSwap.sourceFile`, not per capability.** Each swap entry targets one source file (e.g. `src/App.jsx`); dispatch one wiring subagent per distinct source file (or inline if one). **Never two writers on the same source file** (same shared-file discipline as `none`).
+- Each writer opens `<SKILL_ROOT>/references/custom/cms/WIRING.md` § "Framework SPA — persistence swap" and rewrites the named `load`/`save` functions/effects to `@wix/data` `query`/`insert`/`update`/`remove` against the seeded collection, using bundled `import { items } from "@wix/data"` (the app `npm install`ed it — **not** the CDN). The component tree, JSX, and styling are untouched. Inline the `appId` (OAuth `clientId`) literally; the agent reads the seeded `collectionId`(s) from its slice in `.wix/seeded.json` (the `persistenceSwap` entry names which collection).
+- The agent adapts to the framework idiom it finds (React `useEffect`/state, Vue `onMounted`/refs, Svelte stores) — the SDK calls are identical; only the surrounding idiom differs.
+
+### create × own (companion case)
+
+The skill controls the source (it scaffolded the app), so there is **no data-layer archaeology** — the wiring agent **writes a fresh data module** (e.g. `src/wixData.js`) exposing the same `load`/`save` surface the generated components call, backed by `@wix/data` against the seeded collection. Same SDK calls as connect × own; the only difference is *write-fresh* vs *rewrite-existing*. `custom/cms/WIRING.md` § "Framework SPA — persistence swap" covers the call shapes. **Gate:** wait the **app-gen** handle *and* the seeder handles before wiring — app-gen fixes the `./wixData` export surface the generated components import, and the seeders return the `collectionId`(s) the module queries. It is **one writer** of `src/wixData.js`, so wiring is a single subagent (or inline), never a parallel batch.
+
+> **Manifest check (two timings for `own`).** Run `node <SKILL_ROOT>/scripts/check-manifest.mjs <project-dir> integration <connection-plan.json>`:
+> - **After wiring, before build** — verifies the *connection*: for `none`, an SDK `<script>` in each binding-map/augmentation `file`; for `own`, the bundled `@wix/sdk` import + a `@wix/data` CRUD call in each `persistenceSwap.sourceFile` (or the fresh data module). The always-connect invariant must hold (exit 1 if zero connections).
+> - **After the build, before release (`own` only)** — re-run with `--build-output <dir>` (e.g. `--build-output dist`) to assert the build output exists and is non-empty, so release publishes the *built* app, not the un-built dev entry that 404s. (For `create × own` with no connection-plan JSON, feed a synthesized `{persistenceSwap:[{sourceFile:"src/wixData.js"}]}` so the same checker verifies the fresh module.)
+>
+> `BUILD-astro.md` § "Build failure modes" applies the same fail-loud discipline.
+
+> **Always connect.** This framework class must end with the site reading from or writing to Wix; `init`+`release` of a static page with no connection is not acceptable (`references/custom/INSTRUCTIONS.md` § "Two locked principles"). The per-capability `custom/<cap>/WIRING.md` guides own the wiring step.
+
+## Imagery gates (own)
+
+The `imagery` flag (`"ai-generated"` | `"themed-blocks"`, captured in `DISCOVERY-create.md` Step 2.5, default `"themed-blocks"`) gates **both** image phases on the `own` branch — exactly as it does on astro (`BUILD-astro.md` § "Imagery gates"; keep the two in sync). Both phases are framework-agnostic: Phase 2 PATCHes Wix-side entities (no frontend dependency at all); Phase 1's decorative URLs reach the SPA through `src/decorative-images.json` (which the generated app imports), **not** through astro's `patch-decorative-slots.mjs` (that script stays astro-only).
+
+> **Generation runs through `generate-images.mjs` (parallel, deterministic).** Both phases' generate-then-import work is the parallelizable, recipe-free half — and when the agent drove it by hand it serialized (traces show product images fired one at a time across turns). Each phase's generation + Wix Media import is now done by `<SKILL_ROOT>/scripts/generate-images.mjs`, which fires every image as a **concurrent single-task request in one process** (`Promise.all`) — no per-turn serialization, and no `google:4@2` N≥3-in-one-request 504 (each task is its own request). Pass the **already-minted** site token via `WIX_TOKEN` (mint-once — `AUTHENTICATION.md`); the script returns a `slots`/`map` of key→URL. Attachment is unchanged and stays where the recipe lives (Phase 1 → `write-decorative-json.mjs`; Phase 2 → the entity PATCH/PUT/publish recipe in `images/INSTRUCTIONS.md` / `plan-entity-image-waves.mjs`).
+
+**The two phases run concurrently — Phase 2 is gated on the entity seeders only, never on Phase 1 or on wiring.** Phase 1 (decorative) depends on brand context alone and rides the seed wave; Phase 2 (entity) needs seeded entity IDs and so cannot start before the seeders return — but the **instant** they do (the seed gate), dispatch Phase 2 in the **same message** that opens the Wiring cell, so it overlaps both Phase 1's tail and the wiring writers. Do **not** spend a dedicated later orchestrator turn on "now dispatch Phase 2" — it is part of the seed-gate batch.
+
+- **Image Phase 1 — Decorative** (seed-wave batch, run-step 3). **Only when `imagery === "ai-generated"`**, generate the `["hero","about"]` slots (the canonical `own` set — matches the app-gen components + the credit estimate) via `generate-images.mjs` (keys = slot names). At the **seed gate**, pipe its `slots` map into `write-decorative-json.mjs` —
+  ```bash
+  echo '<generate-images.mjs .slots JSON>' | node <SKILL_ROOT>/scripts/write-decorative-json.mjs "<project-dir>"
+  ```
+  This rewrites `src/decorative-images.json` with the real URLs **before** the build. On `"themed-blocks"` (default): do **not** generate, leave the placeholder `{}` from bootstrap in place (the app renders themed blocks), and record `{phase: "image-phase-1-decorative", status: "skipped", notes: "themed-blocks mode"}`.
+- **Image Phase 2 — Entity** (opens the Wiring cell, run-step 4; dispatched **in parallel** at the seed gate per the rule above). Only on `ai-generated`, after the seed gate (entities exist): generate the entity images via `generate-images.mjs` (keys = entityIds), then attach them — PATCH Wix entities (`stores/v3/products`, `wix-data/v2/items`, `blog/v3/...`) per the `images/INSTRUCTIONS.md` recipe (428-prevention GETs, `revision`, CMS read-merge-PUT). Inline the `seeded.<pack>` slice (productIds/collectionIds/itemIds + names/descriptions) + brand context — Image Phase 2 is a single dispatch with a battle-tested inline contract, so its slice stays inlined (only the per-file *wiring* agents read from `.wix/seeded.json`). No frontend touch. On `themed-blocks`: skip, record `{phase: "image-phase-2-entity", status: "skipped"}`.
+
+> **The load-bearing ordering:** the seed-gate `write-decorative-json.mjs` overwrite **must precede `npm run build`** (Release step 1). Vite resolves the `src/decorative-images.json` import at build time, so a build run before the overwrite ships themed blocks even in `ai-generated` mode. The bootstrap placeholder + the seed-gate overwrite both run before Release, so the order holds — do not move the build earlier.
+
+## Release
+
+Apply the **shared release tail** (`BUILD.md` § "Shared release tail"). Step 1 (build) is **framework-keyed**:
+
+**`none`** — no build; the HTML is the deployable. **Before releasing, confirm the entry HTML in `outputDirectory` is `index.html`** (the bootstrap rename in connect × none — re-verify here, because a non-`index.html` entry publishes "successfully" yet the live root URL errors at runtime, and `release` won't flag it). Then run release directly:
+
+```bash
+test -f "$(node -p "require('./wix.config.json').site.outputDirectory")/index.html" \
+  || { echo "FAIL: no index.html in outputDirectory — rename the entry HTML before release"; exit 1; }
+npx @wix/cli@latest release 2>&1   # parse `Site published on <url>`; NO `wix build` first
+```
+
+**`own`** — first settle imagery, then run the **project's own build**, point `outputDirectory` at the build output, then release:
+
+- **On `imagery === "ai-generated"`:** wait the Image Phase 2 handle (dispatched at the Wiring cell) with a hard **120 s timeout** from when wiring finishes; on timeout, note the timeout and proceed. (Entity images attach server-side, so they don't block the SPA *build* — the gate is mainly so the run doesn't proceed with entity images still attaching.) Confirm the seed-gate `write-decorative-json.mjs` overwrite already ran (decorative URLs are in `src/decorative-images.json`) **before** building.
+- **On `imagery === "themed-blocks"`:** no wait — `src/decorative-images.json` is the bootstrap `{}` placeholder; proceed to build.
+
+```bash
+npm run build 2>&1                 # the PROJECT's build (Vite/…), confirmed from package.json scripts — NEVER `wix build`
+# ensure wix.config.json.site.outputDirectory points at the build output (e.g. ./dist)
+npx @wix/cli@latest release 2>&1   # parse `Site published on <url>`
+```
+
+A `npm run build` failure is a **code bug** — fix it, do not retry (only the `release` step retries on transient errors).
+
+Either way: extract the published URL from `Site published on <url>`. Transient release errors (`ECONNRESET`, `STATE_MISMATCH`, `temporarily unavailable`, …) — retry serially up to 3× with `attempt * 5`s backoff (`references/shared/PRODUCTION_SHARP_EDGES.md`). Then the **Final Message** (`BUILD.md` § "Final Message" — the shared summary + `AGENTS.md` turn).