@greatstore/cli 0.1.0 → 0.1.3

package/dist/gs-skill/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: greatstore
+description: Build AI-powered shopping experiences with GreatStore on a merchant's website and store. Use when installing the GreatStore chat widget on a site, generating AI content for custom UI with generateStructuredContent, adding chat entry points (sendMessage), letting the assistant act on the page via WebMCP page tools (document.modelContext.registerTool), authoring custom in-chat React components with the gs CLI, administering the store from the CLI (gs configure, gs connectors — origin allowlists, CSP hosts, MCP connectors), setting up web push re-engagement, or connecting AI agents to a store's MCP endpoints. Covers setup, schema design, caching behavior, component authoring, store administration, and ready-made recipes.
+---
+
+# Building with GreatStore
+
+GreatStore gives a store an AI shopping assistant on two surfaces: a hosted
+storefront at `https://<slug>.greatstore.ai/`, and an embedded chat widget on
+the merchant's own site, installed with one script tag:
+
+```html
+<script src="https://my-store.greatstore.ai/embed.js"></script>
+```
+
+Everything else a site can do with GreatStore is documented in the
+references below. Read the one that matches the task before writing code —
+each facet has non-obvious rules (caching, grounding, result shapes, design
+constraints) that the references spell out.
+
+## Index
+
+| Goal | Use | Read |
+|---|---|---|
+| Install the widget; control the panel; readiness, events, troubleshooting | `window.GreatStore` SDK | [references/embed-api.md](references/embed-api.md) |
+| AI-generated, catalog-grounded content rendered in **your own HTML/CSS** (highlights, comparisons, FAQs, gift guides) | `generateStructuredContent(schema, prompt)` | [references/structured-content.md](references/structured-content.md) |
+| Copy-paste on-page experiences | recipes built on the SDK | the [Recipes](#recipes) table below |
+| Contextual **conversation entry points** anywhere on the page | `sendMessage(text)`, `open()`, `?gs_chat=open` | [references/embed-api.md](references/embed-api.md) |
+| Feed the assistant **invisible page/component state** (current product, cart, selected variant) | `updateModelContext(text)`; component `onUpdateModelContext` | [references/embed-api.md](references/embed-api.md), [references/chat-components.md](references/chat-components.md) |
+| Let the assistant **act on the page** (cart, navigation, filters) | WebMCP: `document.modelContext.registerTool(...)` | [references/embed-api.md](references/embed-api.md) |
+| Custom **interactive UI inside the chat** (configurators, quizzes, size guides, booking forms) | remote components shipped with the `gs` CLI | [references/chat-components.md](references/chat-components.md) |
+| Expand a component's image in an **on-brand full-screen lightbox** | component `onShowLightbox({ src, originRect })` | [references/chat-components.md](references/chat-components.md) |
+| **Re-engage shoppers** with browser notifications | merchant-hosted `gs.js` + `enableNotifications()` | [references/push-notifications.md](references/push-notifications.md) |
+| Connect **AI agents** to the store (shopping tools over MCP, CLI docs for coding agents) | the store's MCP endpoints | [references/agents-and-mcp.md](references/agents-and-mcp.md) |
+| **Administer the store** — read config/connectors to ground decisions; self-serve origin allowlists and CSP hosts | `gs configure`, `gs connectors` | [references/store-admin.md](references/store-admin.md) |
+
+## Three things to know before any of it
+
+- **Every code sample in this skill is a reference implementation, not a
+  drop-in.** Samples are framework-free vanilla JS so they stay portable —
+  re-express the same logic in the conventions of the repo you're working
+  in (React, Vue, Shopify Liquid sections, Svelte, …); never retrofit the
+  sample as-is into a codebase with its own framework.
+- The page's domain **must be in the store's allowed domains**. If it isn't,
+  nothing works and the console shows
+  `[GreatStore] Chat is unavailable on <origin>…` — check this first whenever
+  the embed appears dead. You can verify and fix it yourself with the `gs`
+  CLI (read-merge-write on `extraOrigins` — see
+  [references/store-admin.md](references/store-admin.md)).
+- Every SDK call is safe immediately after the script tag — pre-mount calls
+  queue and replay in order, and the SDK pre-warms itself in the background.
+
+## Recipes
+
+Complete, framework-free implementations, one per file. Shared conventions:
+containers start `hidden` and reveal only on success (a failed generation
+changes nothing); generated strings render via `textContent`, never
+`innerHTML`; every recipe guards on `window.GreatStore`; prompts stay
+deterministic per page so repeat renders hit the cache.
+Inline real product/page data into prompts where the platform exposes it.
+
+| Recipe | What it builds | Use it for |
+|---|---|---|
+| [GreatStore launchers](recipes/launchers.md) | Horizontally scrollable AI-generated chips — engaging first-person questions about the current page; tap to ask the assistant. | Instant engagement on any page type — product, collection, blog, home. Simple yet effective; start here. |
+| [Ask-about-this entry points](recipes/ask-about-this.md) | One-line `sendMessage` buttons wired to existing page elements. | Size guides, shipping rows, out-of-stock badges — anywhere a shopper hesitates. |
+| [Product FAQ accordion](recipes/product-faq.md) | Grounded pre-purchase Q&A with an "ask us" handoff into chat. | Product pages; answering objections before they cost the sale. |
+| [Comparison table](recipes/comparison-table.md) | AI-picked representative products compared on category-relevant criteria. | Collection pages where shoppers weigh options. |
+| [Complete the look](recipes/complete-the-look.md) | Catalog-grounded cross-sell strip with a reason per pick. | Product pages; raising order value with genuine pairings. |
+| [Campaign hero](recipes/campaign-hero.md) | Seasonal homepage hero copy, cache-keyed to the ISO week. | Fresh homepage/campaign copy without manual rewrites. |
+| [Gift finder funnel](recipes/gift-finder-funnel.md) | Quiz teaser → chat handoff → page-tool navigation; the full funnel. | Gifting seasons, guided discovery, homepage engagement. |
+| [Page-action suite](recipes/page-action-suite.md) | WebMCP cart/page tools every conversation can use. | Any site where the assistant should act, not just advise. |
+| [Custom chat button](recipes/custom-chat-button.md) | Branded launcher synced via `ready` + `open`/`close` events. | Replacing the default launcher with the site's own UI. |
+
+## How the facets combine
+
+The strongest pattern is the **teaser → conversation → action** funnel:
+`generateStructuredContent` renders a grounded teaser in the merchant's
+design; each option's click handler calls `sendMessage` with the shopper's
+choice, dropping them into a conversation with momentum; WebMCP page tools
+and custom chat components let that conversation actually do things — add to
+cart, configure a product, book a slot — so it ends in a conversion, not a
+copy-paste. The [gift finder funnel](recipes/gift-finder-funnel.md)
+recipe is this funnel end to end.

package/dist/gs-skill/recipes/ask-about-this.md

@@ -0,0 +1,31 @@
+# "Ask about this" entry points (`sendMessage` only)
+
+> **Treat this code as a reference, not a drop-in.** Samples are
+> framework-free vanilla JS so they stay portable — re-express the same
+> logic in the conventions of the repo you're working in (React, Vue,
+> Shopify Liquid sections, Svelte, …) instead of retrofitting the sample
+> as-is.
+
+Zero-generation, instant, and often the biggest engagement win per line of
+code. Sprinkle context-aware buttons wherever a shopper hesitates:
+
+```js
+const gs = window.GreatStore;
+if (gs) {
+  sizeGuideLink.addEventListener("click", (e) => {
+    e.preventDefault();
+    gs.sendMessage(`How does the sizing run on "${productName}"? I usually wear a medium.`);
+  });
+
+  shippingRow.querySelector(".ask").addEventListener("click", () => {
+    gs.sendMessage(`What are the shipping options and times for "${productName}"?`);
+  });
+
+  outOfStockBadge?.addEventListener("click", () => {
+    gs.sendMessage(`"${productName}" looks out of stock — is there anything similar in stock?`);
+  });
+}
+```
+
+Write each message as something the shopper would plausibly say — it appears
+in the transcript as their message.

package/dist/gs-skill/recipes/campaign-hero.md

@@ -0,0 +1,43 @@
+# Campaign hero with deliberate variation
+
+> **Treat this code as a reference, not a drop-in.** Samples are
+> framework-free vanilla JS so they stay portable — re-express the same
+> logic in the conventions of the repo you're working in (React, Vue,
+> Shopify Liquid sections, Svelte, …) instead of retrofitting the sample
+> as-is.
+
+Cache-friendly variation: key the prompt to a low-cardinality period, not to
+time itself.
+
+```js
+// ISO week number → one generation per store per week, shared by everyone.
+const week = (d => {
+  const t = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+  t.setUTCDate(t.getUTCDate() + 4 - (t.getUTCDay() || 7));
+  return `${t.getUTCFullYear()}-W${Math.ceil((((t - Date.UTC(t.getUTCFullYear(), 0, 1)) / 864e5) + 1) / 7)}`;
+})(new Date());
+
+const data = await window.GreatStore.generateStructuredContent(
+  {
+    type: "object",
+    properties: {
+      headline: { type: "string", maxLength: 60 },
+      subline: { type: "string", maxLength: 120 },
+      featuredProductName: { type: "string", nullable: true },
+      ctaChatMessage: { type: "string", maxLength: 120 },
+    },
+    required: ["headline", "subline", "ctaChatMessage"],
+  },
+  `Variant ${week}. Write a homepage hero for this store: a headline and ` +
+    `subline spotlighting a real product or category that fits the current ` +
+    `season, plus ctaChatMessage — the first-person message a shopper ` +
+    `would send to start shopping for it.`
+);
+
+heroHeadline.textContent = data.headline;
+heroSubline.textContent = data.subline;
+heroCta.addEventListener("click", () =>
+  window.GreatStore.sendMessage(data.ctaChatMessage)
+);
+hero.hidden = false;
+```

package/dist/gs-skill/recipes/comparison-table.md

@@ -0,0 +1,80 @@
+# Collection-page comparison table
+
+> **Treat this code as a reference, not a drop-in.** Samples are
+> framework-free vanilla JS so they stay portable — re-express the same
+> logic in the conventions of the repo you're working in (React, Vue,
+> Shopify Liquid sections, Svelte, …) instead of retrofitting the sample
+> as-is.
+
+```html
+<section id="gs-compare" hidden>
+  <h3>Quick comparison</h3>
+  <table><thead id="gsc-head"></thead><tbody id="gsc-body"></tbody></table>
+</section>
+
+<script>
+  (async () => {
+    if (!window.GreatStore?.generateStructuredContent) return;
+    const collection = "winter jackets"; // ← your collection name
+    try {
+      const data = await window.GreatStore.generateStructuredContent(
+        {
+          type: "object",
+          properties: {
+            criteria: {
+              type: "array", minItems: 2, maxItems: 4,
+              items: { type: "string", maxLength: 25 },
+            },
+            rows: {
+              type: "array", minItems: 2, maxItems: 4,
+              items: {
+                type: "object",
+                properties: {
+                  productName: { type: "string" },
+                  bestFor: { type: "string", maxLength: 60 },
+                  values: {
+                    type: "array",
+                    items: { type: "string", maxLength: 60 },
+                  },
+                },
+                required: ["productName", "bestFor", "values"],
+              },
+            },
+          },
+          required: ["criteria", "rows"],
+        },
+        `The shopper is browsing the "${collection}" collection. Pick the ` +
+          `3-4 most representative products and compare them. Choose the ` +
+          `criteria a shopper actually decides on for this category. ` +
+          `"values" must align with "criteria" by index. Add a one-line ` +
+          `"bestFor" verdict per product. Only use real products and facts.`
+      );
+
+      const head = document.getElementById("gsc-head");
+      const hr = document.createElement("tr");
+      for (const h of ["Product", ...data.criteria, "Best for"]) {
+        const th = document.createElement("th");
+        th.textContent = h;
+        hr.append(th);
+      }
+      head.append(hr);
+
+      const body = document.getElementById("gsc-body");
+      for (const row of data.rows) {
+        const tr = document.createElement("tr");
+        const cells = [row.productName, ...(row.values ?? []), row.bestFor];
+        for (let i = 0; i < data.criteria.length + 2; i++) {
+          const td = document.createElement("td");
+          td.textContent = cells[i] ?? "—";
+          tr.append(td);
+        }
+        body.append(tr);
+      }
+      document.getElementById("gs-compare").hidden = false;
+    } catch {}
+  })();
+</script>
+```
+
+Note the index-aligned `values`/`criteria` trick and the `?? "—"` guard —
+grounding means a value the catalog can't support may be missing.

package/dist/gs-skill/recipes/complete-the-look.md

@@ -0,0 +1,59 @@
+# "Complete the look" cross-sell strip
+
+> **Treat this code as a reference, not a drop-in.** Samples are
+> framework-free vanilla JS so they stay portable — re-express the same
+> logic in the conventions of the repo you're working in (React, Vue,
+> Shopify Liquid sections, Svelte, …) instead of retrofitting the sample
+> as-is.
+
+```js
+const data = await window.GreatStore.generateStructuredContent(
+  {
+    type: "object",
+    properties: {
+      intro: { type: "string", maxLength: 90 },
+      picks: {
+        type: "array", minItems: 2, maxItems: 4,
+        items: {
+          type: "object",
+          properties: {
+            productName: { type: "string" },
+            reason: { type: "string", maxLength: 90 },
+            imageUrl: { type: "string", nullable: true },
+            productUrl: { type: "string", nullable: true },
+          },
+          required: ["productName", "reason"],
+        },
+      },
+    },
+    required: ["picks"],
+  },
+  `The shopper is viewing "${productName}". From the store's real catalog, ` +
+    `pick 2-4 products that genuinely pair with it and say why each one ` +
+    `completes the look or use-case. Include image and product URLs only ` +
+    `if known.`
+);
+
+for (const pick of data.picks) {
+  const card = document.createElement("a");
+  if (pick.productUrl) card.href = pick.productUrl;
+  if (pick.imageUrl) {
+    const img = document.createElement("img");
+    img.src = pick.imageUrl;
+    img.alt = pick.productName;
+    img.loading = "lazy";
+    card.append(img);
+  }
+  const name = document.createElement("strong");
+  name.textContent = pick.productName;
+  const why = document.createElement("p");
+  why.textContent = pick.reason;
+  card.append(name, why);
+  strip.append(card);
+}
+strip.hidden = false;
+```
+
+`imageUrl`/`productUrl` are `nullable` and optional in the render — the
+grounding contract means they're only present when the catalog actually has
+them. Never `require` URLs.

package/dist/gs-skill/recipes/custom-chat-button.md

@@ -0,0 +1,25 @@
+# Custom chat button synced to panel state
+
+> **Treat this code as a reference, not a drop-in.** Samples are
+> framework-free vanilla JS so they stay portable — re-express the same
+> logic in the conventions of the repo you're working in (React, Vue,
+> Shopify Liquid sections, Svelte, …) instead of retrofitting the sample
+> as-is.
+
+Replace the default launcher with your own UI using the lifecycle surface:
+
+```js
+const gs = window.GreatStore;
+const btn = document.getElementById("my-chat-button");
+
+gs.ready.then(() => { btn.hidden = false; });
+btn.addEventListener("click", () => gs.toggle());
+
+gs.on("open",  () => btn.setAttribute("aria-expanded", "true"));
+gs.on("close", () => btn.setAttribute("aria-expanded", "false"));
+```
+
+`ready` resolves even when `.then()` is attached after mount, so script
+ordering doesn't matter. The `open`/`close` events also fire for opens the
+SDK triggers itself (`sendMessage`, `?gs_chat=open`), keeping your button
+state honest.

package/dist/gs-skill/recipes/gift-finder-funnel.md

@@ -0,0 +1,97 @@
+# Gift finder funnel (teaser → conversation → action)
+
+> **Treat this code as a reference, not a drop-in.** Samples are
+> framework-free vanilla JS so they stay portable — re-express the same
+> logic in the conventions of the repo you're working in (React, Vue,
+> Shopify Liquid sections, Svelte, …) instead of retrofitting the sample
+> as-is.
+
+The flagship pattern: an AI-generated quiz card in your design, whose answers
+drop the shopper into a chat that can act on the page. Uses the
+`onGreatStoreReady` helper from the
+[embed API reference](../references/embed-api.md#availability) — define
+that once and it works for every use on the page.
+
+```html
+<section id="gift-finder" hidden>
+  <h3 id="gf-question"></h3>
+  <div id="gf-options"></div>
+</section>
+
+<script>
+  // Depending on where this script tag sits relative to the embed script
+  // tag, this inline script could run either before embed.js has executed
+  // at all, or after it's already mounted — checking `window.GreatStore`
+  // synchronously and bailing if it's not there yet would silently skip
+  // the whole funnel in the first case, and a bare
+  // `addEventListener("greatstore:ready", ...)` would silently miss the
+  // (one-shot, already-fired) event in the second.
+  // onGreatStoreReady (see the embed API reference) handles both.
+  onGreatStoreReady(async (gs) => {
+    // Tools the resulting conversation can use — discovered on its next
+    // turn automatically.
+    document.modelContext.registerTool({
+      name: "go_to_product",
+      description:
+        "Navigate the shopper to a product page on this site. Use when " +
+        "the shopper picks a product they want to see.",
+      inputSchema: {
+        type: "object",
+        properties: { url: { type: "string" } },
+        required: ["url"],
+      },
+      execute({ url }) {
+        const u = new URL(String(url), location.origin);
+        if (u.origin !== location.origin) throw new Error("Only same-site URLs allowed");
+        location.assign(u.href);
+        return { content: [{ type: "text", text: "Navigating." }] };
+      },
+    });
+
+    try {
+      const data = await gs.generateStructuredContent(
+        {
+          type: "object",
+          properties: {
+            question: { type: "string", maxLength: 80 },
+            options: {
+              type: "array",
+              minItems: 3,
+              maxItems: 4,
+              items: {
+                type: "object",
+                properties: {
+                  label: { type: "string", maxLength: 30 },
+                  chatMessage: { type: "string", maxLength: 140 },
+                },
+                required: ["label", "chatMessage"],
+              },
+            },
+          },
+          required: ["question", "options"],
+        },
+        "Create one engaging gift-finder opening question for this store, " +
+          "with 3-4 answer options that map to real areas of the catalog. " +
+          "For each option also write chatMessage: the message a shopper " +
+          "would send to a shopping assistant after picking it, phrased in " +
+          "first person (e.g. \"I'm shopping for my dad who loves hiking\")."
+      );
+
+      document.getElementById("gf-question").textContent = data.question;
+      const wrap = document.getElementById("gf-options");
+      for (const opt of data.options) {
+        const btn = document.createElement("button");
+        btn.type = "button";
+        btn.textContent = opt.label;
+        btn.addEventListener("click", () => gs.sendMessage(opt.chatMessage));
+        wrap.append(btn);
+      }
+      document.getElementById("gift-finder").hidden = false;
+    } catch {}
+  });
+</script>
+```
+
+Why it works: the teaser costs one cached generation per page, each
+click opens a conversation that already has direction, and `go_to_product`
+lets the conversation end on a product page instead of in a dead end.

package/dist/gs-skill/recipes/launchers.md

@@ -0,0 +1,109 @@
+# GreatStore launchers — AI question chips
+
+> **Treat this code as a reference, not a drop-in.** Samples are
+> framework-free vanilla JS so they stay portable — re-express the same
+> logic in the conventions of the repo you're working in (React, Vue,
+> Shopify Liquid sections, Svelte, …) instead of retrofitting the sample
+> as-is.
+
+A horizontally scrollable row of chips, each a highly engaging first-person
+question about the current page. Tapping a chip sends that question to the
+assistant — `generateStructuredContent` writes the questions, `sendMessage`
+fires them. Simple yet effective: it works on every page type, costs one
+cached generation per page, and every tap starts a conversation that already
+has a great opening line.
+
+```html
+<div id="gs-launchers" hidden></div>
+
+<style>
+  #gs-launchers {
+    display: flex;
+    gap: 0.5em;
+    overflow-x: auto;
+    -webkit-overflow-scrolling: touch;
+    scrollbar-width: none;
+    padding: 0.5em 1em;
+  }
+  #gs-launchers::-webkit-scrollbar { display: none; }
+  #gs-launchers button {
+    flex: 0 0 auto;
+    white-space: nowrap;
+    border: 1px solid #ddd;
+    border-radius: 999px;
+    padding: 0.5em 0.9em;
+    background: #fff;
+    cursor: pointer;
+  }
+</style>
+
+<script>
+  (async () => {
+    const gs = window.GreatStore;
+    if (!gs?.generateStructuredContent) return;
+    try {
+      const data = await gs.generateStructuredContent(
+        {
+          type: "object",
+          properties: {
+            launchers: {
+              type: "array", minItems: 4, maxItems: 6,
+              items: {
+                type: "object",
+                properties: {
+                  chip: { type: "string", maxLength: 32 },
+                  question: { type: "string", maxLength: 140 },
+                },
+                required: ["chip", "question"],
+              },
+            },
+          },
+          required: ["launchers"],
+        },
+        `The shopper is on the page "${document.title}". Write 4-6 launcher ` +
+          `chips for a shopping assistant. For each, "question" is a highly ` +
+          `engaging first-person question this shopper would genuinely want ` +
+          `answered on this page — specific to its product, category, or ` +
+          `content, never generic — and "chip" is a 2-4 word teaser of it. ` +
+          `Vary the angles: fit and use, comparisons, gifting, care, what's ` +
+          `popular.`
+      );
+
+      const row = document.getElementById("gs-launchers");
+      for (const { chip, question } of data.launchers) {
+        const btn = document.createElement("button");
+        btn.type = "button";
+        btn.textContent = chip;
+        btn.title = question;
+        btn.addEventListener("click", () => gs.sendMessage(question));
+        row.append(btn);
+      }
+      row.hidden = false;
+    } catch {}
+  })();
+</script>
+```
+
+Why it works:
+
+- **The chip is the teaser, the question is the payload.** A 2-4 word chip
+  scans instantly; the full first-person question lands in the transcript
+  reading like something the shopper typed, and gives the assistant a
+  well-formed prompt. The `title` attribute previews the full question on
+  hover.
+- **Per-page for free.** The page URL is part of the generation context and
+  the cache key, so one site-wide snippet yields different chips on every
+  page — each served from cache on repeat renders.
+- **Placement is the lever.** Under the product title, above the grid on
+  collections, at the end of a blog post — wherever a shopper pauses to
+  wonder, the chips name the question for them.
+
+Tips:
+
+- Inline the product or collection name into the prompt when the platform
+  exposes it — it beats relying on `document.title`.
+- Restyle the chips to the site's design system; the CSS above is just the
+  scroll mechanics (flex row, `overflow-x: auto`, hidden scrollbars,
+  `white-space: nowrap`).
+- Resist adding more than ~6 chips — a launcher row is an invitation, not a
+  sitemap.

package/dist/gs-skill/recipes/page-action-suite.md

@@ -0,0 +1,90 @@
+# Page-action suite (WebMCP)
+
+> **Treat this code as a reference, not a drop-in.** Samples are
+> framework-free vanilla JS so they stay portable — re-express the same
+> logic in the conventions of the repo you're working in (React, Vue,
+> Shopify Liquid sections, Svelte, …) instead of retrofitting the sample
+> as-is.
+
+Give every conversation on the site real capabilities. Register once in a
+shared snippet, after the SDK is ready (which guarantees
+`document.modelContext` exists) — using the `onGreatStoreReady` helper from
+the [embed API reference](../references/embed-api.md#availability), which
+handles both load orderings (embed script not run yet vs. already mounted)
+that a plain `window.GreatStore?.ready.then()` or a bare
+`addEventListener("greatstore:ready", ...)` each only cover one side of:
+
+```js
+onGreatStoreReady(() => {
+  const text = (value) => ({
+    content: [{ type: "text", text: JSON.stringify(value) }],
+  });
+
+  document.modelContext.registerTool({
+    name: "get_cart",
+    description:
+      "Read the shopper's current cart on this site: items, quantities, " +
+      "and totals. Use before answering any cart question.",
+    inputSchema: { type: "object", properties: {} },
+    async execute() {
+      return text(await (await fetch("/cart.js")).json());
+    },
+  });
+
+  document.modelContext.registerTool({
+    name: "add_to_cart",
+    description:
+      "Add a product variant to the cart on this site. Use when the " +
+      "shopper asks to add or buy something. Confirm the variant with " +
+      "the shopper first if ambiguous.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        variantId: { type: "string" },
+        quantity: { type: "integer", minimum: 1, maximum: 10 },
+      },
+      required: ["variantId"],
+    },
+    async execute({ variantId, quantity }) {
+      if (!variantId) throw new Error("variantId is required");
+      const res = await fetch("/cart/add.js", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ id: variantId, quantity: quantity ?? 1 }),
+      });
+      if (!res.ok) throw new Error(`Could not add to cart (${res.status})`);
+      document.dispatchEvent(new CustomEvent("cart:refresh"));
+      return text(await res.json());
+    },
+  });
+
+  document.modelContext.registerTool({
+    name: "get_current_page",
+    description:
+      "Read what page the shopper is currently on, including structured " +
+      "product data when on a product page.",
+    inputSchema: { type: "object", properties: {} },
+    execute() {
+      return text({
+        url: location.href,
+        title: document.title,
+        productJson: document.querySelector("#product-json")?.textContent ?? null,
+      });
+    },
+  });
+});
+```
+
+Principles at work: throw on failure (the assistant explains and recovers),
+return fresh state after mutations (the assistant confirms accurately), cap
+quantities in the schema, and notify your own UI (`cart:refresh`) so the
+page reflects what the AI did.
+
+For a product-page-only tool, register with an `AbortSignal` and abort on
+SPA navigation:
+
+```js
+const ac = new AbortController();
+document.modelContext.registerTool(reviewsTool, { signal: ac.signal });
+router.onLeave("/products/:handle", () => ac.abort());
+```