@wix/agent-skills 1.7.0 → 1.9.0

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

@@ -25,7 +25,7 @@ body: [
 ]
 ```
 
-Before the first call, ensure the `curl` tool schema is loaded (the orchestrator's session auth covers this — see `<SKILL_ROOT>/references/commands/AUTHENTICATION.md`) so `body` is sent as a real JSON array (not a stringified blob). Use your runtime's AUTHENTICATION.md recovery ladder if you need to (re-)load it.
+Send `body` as a real JSON array (not a stringified blob). Auth uses the CLI-minted site-scoped token and the standard headers — see `<SKILL_ROOT>/references/shared/AUTHENTICATION.md`.
 
 Extract `data[0].imageURL` from the response. This is a short-lived URL — **import to Wix Media immediately** in the same task queue.
 
@@ -44,7 +44,7 @@ Extract `data[0].imageURL` from the response. This is a short-lived URL — **im
 
 ### Allowed Dimensions (safe defaults)
 
-Runware enforces a fixed set per model. Start with these — all three were validated end-to-end this session with `google:4@2`:
+Runware enforces a fixed set per model. Start with these:
 
 | Aspect | Size | Use for |
 |--------|------|---------|
@@ -58,7 +58,26 @@ If a 400 response lists supported dimensions, use one from that list — do not
 
 Do NOT send `steps` or `CFGScale` — both are rejected with `unsupportedParameter` and cause a 400. These fields are valid for other Runware models but must be omitted for `google:4@2`.
 
-## Required: minimize round-trips per image phase
+## Preferred: run the whole phase through `generate-images.mjs`
+
+Generation + Wix Media import is **embarrassingly parallel** (N independent `generate → import` chains, no cross-image dependency) and **recipe-free** (no entity write-shapes), so it is best run by a deterministic script rather than by hand. `<SKILL_ROOT>/scripts/generate-images.mjs` does exactly this: it fires every image as a **concurrent single-task request in one process** (`Promise.all`), then imports each result to Wix Media — all in parallel — and returns a `key → {url, fileId}` map. Because each task is its **own** request (not N tasks in one body), it sidesteps the `google:4@2` N≥3-in-one-request 504 entirely, and because the parallelism lives in code it cannot degrade into the sequential-turns anti-pattern below.
+
+```bash
+echo '{
+  "siteId": "<siteId>",
+  "model": "google:4@2",
+  "images": [
+    {"key": "hero",  "positivePrompt": "<prompt>", "width": 1376, "height": 768},
+    {"key": "about", "positivePrompt": "<prompt>", "width": 1200, "height": 896}
+  ]
+}' | WIX_TOKEN="$TOKEN" node <SKILL_ROOT>/scripts/generate-images.mjs
+```
+
+`key` is a **slot name** for Phase 1 (`hero`, `about`) or an **entityId** for Phase 2. The returned `slots` map (key→url) pipes straight into `write-decorative-json.mjs` (Phase 1); the `map` (key→{url,fileId}) feeds the entity PATCH/PUT/publish recipe (Phase 2). Pass the **already-minted** site token via `WIX_TOKEN` (mint-once — `AUTHENTICATION.md`); the script mints its own only as a fallback. Per-image failures are isolated (`status: "partial"`), and `x-wix-request-id` is captured per call into `results[]` for trace analysis.
+
+The manual `curl` shapes below remain the **reference for the request bodies** the script builds, and the **fallback** when the script can't be used. The "one concurrent batch" rule still applies if you ever hand-drive a phase.
+
+## Required (manual fallback): minimize round-trips per image phase
 
 The image agent's `image-phase-1-decorative` and `image-phase-2-entity` scopes each generate multiple images. **Do not emit N one-task calls in sequential turns** — sequential dispatch across many turns adds ~30–40 s of inter-message overhead. The correct shape depends on the model:
 
@@ -85,37 +104,19 @@ Assistant message (single turn, multiple tool calls):
   REST: POST https://www.wixapis.com/runwareschemaless/v1/request
 ```
 
-All three fire in parallel (runtime dispatches concurrent siblings concurrently). No 504, no sequential wait. The important constraint is *one concurrent batch* — splitting them across turns loses the parallelism and degenerates into the anti-pattern below.
-
-### ANTI-PATTERN (slow, regardless of model)
-
-Sequential 1-task calls across multiple turns:
-```
-Assistant msg 1:  curl  body: [ task1 ]
-(runtime waits)
-Assistant msg 2:  curl  body: [ task2 ]
-(runtime waits)
-Assistant msg 3:  curl  body: [ task3 ]
-```
-Each turn adds inter-message overhead. Whether you're using the batched pattern or parallel siblings, **all the image-generation tool calls MUST be in one concurrent batch**.
+All three fire in parallel (runtime dispatches concurrent siblings concurrently). No 504, no sequential wait. The important constraint is *one concurrent batch* — splitting them across turns loses the parallelism: sequential 1-task calls across multiple turns each add inter-message overhead.
 
 ### Procedure to enforce batching
 
-The following procedure prevents the observed serialization anti-pattern. Follow these steps in order:
+Whether you batch one request or fire parallel siblings, **all calls in each stage MUST be in one concurrent batch**. Follow these steps in order:
 
 1. **Write all prompts first.** In your text response, list every image you will generate with its positivePrompt, dimensions, and a UUID. Do not make any tool calls yet.
-2. **Compose the full body array** as a fenced JSON block in your text. Verify the task count matches the entity count.
-3. **One tool call.** Make exactly one `curl` call with that complete body array.
-4. **Parallel imports.** After the generate response arrives, emit all N `POST /site-media/v1/files/import` calls as **concurrent sibling calls in one concurrent batch**.
-5. **Parallel PATCHes.** After all imports resolve, emit all N PATCH calls as **concurrent sibling calls in one concurrent batch**.
-
-**Three concurrent batches total (one per stage).** If you find yourself making more, stop and check whether you're serializing.
-
-### Media import and entity PATCH — parallelize with siblings
-
-Generation is one concurrent batch — whether that's one batched call or N parallel siblings. The follow-up steps (`POST /site-media/v1/files/import` per image, and entity PATCH per product/post/item) are per-entity; those can parallelize via concurrent siblings — emit all N import calls in one concurrent batch, then all N PATCH calls in one concurrent batch. See the skill's `references/PLAN.md` § "Batching discipline" for why sibling batching beats sequential dispatch.
+2. **Compose the generation call(s).** For `bfl:5@1` / `runware:400@1`, one batched call with the full body array; for `google:4@2`, N parallel 1-task sibling calls. Verify the task count matches the entity count.
+3. **Generate.** Fire that generation as one concurrent batch.
+4. **Parallel imports.** After the generate response arrives, emit all N `POST /site-media/v1/files/import` calls as concurrent sibling calls in one concurrent batch.
+5. **Parallel PATCHes.** After all imports resolve, emit all N PATCH calls as concurrent sibling calls in one concurrent batch.
 
-**Pattern for an image phase:** one batched generation call → N parallel imports (sibling calls in one message) → N parallel PATCHes (sibling calls in one message).
+**Three concurrent batches total (one per stage).** If you find yourself making more, stop and check whether you're serializing. See the skill's `references/PLAN.md` § "Batching discipline" for why sibling batching beats sequential dispatch.
 
 ## Step 2: Import to Wix Media
 

package/skills/wix-headless/references/shared/IMPLEMENTER.md

@@ -1,6 +1,6 @@
 # Shared Implementer — Common Behavior for Every Vertical Subagent
 
-This file is **extended by every per-vertical `INSTRUCTIONS.md`** (stores, ecom, cms, blog, forms, gift-cards). Per-vertical instruction files are thin — they declare scopes and reference paths. Everything else lives here.
+This file is **extended by every per-vertical `INSTRUCTIONS.md`** (stores, ecom, cms, blog, forms, gift-cards, bookings). Per-vertical instruction files are thin — they declare scopes and reference paths. Everything else lives here.
 
 ## Self-loading
 
@@ -12,13 +12,15 @@ Read **only** the files your scope needs. The reading set varies by scope:
 | `components`, `components-css`, `pages`, `pages-*` | this file, `RETURN_CONTRACT.md`, `STYLING.md` | — |
 | Image scopes | (read `references/images/INSTRUCTIONS.md` § Self-Loading) | — |
 
-Then read the specific reference(s) for your declared scope (see your vertical's `INSTRUCTIONS.md` scope table). Do NOT read references for scopes other than the one named in your prompt — wastes context and blurs ownership.
+Then read the specific reference(s) for your declared scope(s) (see your vertical's `INSTRUCTIONS.md` scope table). Do NOT read references for scopes **not** named in your prompt — wastes context and blurs ownership.
 
 ## Phase routing
 
-Your prompt includes a line `Scope: <name>`. Map to exactly one reference set per your vertical's `INSTRUCTIONS.md` scope table. If the `Scope:` line is missing, stop and ask the parent — do not guess.
+Your prompt includes a line naming your scope(s). Map **each** scope to its reference set per your vertical's `INSTRUCTIONS.md` scope table. If the scope line is missing, stop and ask the parent — do not guess.
 
-Standard scope names (see architecture-proposal §3):
+**Merged dispatch (the common case — one agent owns components + pages for a vertical).** Your prompt may list **several** scopes — e.g. `Scopes (write in this order): components, pages-products, pages-categories`. This is a single "build" agent for one vertical: read the **union** of those scopes' references and write them in the order given — **islands/components FIRST, then the pages/routes that mount them.** Writing the page before its island leaves a dangling import; the within-agent order is exactly why these were merged into one dispatch (it removes the cross-agent Components→Pages barrier). You still own only the files those scopes declare; do not touch another vertical's files or a shared shell unless your scope list explicitly includes a shell-patching `pages` scope.
+
+Standard scope names:
 - `seed` — Seed phase (REST data setup, no frontend code)
 - `components` — Components phase (reusable React/Astro islands, SDK wiring)
 - `pages` — Pages phase (route files with visual design + data queries, single scope per vertical)
@@ -30,30 +32,30 @@ Scopes that call Wix APIs (`seed`, image phases) receive `siteId` in the prompt.
 
 If your scope is `components` or `pages`, you should NOT make REST calls — those scopes are frontend-only. If you find yourself needing a site API call, it's a scope violation — return `status: "partial"` with an error note, do not proceed.
 
-## Do NOT read `.wix/site.json`
+## Don't depend on mutable shared state (one scoped exception: `.wix/seeded.json`)
 
-Every input you need is inlined in your prompt. The orchestrator is the sole reader/writer of `.wix/site.json`; the file is a slim metadata snapshot for run.json composition + resume detection, not a coordination channel.
+Every input you need is either inlined in your prompt or — for seeded entity IDs — in **`.wix/seeded.json`**, the one shared file you are allowed to read. The orchestrator holds run state in scratch, not on disk — it is **not** a coordination channel you can read. `.wix/seeded.json` is the one exception: a producer→consumer handoff written **once** at the seed gate, read-only thereafter. Read **only your own `<vertical>` slice**; never write it.
 
-**Phase-specific inputs (all inlined in your prompt):**
+**Phase-specific inputs:**
 
-| Scope | What the prompt inlines |
+| Scope | Where its inputs come from |
 |---|---|
-| `seed` | `brand`, `intent.<pack>`, `siteId`, recipe path(s). Do NOT re-derive these. |
-| `components` | `brand`, the full `designTokens` JSON (same shape Designer returned). CSS variables are also on disk at `.wix/design-tokens.css` for the build. |
-| `pages` / `pages-*` | `brand`, the `designTokens` JSON, and the relevant `seeded.<vertical>` slice (products, posts, collections IDs). Page data wiring uses live SDK queries; the `seeded` data in your prompt is for path resolution + demo content authoring. |
+| `seed` | All **inlined**: `brand`, `intent.<pack>`, `siteId`, recipe path(s). Do NOT re-derive these. |
+| `components` | **Inlined**: `brand`. **Read from disk**: the design tokens (the DESIGN.md vocabulary — `colors`/`typography`/`spacing`/`rounded`/`containers`) from `.wix/design-tokens.css` (gate-verified present; also the CSS variables the build consumes). Components do not need seeded IDs. |
+| `pages` / `pages-*` | **Inlined:** `brand`. **Read from disk:** the design tokens (`.wix/design-tokens.css`, DESIGN.md vocabulary); your `seeded.<vertical>` slice from `.wix/seeded.json` (products, posts, collections IDs). Page data wiring uses live SDK queries; the `seeded` data is for path resolution + demo content authoring. |
 
-If a required input is missing from your prompt (e.g. the orchestrator forgot to inline `seeded.stores` when dispatching you as `pages-products`), fail fast — return `status: "failed"` with `errors: [{ code: "PROMPT_INCOMPLETE", missing: "seeded.stores.products" }]`. Do NOT re-fetch from `.wix/site.json` or via curl — the data gap means an upstream phase didn't complete, and re-querying would mask the real bug.
+If a required **inlined** input is missing from your prompt, or your **`.wix/seeded.json` slice** is absent (e.g. you are dispatched as `pages-products` but `.wix/seeded.json` has no `seeded.stores`), fail fast — return `status: "failed"` with `errors: [{ code: "SEEDED_JSON_SLICE_MISSING", missing: "seeded.stores.products" }]` (or `PROMPT_INCOMPLETE` for an inlined gap). Do NOT re-fetch via curl — the gap means an upstream phase didn't complete, and re-querying would mask the real bug.
 
-## Seeders return data; orchestrator aggregates
+## Seeders return data; orchestrator aggregates → `.wix/seeded.json`
 
-Agents with `Scope: seed` return their seeded entities in the `data` block of the standard return (see `RETURN_CONTRACT.md`). The orchestrator collects every seeder return into its session scratch and inlines the relevant slice into the prompts of Phase 3 Components / Phase 4 Pages / Image Phase 2 subagents. You do NOT write `site.json` yourself and you do NOT write `.wix/seed-returns/<pack>.json` — your JSON return is the contract.
+Agents with `Scope: seed` return their seeded entities in the `data` block of the standard return (see `RETURN_CONTRACT.md`). The orchestrator collects every seeder return into its session scratch and writes the aggregated map **once** to `.wix/seeded.json` at the seed gate; per-vertical Page / wiring agents then read their own slice from that file (no inlined slice). (The single Image Phase 2 dispatch keeps its slice inlined.) You do NOT write `.wix/seeded.json` (the orchestrator is its sole writer), and you do NOT write `.wix/seed-returns/<pack>.json` — your JSON return is the contract.
 
 ## Writing page files
 
 Pages-phase agents write route files (`.astro`) with:
 
-1. **Visual design via design tokens and Tailwind.** Reference tokens as `var(--color-primary)` in `<style>` blocks or `bg-[--color-primary]` as Tailwind arbitrary values. Use canonical component templates (`agents/<vertical>/templates/*.astro`) as starting points — adapt, don't invent.
-2. **Data queries against seeded data.** The seeded entity IDs / slugs are inlined in your prompt (`seeded.<vertical>`). Pages query the Wix SDK at request time (`await productsV3.queryProducts(...)`) — that's the production-correct pattern. Use the inlined `seeded` data for path generation (e.g. `getStaticPaths` slugs) and for authoring demo content where needed; do NOT `import` `.wix/site.json` from page files.
+1. **Visual design via design tokens and Tailwind.** Reference tokens as `var(--color-accent)` in `<style>` blocks or `bg-[--color-accent]` as Tailwind arbitrary values. Use canonical component templates (`agents/<vertical>/templates/*.astro`) as starting points — adapt, don't invent.
+2. **Data queries against seeded data.** Read the seeded entity IDs / slugs from your `seeded.<vertical>` slice in `.wix/seeded.json` (with the `Read` tool — not by `import`). Pages query the Wix SDK at request time (`await productsV3.queryProducts(...)`) — that's the production-correct pattern. Use the `seeded` data for path generation (e.g. `getStaticPaths` slugs) and for authoring demo content where needed; do NOT `import` `.wix/seeded.json` from page files — it sits outside the bundler root and reading it at author-time (not bundling it) keeps it out of `dist/`.
 3. **Imports from shared components.** Pages import components your Components-phase agent wrote (`src/components/*.tsx`, `.astro`).
 4. **Imports from skill shared utilities.** `from "../utils/wix-image"` and `from "../utils/analytics"` — these are skill-shipped (copied into the project by `seed-utilities.sh` during Setup); do NOT import them from anywhere else.
 
@@ -117,30 +119,88 @@ The full styling contract (tokens-as-utilities default, when global semantic cla
 ## Style conventions
 
 - **camelCase for identifiers, kebab-case for filenames, PascalCase for components.** Example: `ProductCard.astro`, `queryBlogPosts` function, `cart-updated` event.
-- **No inline styles beyond design-token CSS variables.** `style={{ color: "red" }}` is forbidden; `style={{ color: "var(--color-primary)" }}` is fine.
-- **Tailwind utilities are local to the component.** Don't invent cross-cutting class names. If you need section padding, write `<section class="py-4xl">` — not `<section class="hero-section">`. If you need a flex column with gap, write `class="flex flex-col gap-md"` — not `class="product-card-body"`. If two components need the same look, extract a shared primitive component, not a shared class name. The retained list of legitimate global semantic classes is short and lives in designer `INSTRUCTIONS.md` § "Always-required global semantic classes" — anything outside that list does not belong in `global.css`.
-- **Tailwind v4 `@reference` is mandatory in any scoped CSS that uses `@apply`.** Tailwind v4 isolates `@apply` per file — utilities defined in the main entry CSS (where `@theme` lives) are NOT visible to `components-*.css` unless that file prepends `@reference "./global.css";` on line 1. Without it, `wix cli build` fails with `Cannot apply unknown utility class 'gap-sm' …`. **`tsc` and `astro check` both pass clean** — only the bundler catches the regression. If your scope writes a `components-<vertical>.css` that uses `@apply` with theme tokens (e.g., `@apply gap-sm font-display text-sm`), the file MUST start with:
+- **No inline styles beyond design-token CSS variables.** `style={{ color: "red" }}` is forbidden; `style={{ color: "var(--color-accent)" }}` is fine.
+- **Tailwind v4 `@reference` is mandatory in any scoped CSS that uses `@apply`.** Tailwind v4 isolates `@apply` per file — utilities defined in the main entry CSS (where `@theme` lives) are NOT visible to `components-*.css` unless that file prepends `@reference "./global.css";` on line 1. If your scope writes a `components-<vertical>.css` that uses `@apply` with theme tokens (e.g., `@apply gap-sm font-display text-sm`), the file MUST start with:
   ```css
   @reference "./global.css";
   ```
-  Without it, the build breaks at release time even though `tsc` and `astro check` pass clean — only the bundler catches it.
+  Without it, the build breaks at release time with `Cannot apply unknown utility class 'gap-sm' …` even though `tsc` and `astro check` pass clean — only the bundler catches it.
 - **Fail loud, never silently.** If data is missing, a required field is absent, or an REST call returns an unexpected shape, return `status: "failed"` with details. Do not invent placeholders or swallow errors.
 
 ## Return contract
 
-Every agent ends its message with a fenced JSON block per `RETURN_CONTRACT.md`. The JSON MUST be the last content in the message — no trailing prose. Timing fields are NOT included (the orchestrator captures timing via runtime `duration_ms`).
+Every agent ends its message with a fenced JSON block per `RETURN_CONTRACT.md` (the universal envelope: skeleton, status semantics, no-trailing-prose rule). The JSON MUST be the last content in the message — no trailing prose. Timing fields are NOT included (the orchestrator captures timing via runtime `duration_ms`).
+
+The `data` shapes for the scopes this file owns — `components` and `pages`/`pages-*` — are below. (Seed `data` shapes live in your per-vertical `INSTRUCTIONS.md` § Seed return.)
+
+**`components` scope** (`phase: "<pack>-components"`):
+
+```json
+{
+  "status": "complete",
+  "phase": "stores-components",
+  "scope": "components",
+  "summary": "Wrote React islands + utils; wired analytics; contract classes referenced: 7",
+  "data": {
+    "islands": ["ProductPurchase.tsx", "CartView.tsx", "AddToCartButton.tsx", "CartBadge.tsx"],
+    "utils": ["wix-image.ts", "analytics.ts"],
+    "astroComponents": ["SeoTags.astro"]
+  },
+  "files": [
+    "src/utils/wix-image.ts",
+    "src/utils/analytics.ts",
+    "src/components/SeoTags.astro",
+    "src/components/AddToCartButton.tsx",
+    "src/components/CartBadge.tsx",
+    "src/components/ProductPurchase.tsx",
+    "src/components/CartView.tsx"
+  ]
+}
+```
+
+**`pages` / `pages-*` scope** (`phase: "<pack>-pages[-<group>]"`):
+
+```json
+{
+  "status": "complete",
+  "phase": "stores-pages-products",
+  "scope": "pages-products",
+  "data": {
+    "pagesWired": 2,
+    "wixMetadataExported": true,
+    "seoTagsMounted": true,
+    "analyticsEvents": ["AddProductImpression", "ClickProduct", "ViewContent"]
+  },
+  "files": [
+    "src/pages/products/index.astro",
+    "src/pages/products/[slug].astro",
+    "src/components/ProductCard.astro"
+  ]
+}
+```
 
 ## Common failure modes
 
 | Wrong | Right |
 |---|---|
-| Reading references for scopes other than the declared `Scope:` | Read only your scope's references |
-| Issuing REST calls from a `components` or `pages` scope | Components/Pages are frontend-only; use `seeded` data inlined in your prompt |
-| Re-querying when `seeded.<vertical>` is missing from your prompt | Fail fast with `PROMPT_INCOMPLETE` — the orchestrator forgot to inline it (upstream bug) |
-| Writing `.wix/site.json` from a seeder | Seeders return data; orchestrator writes site.json |
+| Reading references for scopes **not** listed in your prompt | Read only the references for your declared scope(s) — the union when it's a merged build dispatch |
+| Writing a page/route before the island it mounts (merged dispatch) | Write islands/components FIRST, then the pages — in the prompt's scope order |
+| Issuing REST calls from a `components` or `pages` scope | Components/Pages are frontend-only; read `seeded` data from your `.wix/seeded.json` slice (pages only) — never curl |
+| Re-querying when your `seeded.<vertical>` slice is missing from `.wix/seeded.json` | Fail fast with `SEEDED_JSON_SLICE_MISSING` — an upstream phase didn't complete (do NOT re-query) |
+| Depending on mutable shared state the orchestrator holds in scratch | Every input is inlined; the one shared file you may read is your `.wix/seeded.json` slice (read-only) |
 | Inventing class names for layout/spacing/typography (`.productCard`, `.heroSection`) | Tailwind utilities derived from `@theme` tokens (`class="flex flex-col gap-md"`, `class="py-4xl"`). For one-off page decoration, co-located `<style>` block. |
 | Removing a marker after inserting at it | Marker stays; other verticals may contribute after you |
 | Trailing narrative prose after the return JSON | JSON block must be the last content |
 | Fabricated timestamps in the return JSON | Do not include timing fields — orchestrator captures them |
-| Inline `style="color: red"` | Use design tokens: `style="color: var(--color-primary)"` |
-| Creating a new cross-cutting class name | Extract a shared primitive component instead |
+| Inline `style="color: red"` | Use design tokens: `style="color: var(--color-accent)"` |
+| Creating a new cross-cutting class name | Extract a shared primitive component instead |
+
+### Astro/React build-blockers — check before returning `complete`
+
+| Failure | How to detect | Fix |
+|---------|---------------|-----|
+| HTML-style comments in `.astro` frontmatter | `grep '<!--' *.astro` frontmatter | Use `//` or `/* */` — frontmatter is TypeScript. Surfaces at build as `Legacy HTML single-line comments`. |
+| Missing `wixMetadata` on `/products/[slug]` | Check exports | Add the metadata export — required for Wix platform indexing |
+| `import { products }` instead of `productsV3` | `grep 'from "@wix/stores"'` import line | V1 silently returns 0 on V3 catalogs |
+| Missing `variantId` in cart operations | Check `catalogReference.options` | Always include — single-variant products have one |
+| React island using default Tailwind color class | `grep 'bg-blue-\|bg-green-\|text-red-\|bg-gray-' *.tsx` | Use brand `@theme` utilities (`bg-bark`, `text-cream`) or contract class names |

package/skills/wix-headless/references/shared/PRODUCTION_SHARP_EDGES.md

@@ -13,7 +13,7 @@ Use this reference when a Wix Headless run touches production release, SEO-contr
 - `temporary system error`
 - `try again shortly`
 
-The bundled `scripts/release.sh` retries these known transient release failures. Do not retry build failures; TypeScript, Astro, missing import, and missing module failures are code issues that must be fixed before another release attempt.
+The conductor's release step (the shared release tail, `BUILD.md` § "Shared release tail" — `BUILD-astro.md` § "Build & Release" for astro, `BUILD-own-build.md` § "Release" for no-build frameworks) retries these known transient release failures serially — up to 3× with `attempt * 5`s backoff. Do not retry build failures; TypeScript, Astro, missing import, and missing module failures are code issues that must be fixed before another release attempt.
 
 For batch releases across many projects, prefer releasing failed sites one by one after the current deployment state settles. Parallel release is useful for throughput, but retry serially when Wix reports state-machine errors.
 
@@ -63,7 +63,7 @@ PUT https://www.wixapis.com/promote-seo-robots-server/v2/llms
 }
 ```
 
-Do not use `default: true` for custom `llms.txt`; in observed runs it caused `/llms.txt` to return `404`.
+Do not use `default: true` for custom `llms.txt` — setting `default: true` returns `404` for custom `llms.txt` content.
 
 Wix may mutate `llms.txt` content by: