@wix/agent-skills 1.7.0 → 1.8.0

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).