@wix/agent-skills 1.13.0 → 1.15.0

package/skills/wix-headless/references/custom/ecom/WIRING.md

@@ -1,67 +0,0 @@
----
-name: custom-ecom-wiring
-description: "Integration-mode wiring subagent for the ecom capability. Wires add-to-cart + checkout into a brought-in static site — @wix/ecom currentCart + a redirect to Wix-hosted checkout, client-side via @wix/sdk from CDN. No SSR cart-persistence (deferred); cart lives in the visitor session + a checkout redirect."
----
-
-# Ecom wiring (integration mode)
-
-You wire the **ecom capability** (add-to-cart + checkout) into a brought-in static site (`frontend = "custom"`). Pairs with the **stores** guide (which renders products). Client-side vanilla JS, `@wix/sdk` from CDN, no build. Read `INSTRUCTIONS.md` § "The technical spine" + § "Wiring discipline" first.
-
-> **Scope.** Beta does **add-to-cart + redirect-to-Wix-hosted-checkout** via the visitor session. A persistent on-page cart UI across reloads needs the server runtime (`@wix/astro`) — **deferred**. Checkout itself happens on Wix's hosted page, so payment/fulfillment need no client work.
-
-## Inputs
-
-- **`appId`** — `OAuthStrategy` `clientId`.
-- Binding-map / design controls: the "Add to cart" / "Buy" buttons (with the product/variant id available, e.g. from the stores wiring's `data-product-id`).
-
-## Add to cart + checkout
-
-```html
-<script type="module">
-  import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk@1";
-  import { currentCart } from "https://esm.sh/@wix/ecom@1";
-  import { redirects } from "https://esm.sh/@wix/redirects@1";
-
-  const wix = createClient({ modules: { currentCart, redirects }, auth: OAuthStrategy({ clientId: "REPLACE_WITH_APP_ID" }) });
-
-  // Add to cart — buttons carry data-product-id (set by the stores wiring)
-  document.querySelectorAll("[data-add-to-cart]").forEach((btn) => {
-    btn.addEventListener("click", async () => {
-      btn.disabled = true;
-      try {
-        await wix.currentCart.addToCurrentCart({
-          lineItems: [{
-            catalogReference: {
-              appId: "215238eb-22a5-4c36-9e7b-e7c08025e04e", // Wix Stores catalog appId (constant)
-              catalogItemId: btn.dataset.productId,
-            },
-            quantity: 1,
-          }],
-        });
-        document.querySelector("[data-cart-badge]")?.replaceChildren(document.createTextNode("•"));
-      } catch (err) { console.error("[wix-ecom] add-to-cart failed:", err); }
-      finally { btn.disabled = false; }
-    });
-  });
-
-  // Checkout — create a checkout from the current cart, then redirect to Wix-hosted checkout
-  document.querySelector("[data-checkout]")?.addEventListener("click", async () => {
-    try {
-      const { checkoutId } = await wix.currentCart.createCheckoutFromCurrentCart({ channelType: "WEB" });
-      const { redirectSession } = await wix.redirects.createRedirectSession({
-        ecomCheckout: { checkoutId },
-        callbacks: { postFlowUrl: location.href },
-      });
-      if (redirectSession?.fullUrl) location.assign(redirectSession.fullUrl);
-    } catch (err) { console.error("[wix-ecom] checkout failed:", err); }
-  });
-</script>
-```
-
-- **`currentCart`** APIs only — never the `cart` namespace that needs a cart ID.
-- The Wix Stores catalog `appId` (`215238eb-…`) is a platform constant (the catalog provider), distinct from the site's OAuth `appId`/`clientId`.
-- Cart badge is a minimal indicator; a full cart-contents page is out of Beta scope (no SSR persistence).
-
-## Discipline & return
-
-Additive; inline the site `appId`; guard calls. Return per `shared/RETURN_CONTRACT.md`: files edited, controls wired (add-to-cart count, checkout button), and note that persistent cart UI is deferred.

package/skills/wix-headless/references/custom/forms/WIRING.md

@@ -1,101 +0,0 @@
----
-name: custom-forms-wiring
-description: "Integration-mode wiring subagent for the forms capability. Connects a brought-in static site to Wix Forms — wires an existing <form> to submit via @wix/forms, OR injects a new connected form (RSVP / lead / contact) styled from the design's CSS tokens. Client-side @wix/sdk + OAuthStrategy visitor session, loaded from CDN. The universal connection floor for integration mode."
----
-
-# Forms wiring (integration mode)
-
-You wire the **forms capability** into a brought-in static site for `wix-headless` integration mode (`frontend = "custom"`). Forms is the **universal connection floor** — when a design has no dynamic content, a domain-appropriate form (RSVP, lead, contact) is the connection that makes it live.
-
-You write **client-side, vanilla JS** — no React, no build step. `@wix/sdk` + `@wix/forms` load from a CDN; the HTML *is* the deployable. Read `INSTRUCTIONS.md` § "The technical spine" and § "Wiring discipline" before starting.
-
-## Inputs (inlined by the orchestrator)
-
-- **`appId`** — from `wix.config.json`; the `OAuthStrategy` `clientId`.
-- **`formId`** — the Wix Form created at Seed time (Seed creates the form definition from the augmentation spec's `fields`, with `postSubmissionTriggers.upsertContact` so submissions create CRM contacts). Never hardcode or invent a form ID — if it's missing, fail loudly.
-- **`fields`** — each `{ name, label, type, required, options?, target }`. The **`target`** is the Wix field key the submission map uses (from the created form's schema). If only `name` is known, the orchestrator resolves `target` from the seeded form schema before dispatch.
-- **The augmentation spec** (`injectAt`, `styleFrom`) and/or a binding-map entry (an existing `<form>` to wire).
-- **`tokens`** — the design's resolved CSS custom properties for styling.
-
-## Two cases
-
-### A. Augment — inject a new connected form (the static-design path)
-
-The design has no form (e.g. a wedding invitation). Inject one at `augmentation.injectAt`.
-
-1. **Build the `<form>` markup** from `fields`, styled with the design's tokens. Use the site's existing CSS custom properties (`var(--…)`) and font/spacing variables verbatim so the form reads as designed-in. Reuse the page's section/heading rhythm (match an existing `section`'s padding, an existing heading's font). Each input's `name` attribute = the field's `target`.
-2. **Insert** at `injectAt` (e.g. `position: "before"` the `section.closing`). Additive only — do not alter surrounding markup or the global `<style>`. Put the form's own CSS in a single scoped `<style>` block that references the design tokens.
-3. **Wire submission** with the script below.
-
-### B. Wire — connect an existing `<form>` (the form-shaped-design path)
-
-The design already has a `<form>` (binding-map entry, `entity: "forms.submit"`). Map its inputs' `name`/`id` to the form's field `target`s, intercept submit, and post via the SDK. Keep the existing markup and styling; only add the submit handler script.
-
-## The submission script (both cases)
-
-Append one `<script type="module">` (before `</body>`). Inline the literal `appId` and `formId`.
-
-```html
-<script type="module">
-  import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk@1";
-  import { submissions } from "https://esm.sh/@wix/forms@1";
-
-  const wix = createClient({
-    modules: { submissions },
-    auth: OAuthStrategy({ clientId: "REPLACE_WITH_APP_ID" }), // appId from wix.config.json
-  });
-
-  const FORM_ID = "REPLACE_WITH_FORM_ID";
-  const form = document.querySelector("#wix-rsvp-form"); // the injected/targeted form
-
-  form?.addEventListener("submit", async (e) => {
-    e.preventDefault();
-    const btn = form.querySelector("[type=submit]");
-    if (btn) btn.disabled = true;
-
-    // keys MUST be the Wix field `target`s (input name="<target>")
-    const data = Object.fromEntries(new FormData(form).entries());
-
-    try {
-      const result = await wix.submissions.createSubmission({
-        formId: FORM_ID,
-        submissions: data,
-      });
-      if (result.status === "PENDING" || result.status === "CONFIRMED") {
-        form.querySelector("[data-wix-success]")?.removeAttribute("hidden");
-        form.reset();
-      } else {
-        throw new Error("unexpected submission status: " + result.status);
-      }
-    } catch (err) {
-      console.error("[wix-forms] submission failed:", err);
-      form.querySelector("[data-wix-error]")?.removeAttribute("hidden");
-      // surface field-level violations if present
-      const violations = err?.details?.validationError?.fieldViolations ?? [];
-      for (const v of violations) {
-        for (const fe of (v?.data?.errors ?? [])) {
-          const el = form.querySelector(`[name="${fe.errorPath}"]`);
-          if (el) el.setAttribute("aria-invalid", "true");
-        }
-      }
-    } finally {
-      if (btn) btn.disabled = false;
-    }
-  });
-</script>
-```
-
-- Include a hidden success node (`<p data-wix-success hidden>…</p>`) and error node (`<p data-wix-error hidden>…</p>`) in the form markup, styled with the tokens.
-- The submission `data` keys are the field **`target`s** — set each input's `name` to its `target`.
-- Pin the CDN versions (`@1`) in the import URLs; do not float `@latest` in shipped HTML.
-
-## Discipline (from `INSTRUCTIONS.md`)
-
-- **Additive only** — never restructure the design or edit the global stylesheet; the injected form is self-contained.
-- **Style from tokens** — use `var(--…)` from the site's `:root`; never introduce a foreign palette/font.
-- **Guard the call** — try/catch; on failure show the error node, keep the form usable.
-- **Inline `appId` + `formId` literally** — no env vars, no build-time substitution.
-
-## Return
-
-Per `shared/RETURN_CONTRACT.md`: report the file(s) edited, the inject anchor used, the `formId` wired, and the form's `target`→input mapping. If `formId` was missing, return `status: "failed"` with `errors: [{ code: "FORM_NOT_SEEDED" }]` — do not invent one.

package/skills/wix-headless/references/custom/stores/WIRING.md

@@ -1,80 +0,0 @@
----
-name: custom-stores-wiring
-description: "Integration-mode wiring subagent for the stores capability. Connects a brought-in static site's product markup to Wix Stores — replaces hard-coded product cards with live productsV3 queries rendered into the existing DOM template, client-side via @wix/sdk + @wix/stores from CDN. Cart-add + checkout via the ecom guide."
----
-
-# Stores wiring (integration mode)
-
-You wire the **stores capability** into a brought-in static site (`frontend = "custom"`). The design already shows products as **hard-coded sample cards**; you replace the sample data with live `@wix/stores` queries, rendering into the **existing card markup** the design provides. Client-side vanilla JS, `@wix/sdk` from CDN, no build. Read `INSTRUCTIONS.md` § "The technical spine" + § "Wiring discipline" first.
-
-## Inputs (inlined by the orchestrator)
-
-- **`appId`** — `OAuthStrategy` `clientId` (from `wix.config.json`).
-- **Binding-map entries** for `stores.products` regions: `{ file, anchor, shape, template, bindings, sampleCount }`.
-- **Seeded `productIds` / slugs** (from Seed) — so the wired query shows the seeded catalog.
-- **`tokens`** — design CSS custom properties (only needed if you add an empty-state node).
-
-## The read-and-render pattern (this is the core; blog/cms reuse it)
-
-For each binding-map list region:
-
-1. **Keep the first sample child as the template.** The region (`anchor`) holds `sampleCount` near-identical children matching `template` (e.g. `article.product-card`). Clone that node per result; remove the remaining static samples. Do **not** restyle — the existing classes carry the design.
-2. **Query live data** and **bind fields** by the binding-map `bindings` map (DOM selector relative to template → entity field path).
-3. **Render on load**, guard with try/catch; on error leave the original samples visible.
-
-```html
-<script type="module">
-  import { createClient, OAuthStrategy } from "https://esm.sh/@wix/sdk@1";
-  import { productsV3 } from "https://esm.sh/@wix/stores@1";   // V3 — never the V1 `products`
-
-  const wix = createClient({
-    modules: { productsV3 },
-    auth: OAuthStrategy({ clientId: "REPLACE_WITH_APP_ID" }),
-  });
-
-  const grid = document.querySelector("section.product-grid");      // binding-map anchor
-  const tpl  = grid?.querySelector("article.product-card");          // binding-map template
-  if (grid && tpl) {
-    try {
-      const { items } = await wix.productsV3
-        .queryProducts({ fields: ["CURRENCY"] })
-        .limit(12)
-        .find();
-
-      const proto = tpl.cloneNode(true);
-      grid.replaceChildren(...items.map((p) => {
-        const card = proto.cloneNode(true);
-        // bindings: selector@attr → field path   (e.g. "img.thumb@src" → media.mainMedia.image.url)
-        const img = card.querySelector("img.thumb"); if (img) img.src = p.media?.mainMedia?.image?.url ?? "";
-        const name = card.querySelector("h3.name");  if (name) name.textContent = p.name ?? "";
-        const price = card.querySelector("span.price"); if (price) price.textContent = p.priceData?.formatted?.price ?? "";
-        // description is RICH TEXT — bind plainDescription, never the HTML `description` (see note below)
-        const desc = card.querySelector(".description"); if (desc) desc.textContent = p.plainDescription ?? (p.description ?? "").replace(/<[^>]*>/g, "");
-        // link to a detail page if the design has one (see "Detail" below)
-        const link = card.querySelector("a"); if (link && p.slug) link.href = `/product/${p.slug}`;
-        return card;
-      }));
-    } catch (err) {
-      console.error("[wix-stores] product query failed:", err);   // leave samples visible
-    }
-  }
-</script>
-```
-
-- **Use `productsV3`**, never V1 `products` (V1 silently returns 0 on V3 catalogs).
-- **Description is rich text — bind `p.plainDescription`, never `p.description`.** `description` is HTML/ricos; binding it into `textContent` (or a framework `{…}` expression) renders literal `<p>…</p>` tags. Use `plainDescription` (a plain string), falling back to `description.replace(/<[^>]*>/g, "")` if absent.
-- **(create × own only — N/A for brought-in static sites.)** When you *own* the markup (the SPA is generated, not brought in), size every image: Wix media URLs are full-resolution, so an `<img>` with no sizing overflows its card onto the text. Put each image in a fixed `aspect-ratio`/`height` slot with `width:100%; height:100%; object-fit:cover`. A brought-in static site is already sized by its own design — skip this.
-- Apply the binding-map's actual selectors/field paths — the snippet's `img.thumb`/`h3.name`/`span.price`/`.description` are illustrative.
-- **Categories:** if a region is `categoriesV3`, query `wix.categoriesV3.queryCategories().eq("visible", true).find()` (the builder rejects empty filters — always chain at least one predicate).
-
-## Detail (`shape: "detail"`)
-
-If the design has a product-detail page keyed by slug, read the slug from the URL (`location.pathname`), `queryProducts().eq("slug", slug).find()`, and bind the single result into the detail markup. If there is no detail page, link cards to the catalog or omit links.
-
-## Buy / cart
-
-Add-to-cart and checkout are the **ecom** capability — see `references/custom/ecom/WIRING.md`. If a card has a "Buy"/"Add" control and ecom is in the capability set, the ecom guide wires it; otherwise leave it inert or link to the product.
-
-## Discipline & return
-
-Additive only; render into the existing template; inline `appId`; guard every call (samples are the error fallback). Return per `shared/RETURN_CONTRACT.md`: files edited, anchors wired, query used, seeded IDs surfaced. Missing seeded catalog → note it; the empty query still wires (Seed should have populated it).

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

@@ -1,59 +0,0 @@
----
-name: ecom-implementer
-description: "Implements vertical-agnostic ecommerce — cart page, checkout redirect, thank-you page, cart badge. Scopes: components, components-css, pages. Extends references/shared/IMPLEMENTER.md."
----
-
-# Ecom Implementer
-
-Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, prompt-inlined inputs (read only your `.wix/seeded.json` slice), return contract, style conventions, and common failure modes.
-
-## Scope routing
-
-| Scope | Phase | Reference |
-|-------|-------|-----------|
-| `components` | Components (CartView, CartBadge — TSX only, **no CSS**) — `src/utils/discounts.ts` is pre-copied by the orchestrator | `../astro/ecom/CART_WIRING.md` |
-| ~~`components-css`~~ | **Do not dispatch.** `src/styles/components-ecom.css` is copied from `<SKILL_ROOT>/references/astro/templates/ecom/components-ecom.css` by the orchestrator's pre-Step-4.5 batch (see BUILD-astro.md § Step 4.5). The template uses direct `var(--token)` CSS, so it works against any designer-published vocabulary without per-run rewrites. `COMPONENTS_CSS.md` documents that CSS for reference — there is no `components-css` subagent to dispatch. | — |
-| `pages` | Pages (cart.astro, thank-you.astro, Navigation CartBadge mount) | `../astro/ecom/CART_PAGES.md` |
-
-> **Why `components` is TSX-only.** The scoped CSS (`src/styles/components-ecom.css`) has no runtime coupling to the TSX components — it's referenced only by class name at build time — so it ships pre-copied from the template by the orchestrator (see the `components-css` scope-routing row above) rather than being written by an agent. Mirrors the stores split. See `../astro/ecom/COMPONENTS_CSS.md` § "What this scope owns".
-
-Note: `ecom` is never triggered independently — it's co-loaded by verticals that require it (`stores` today; `bookings`, `events` in the future). No `seed` scope — ecom has no data of its own; it works off line items from whichever catalog app is installed.
-
-## Files this vertical creates / contributes
-
-See `<SKILL_ROOT>/references/verticals/ecom.md` frontmatter.
-
-## Templates
-
-Components (`components` scope — TSX only):
-- `<SKILL_ROOT>/references/astro/templates/ecom/CartView.tsx`
-- `<SKILL_ROOT>/references/astro/templates/ecom/CartBadge.tsx`
-
-Components CSS (pre-copied by the orchestrator — no agent writes it):
-- `<SKILL_ROOT>/references/astro/templates/ecom/components-ecom.css`
-
-### Pre-copied by the orchestrator (do NOT write this yourself)
-
-- `src/utils/discounts.ts` — pre-copied from `<SKILL_ROOT>/references/astro/templates/ecom/discounts.ts` BEFORE your `components` scope dispatches. Wix Ecom Discount Rules fetch + per-product match utility; consumers are stores `pages-products` / `pages-home-and-nav` (ProductCard ribbon + product-detail offer callout). Uses `auth.elevate()` from `@wix/essentials` — `discountRules.queryDiscountRules` requires `ECOM.DISCOUNT_RULES_READ`, a visitor client returns empty silently without elevation.
-
-  Just import from this path; never rewrite the file. Regenerating it has shipped a no-op stub that satisfied the manifest but caused the discount ribbon to silently never render. The pre-copy makes that regression structurally impossible.
-
-## CSS ownership — ecom pack
-
-Ecom-specific component CSS lives in `src/styles/components-ecom.css` (pre-copied from the template by the orchestrator before Step 4.5 — see the `components-css` scope-routing row above; your `components` scope imports it, never writes it), NOT in the designer's `global.css`. The classes the pack owns:
-
-- `.cart-summary` — the bordered/sticky summary panel on `/cart`. Compound bordered card; sticky on desktop.
-- `.cart-total` — the row inside the summary that anchors the total amount with a top rule and display-serif typography.
-- `.cart-empty` — the centered empty-state on `/cart` when the cart is empty. Includes the inline override of `.checkout-btn` so the "Browse Products" CTA isn't a full-width brick.
-- `.checkout-btn` — primary checkout button with `:disabled` and `:hover:not(:disabled)` states. Composes from `.btn-primary` (which IS designer-owned in `global.css`).
-- `.cart-item-*` — row, image, name, qty controls — all live here. Most are utility-only; the few that need scoped rules (e.g. line-item separator borders) belong here, not in `global.css`.
-
-The designer's `global.css` declares only tokens, the `.btn` family, decorative slots, the editorial-rule, and the site-shell shells. If `global.css` ships with a partial rule for any class above, that's a designer bug — flag it in your return JSON's `errors` array (`{code: "GLOBAL_CSS_LEAK", class: "<name>"}`) and override with the complete rule in `components-ecom.css`.
-
-See `references/shared/STYLING.md` § "Component-specific CSS is owned by the component, not the designer" for the boundary rule.
-
-## Cross-vertical event contract
-
-`cart-updated` CustomEvent on `window`:
-- **Dispatchers:** `AddToCartButton` (stores), `CartView` (ecom)
-- **Listener:** `CartBadge` (ecom)

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

@@ -1,43 +0,0 @@
----
-name: forms-implementer
-description: "Implements contact, lead, and signup forms via @wix/forms. Scopes: seed, components, pages. Extends references/shared/IMPLEMENTER.md."
----
-
-# Forms Implementer
-
-Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, prompt-inlined inputs (read only your `.wix/seeded.json` slice), return contract, style conventions, and common failure modes.
-
-## Scope routing
-
-| Scope | Phase | Reference |
-|-------|-------|-----------|
-| `seed` | Seed (Forms app install + form creation + postSubmissionTriggers PATCH) | `../astro/forms/CONTACT_FORM.md` (§ Form Setup) |
-| `components` | Components (ContactForm.tsx React island) | `../astro/forms/CONTACT_FORM.md` (§ React island) |
-| `pages` | Pages (contact.astro wire with formId from seeded data) | `../astro/forms/CONTACT_FORM.md` (§ Page wiring) |
-
-## Files this vertical creates / contributes
-
-Each scope's files are enumerated in `../astro/forms/CONTACT_FORM.md` (§ Form Setup, § React island, § Page wiring).
-
-## Form purpose variants
-
-The `seed` scope adapts field selection based on business purpose from the functional plan:
-
-| Purpose | Fields | Layout |
-|---------|--------|--------|
-| Waitlist / newsletter | EMAIL + SUBMIT | Single column |
-| Lead capture | FIRST_NAME + EMAIL + SUBMIT | Single column |
-| Contact (full) | FIRST_NAME + LAST_NAME + EMAIL + PHONE + MESSAGE + SUBMIT | First+last side-by-side, rest stacked |
-| Registration | FIRST_NAME + LAST_NAME + EMAIL + custom | Single column |
-
-## Forms-specific failure modes
-
-| Wrong | Right |
-|---|---|
-| Skip `postSubmissionTriggers` PATCH after form creation | Always PATCH — the POST silently drops triggers; without them, submissions are silently lost (no CRM Contact created) |
-| Include triggers in POST body and assume it worked | POST drops `postSubmissionTriggers`; always follow up with PATCH |
-| Fall back to hardcoded fields on `UNSUPPORTED_FORM_NAMESPACE` | Wait 10s and retry up to 3 times — namespace propagation delay after Forms app install |
-| Skip `auth.elevate` when listing forms | `listForms` requires elevated permissions |
-| Submit forms from server-side code | Form submission must be client-side (React island with `client:load`) |
-| Detect textarea by `componentType === "TEXT_AREA"` | Check `identifier === "TEXT_AREA"` or `target === "message"` |
-| Hardcode form field IDs or form ID | Use `forms.listForms("wix.form_app.form")` with `auth.elevate` for runtime discovery |

package/skills/wix-headless/references/gift-cards/INSTRUCTIONS.md

@@ -1,51 +0,0 @@
----
-name: gift-cards-implementer
-description: "Implements the passive Wix Gift Cards vertical — runtime probe util, GiftCardPurchase island, /gift-cards page, and conditional nav/home contributions. Scopes: components, pages. Extends references/shared/IMPLEMENTER.md."
----
-
-# Gift Cards Implementer
-
-Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, prompt-inlined inputs (read only your `.wix/seeded.json` slice), return contract, style conventions, and common failure modes.
-
-## Scope routing
-
-| Scope | Phase | Reference |
-|-------|-------|-----------|
-| `components` | Components (probe util, React island, scoped CSS) | `../astro/gift-cards/COMPONENTS.md` |
-| `pages` | Pages (gift-cards landing + Navigation/index patches) | `../astro/gift-cards/PAGES.md` |
-
-This pack has **no `seed` scope** — the dashboard's eGift Card template is the source of truth and we never seed denominations from code.
-
-## Files this vertical creates / contributes
-
-See the § "Templates" list below for the files each scope produces (and the nav/home contributions it patches).
-
-## Pre-return file-existence assertion (pages scope)
-
-Before returning `status: "complete"` from the `pages` scope, verify every file the scope produces (the page templates in § "Templates" below, plus the patched `Navigation.astro` / `index.astro`) exists on disk. If a declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]` rather than claiming success.
-
-## Templates
-
-Canonical templates live at `<SKILL_ROOT>/references/astro/templates/gift-cards/`. Your `components` and `pages` scopes read these and adapt them — don't invent markup or logic.
-
-Components (`components` scope):
-- `<SKILL_ROOT>/references/astro/templates/gift-cards/gift-cards.ts`
-- `<SKILL_ROOT>/references/astro/templates/gift-cards/GiftCardPurchase.tsx`
-- `<SKILL_ROOT>/references/astro/templates/gift-cards/components-gift-cards.css`
-
-Pages (`pages` scope):
-- `<SKILL_ROOT>/references/astro/templates/gift-cards/gift-cards.astro`
-- `<SKILL_ROOT>/references/astro/templates/gift-cards/_nav-snippet.astro` — exact contribution to insert at `<!-- nav:links -->` in `Navigation.astro`
-- `<SKILL_ROOT>/references/astro/templates/gift-cards/_home-teaser-snippet.astro` — exact contribution to insert at `<!-- home:gift-cards -->` in `index.astro`
-
-## Gift-cards-specific failure modes
-
-| Wrong | Right |
-|---|---|
-| Hardcode denominations in code | Always read `presetVariants` from the live API (`getGiftCardProduct()`) |
-| Call `createGiftCardProduct` or any seeding op | Never seed; the dashboard owns the template |
-| Wrap calls in `auth.elevate(...)` | The probe is visitor-scoped already; elevation breaks it |
-| Forget to import `getGiftCardProduct` when patching `Navigation.astro` or `index.astro` | When inserting at a marker, also add the corresponding import + frontmatter call to that file |
-| Drop or rename the marker comment after inserting | Preserve the marker line — future re-runs and other verticals depend on it |
-| Render the page when probe returns `null` | Redirect to `/` (`Astro.redirect("/", 302)`) so users following stale links never see a broken page |
-| Skip memoization of `getGiftCardProduct()` | Module-level cache promise — Navigation, home, and page render in the same request and must coalesce to one fetch |