@greatstore/cli 0.0.26 → 0.0.28

package/dist/cli.js

@@ -92,7 +92,7 @@ async function captureLoopbackToken(options) {
   const open = options.openBrowser ?? ((url) => openInBrowser(url, options.browserCmdEnv));
   const server = http.createServer();
   try {
-    await new Promise((resolve6) => server.listen(0, "127.0.0.1", resolve6));
+    await new Promise((resolve8) => server.listen(0, "127.0.0.1", resolve8));
     const address = server.address();
     const redirectUri = `http://127.0.0.1:${address.port}${CALLBACK_PATH}`;
     const authUrl = `${options.navBaseUrl}/connect_oauth_done?redirect_uri=${encodeURIComponent(redirectUri)}&state=${encodeURIComponent(state)}`;
@@ -104,7 +104,7 @@ async function captureLoopbackToken(options) {
   }
 }
 function waitForCallback(server, expectedState, timeoutMs) {
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve8, reject) => {
     let settled = false;
     const settle = (fn) => {
       if (settled) return;
@@ -143,7 +143,7 @@ function waitForCallback(server, expectedState, timeoutMs) {
       res.writeHead(200, { "content-type": "text/html" });
       res.end(SUCCESS_HTML);
       clearTimeout(timer);
-      settle(() => resolve6({ token }));
+      settle(() => resolve8({ token }));
     });
   });
 }
@@ -303,6 +303,15 @@ function findGsrc(cwd) {
     dir = parent;
   }
 }
+function resolveAdminStore(args) {
+  const explicit = flagString(args.flags, "store")?.trim();
+  if (explicit) return explicit;
+  const fromRc = findGsrc(process.cwd());
+  if (fromRc) return fromRc;
+  throw new StoreResolutionError(
+    "No store selected. Pass --store <slug>, or run from a project with a .gsrc."
+  );
+}
 function apiBaseFor(slug, env = process.env) {
   const override = env.GS_API_BASE?.trim();
   if (override) return stripTrailingSlash(override);
@@ -395,7 +404,7 @@ var KNOWN_ERROR_MESSAGES = {
   // commitDraft() / promote() / unpublish() — StoreComponentFailure
   not_found: { message: "Component not found on the server." },
   concurrent_write: {
-    message: "Another change landed before this one. Run `gs pull` and try again."
+    message: "Another change landed before this one. Run `gs apps pull` and try again."
   },
   name_mismatch: {
     message: "Manifest `name` does not match the component folder name.",
@@ -524,193 +533,614 @@ function whoamiCommand() {
   return expired ? 1 : 0;
 }
 
-// src/commands/list.ts
-async function listCommand(args) {
-  const slug = requireProjectStore();
-  const url = `${apiBaseFor(slug)}/api/builder/components`;
-  const data = await request(url);
-  if (flagBool(args.flags, "json")) {
-    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
-    return;
-  }
-  if (data.components.length === 0) {
-    process.stdout.write(`(no components in ${slug})
-`);
-    return;
+// src/commands/skill.ts
+import * as fs3 from "fs";
+import * as os2 from "os";
+import * as path3 from "path";
+
+// src/template.ts
+import { readdirSync, readFileSync as readFileSync3 } from "fs";
+import { fileURLToPath } from "url";
+var cache = null;
+function loadTemplate() {
+  if (cache) return cache;
+  cache = true ? JSON.parse('{"component/component.tsx":"import React from \\"react\\";\\n\\n// Add your tool args (matching manifest.json#inputSchema.properties)\\n// alongside the GreatStore-injected lifecycle props. See AGENTS.md for\\n// what each lifecycle prop does.\\ninterface Props {\\n  onSendMessage: (text: string) => void;\\n  onCallTool: (name: string, args: Record<string, unknown>) => void;\\n  onClose: () => void;\\n}\\n\\n// See AGENTS.md for the design rules (em-based sizing, brand CSS\\n// variables), the lifecycle props, and how to write an async,\\n// backend-backed component.\\nexport default function __GS_PASCAL__(_props: Props): React.ReactElement {\\n  return (\\n    <div\\n      style={{\\n        padding: \\"1em\\",\\n        border: \\"1px solid var(--color-border-default)\\",\\n        borderRadius: \\"var(--radius-lg)\\",\\n        background: \\"var(--color-surface)\\",\\n        color: \\"var(--color-foreground)\\",\\n        fontFamily: \\"var(--font-sans)\\",\\n      }}\\n    >\\n      <strong>__GS_NAME__</strong> \u2014 hello from your component!\\n    </div>\\n  );\\n}\\n","component/manifest.json":"{\\n  \\"name\\": \\"__GS_NAME__\\",\\n  \\"displayName\\": \\"__GS_DISPLAY_NAME__\\",\\n  \\"description\\": \\"Renders the __GS_NAME__ widget.\\",\\n  \\"displayMode\\": \\"inline\\",\\n  \\"inputSchema\\": {\\n    \\"type\\": \\"object\\",\\n    \\"properties\\": {}\\n  }\\n}\\n","root/.gitignore":"node_modules/\\ncomponents/*/bundle.js\\ncomponents/*/.gssync.json\\n*.tsbuildinfo\\n.DS_Store\\n","root/.gsrc":"{\\n  \\"store\\": \\"__GS_STORE__\\"\\n}\\n","root/AGENTS.md":"# AGENTS.md\\n\\nGuidance for AI coding agents working on the components in this project.\\n`CLAUDE.md` and `GEMINI.md` are symlinks to this file.\\n\\nThese components render inside arbitrary publisher websites (the embed\\nwidget mounts on a host page) as well as the GreatStore storefront. You\\ncontrol neither the host page\'s base font size nor its color scheme, and\\nthe store owner controls the look from GreatStore theme settings. The\\nrules below keep components portable across both.\\n\\n## Design requirements\\n\\n### Never use `rem` for fonts and sizing \u2014 always use `em`\\n\\n`rem` resolves against the host page\'s root font size, which is\\narbitrary and outside our control. A host that sets `html { font-size:\\n8px }` (or 200%) will shrink or blow up every `rem`-based dimension.\\n`em` resolves against the component\'s own font size, so it stays\\nself-consistent wherever the component is mounted.\\n\\nUse `em` for font sizes, padding, margins, gaps, widths, heights,\\nand any other length. Borders may stay in `px` (hairlines should not\\nscale with text).\\n\\n```tsx\\n// Bad \u2014 breaks on hosts with a non-default root font size\\n<div style={{ padding: \\"1rem\\", fontSize: \\"0.875rem\\" }} />\\n\\n// Good\\n<div style={{ padding: \\"1em\\", fontSize: \\"0.875em\\" }} />\\n```\\n\\n### Don\'t hardcode colors, fonts, or corner radius \u2014 use GreatStore brand variables\\n\\nThe store owner themes the assistant from GreatStore settings. Hardcoded\\nvalues ignore that and make the component clash with the rest of the\\nstore. Read from the CSS variables GreatStore injects on the surface\\ninstead, so the component restyles itself when the theme changes.\\n\\nAvailable variables:\\n\\n| Purpose | Variable |\\n| --- | --- |\\n| Surface background | `--color-surface` |\\n| Secondary surface | `--color-surface-secondary` |\\n| Accent surface | `--color-surface-accent` |\\n| Hover surface | `--color-surface-hover` |\\n| Foreground text | `--color-foreground` |\\n| Secondary text | `--color-foreground-secondary` |\\n| Muted text | `--color-foreground-muted` |\\n| Accent text | `--color-foreground-accent` |\\n| Border | `--color-border-default` |\\n| Focus border | `--color-border-focus` |\\n| Primary / brand | `--color-primary` |\\n| Text on primary | `--color-primary-foreground` |\\n| Primary hover | `--color-primary-hover` |\\n| Primary muted | `--color-primary-muted` |\\n| Text on primary muted | `--color-primary-muted-foreground` |\\n| Primary tint | `--color-primary-tint` |\\n| Link | `--color-link` |\\n| Font family | `--font-sans` |\\n| Corner radius (scale) | `--radius-xs` \u2026 `--radius-4xl`, `--radius-pill` |\\n\\n```tsx\\n// Bad \u2014 hardcoded, ignores the store\'s theme\\n<button style={{ background: \\"#4f46e5\\", borderRadius: 8, fontFamily: \\"Inter\\" }} />\\n\\n// Good\\n<button\\n  style={{\\n    background: \\"var(--color-primary)\\",\\n    color: \\"var(--color-primary-foreground)\\",\\n    borderRadius: \\"var(--radius-lg)\\",\\n    fontFamily: \\"var(--font-sans)\\",\\n  }}\\n/>\\n```\\n\\nProvide a sensible fallback only when a value might be absent, e.g.\\n`var(--color-primary, currentColor)`.\\n\\n## Component props\\n\\nEach component receives its tool args (the fields you declare in\\n`manifest.json#inputSchema.properties`) plus these GreatStore-injected\\nlifecycle props, which are always present:\\n\\n| Prop | What it does |\\n| --- | --- |\\n| `onSendMessage(text)` | Send text into the chat as if the shopper typed it. |\\n| `onCallTool(name, args)` | Chain into another remote-component tool by name. |\\n| `onClose()` | Dismiss the host slot. Over-input clears the overlay, fullscreen reverts the pane, inline is a no-op. |\\n\\n## Async components (backend-backed, render-blocking data)\\n\\nIf a component must load data from a backend/API before it can render\\ncorrectly, make it async \u2014 don\'t render an empty shell and fetch in a\\n`useEffect`. Set `\\"async\\": true` in `manifest.json` and export an async\\ndefault. GreatStore waits for your promise (showing a normal loading\\nstate, so you don\'t render your own placeholder), then renders what it\\nresolves to. Components that render purely from their props stay\\nsynchronous.\\n\\nA thrown error is a **retry signal**: the in-store AI sees it and\\nusually re-calls the tool. So only throw when a *different* call could\\nhelp:\\n\\n1. `await` the backend call, then return the finished JSX.\\n2. Validate the AI-passed props first and throw on bad input \u2014 the AI\\n   can fix the args and retry. (Don\'t validate the API\'s *output* and\\n   throw: the AI can\'t fix the backend, it\'ll just loop.)\\n3. Broadcast a backend failure ONLY when retrying differently could\\n   succeed, and say what to change (e.g. empty search \u2192 \\"try a broader\\n   keyword\\"). For idempotent failures (500, timeout, missing record)\\n   re-running the same call changes nothing \u2014 render a graceful fallback\\n   instead of throwing.\\n\\n```tsx\\nexport default async function Example(props: Props) {\\n  if (!props.query?.trim()) throw new Error(\\"missing required prop: query\\");\\n  const res = await fetch(`/api/search?q=${encodeURIComponent(props.query)}`);\\n  if (res.ok) {\\n    const { results } = await res.json();\\n    if (results.length === 0)\\n      throw new Error(`no results for \\"${props.query}\\" \u2014 try a broader keyword`);\\n    return <ul>{/* render results */}</ul>;\\n  }\\n  return <p>Couldn\'t load results right now.</p>; // idempotent: don\'t throw\\n}\\n```\\n","root/README.md":"# GreatStore components\\n\\nCustom React components published to your GreatStore tenant. Each\\ncomponent lives in its own folder under `components/`.\\n\\n```\\nnpm install\\ngs apps init <component_name>      # add a new component\\ngs apps build                      # builds every components/<name>/bundle.js\\ngs apps push                       # uploads every changed component as a draft\\ngs apps publish <component_name>   # promote a specific component to live\\n```\\n\\n- `gs apps push` (no args) hashes each component and only uploads the ones\\n  that have changed since the last sync.\\n- `gs apps pull` (no args) refreshes every remote component into\\n  `components/<name>/`. Components with unsaved local edits are skipped\\n  with a warning; pass `--force` to overwrite.\\n\\nSee `AGENTS.md` for the design rules every component must follow\\n(em-based sizing, brand CSS variables) \u2014 it doubles as guidance for AI\\ncoding agents (`CLAUDE.md` / `GEMINI.md` symlink to it).\\n","root/package.json":"{\\n  \\"name\\": \\"greatstore-components\\",\\n  \\"version\\": \\"0.0.1\\",\\n  \\"private\\": true,\\n  \\"type\\": \\"module\\",\\n  \\"scripts\\": {\\n    \\"build\\": \\"gs apps build\\",\\n    \\"push\\": \\"gs apps build && gs apps push\\"\\n  },\\n  \\"dependencies\\": {\\n    \\"react\\": \\"^19.0.0\\",\\n    \\"react-dom\\": \\"^19.0.0\\"\\n  },\\n  \\"devDependencies\\": {\\n    \\"@types/react\\": \\"^19.0.0\\",\\n    \\"@types/react-dom\\": \\"^19.0.0\\",\\n    \\"@vitejs/plugin-react\\": \\"^4.3.0\\",\\n    \\"typescript\\": \\"^5.6.0\\",\\n    \\"vite\\": \\"^5.4.0\\"\\n  }\\n}\\n","root/tsconfig.json":"{\\n  \\"compilerOptions\\": {\\n    \\"target\\": \\"ES2022\\",\\n    \\"module\\": \\"ESNext\\",\\n    \\"moduleResolution\\": \\"Bundler\\",\\n    \\"jsx\\": \\"react-jsx\\",\\n    \\"lib\\": [\\"ES2022\\", \\"DOM\\"],\\n    \\"strict\\": true,\\n    \\"esModuleInterop\\": true,\\n    \\"skipLibCheck\\": true,\\n    \\"isolatedModules\\": true,\\n    \\"noEmit\\": true\\n  },\\n  \\"include\\": [\\"components/**/component.tsx\\", \\"vite.config.ts\\"]\\n}\\n","root/vite.config.ts":"import { defineConfig } from \\"vite\\";\\nimport react from \\"@vitejs/plugin-react\\";\\n\\n// Real builds happen in `gs build` (one Vite invocation per\\n// component, externals + runtime shim paths owned by the CLI). This\\n// file exists only so editors / language servers can resolve the\\n// React plugin when inspecting components/*/component.tsx.\\nexport default defineConfig({\\n  plugins: [react()],\\n});\\n"}') : readTreeFromDisk(new URL("../template/", import.meta.url));
+  return cache;
+}
+var TOKENS = {
+  name: "__GS_NAME__",
+  pascalName: "__GS_PASCAL__",
+  displayName: "__GS_DISPLAY_NAME__",
+  store: "__GS_STORE__"
+};
+function applyTemplate(content, vars) {
+  let out = content;
+  for (const key of Object.keys(TOKENS)) {
+    const value = vars[key];
+    if (value !== void 0) out = out.split(TOKENS[key]).join(value);
   }
-  const rows = data.components.map((c) => ({
-    name: c.name,
-    draft: c.draft ? `v${c.draft.version}` : "\u2014",
-    live: c.live ? `v${c.live.version}` : "\u2014",
-    updated: c.live?.updatedAt ?? c.draft?.updatedAt ?? "",
-    permalink: c.permalink ?? ""
-  }));
-  const widths = {
-    name: Math.max(4, ...rows.map((r) => r.name.length)),
-    draft: Math.max(5, ...rows.map((r) => r.draft.length)),
-    live: Math.max(4, ...rows.map((r) => r.live.length)),
-    updated: Math.max(7, ...rows.map((r) => r.updated.length))
-  };
-  const header = `${pad("NAME", widths.name)}  ${pad("DRAFT", widths.draft)}  ${pad("LIVE", widths.live)}  ${pad("UPDATED", widths.updated)}  LINK`;
-  process.stdout.write(header + "\n");
-  for (const r of rows) {
-    process.stdout.write(
-      `${pad(r.name, widths.name)}  ${pad(r.draft, widths.draft)}  ${pad(r.live, widths.live)}  ${pad(r.updated, widths.updated)}  ${r.permalink}
-`
+  const leftover = out.match(/__GS_[A-Z_]+__/);
+  if (leftover) {
+    throw new Error(
+      `internal: template placeholder ${leftover[0]} was not provided`
     );
   }
+  return out;
 }
-function pad(s, width) {
-  return s.length >= width ? s : s + " ".repeat(width - s.length);
-}
-
-// src/commands/pull.ts
-import * as fs4 from "fs";
-import * as path4 from "path";
 
-// src/sync.ts
-import * as crypto2 from "crypto";
-import * as fs3 from "fs";
-import * as path3 from "path";
-var SYNC_FILE = ".gssync.json";
-function hashString(text) {
-  return crypto2.createHash("sha256").update(text).digest("hex");
-}
-function hashFile(filePath) {
-  if (!fs3.existsSync(filePath)) return null;
-  return hashString(fs3.readFileSync(filePath, "utf8"));
-}
-function computeComponentHashes(componentDir) {
-  const manifestHash = hashFile(path3.join(componentDir, "manifest.json"));
-  if (manifestHash === null) {
-    throw new Error(`Missing manifest.json in ${componentDir}`);
+// src/skill.ts
+var SKILL_DIR_NAME = "greatstore";
+var cache2 = null;
+function loadSkill() {
+  if (cache2) return cache2;
+  cache2 = true ? JSON.parse('{"SKILL.md":"---\\nname: greatstore\\ndescription: 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 \u2014 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.\\n---\\n\\n# Building with GreatStore\\n\\nGreatStore gives a store an AI shopping assistant on two surfaces: a hosted\\nstorefront at `https://<slug>.greatstore.ai/`, and an embedded chat widget on\\nthe merchant\'s own site, installed with one script tag:\\n\\n```html\\n<script src=\\"https://my-store.greatstore.ai/embed.js\\"></script>\\n```\\n\\nEverything else a site can do with GreatStore is documented in the\\nreferences below. Read the one that matches the task before writing code \u2014\\neach facet has non-obvious rules (caching, grounding, result shapes, design\\nconstraints) that the references spell out.\\n\\n## Index\\n\\n| Goal | Use | Read |\\n|---|---|---|\\n| Install the widget; control the panel; readiness, events, troubleshooting | `window.GreatStore` SDK | [references/embed-api.md](references/embed-api.md) |\\n| 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) |\\n| Copy-paste on-page experiences | recipes built on the SDK | the [Recipes](#recipes) table below |\\n| Contextual **conversation entry points** anywhere on the page | `sendMessage(text)`, `open()`, `?gs_chat=open` | [references/embed-api.md](references/embed-api.md) |\\n| Let the assistant **act on the page** (cart, navigation, filters) | WebMCP: `document.modelContext.registerTool(...)` | [references/embed-api.md](references/embed-api.md) |\\n| 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) |\\n| **Re-engage shoppers** with browser notifications | merchant-hosted `gs.js` + `enableNotifications()` | [references/push-notifications.md](references/push-notifications.md) |\\n| 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) |\\n| **Administer the store** \u2014 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) |\\n\\n## Three things to know before any of it\\n\\n- **Every code sample in this skill is a reference implementation, not a\\n  drop-in.** Samples are framework-free vanilla JS so they stay portable \u2014\\n  re-express the same logic in the conventions of the repo you\'re working\\n  in (React, Vue, Shopify Liquid sections, Svelte, \u2026); never retrofit the\\n  sample as-is into a codebase with its own framework.\\n- The page\'s domain **must be in the store\'s allowed domains**. If it isn\'t,\\n  nothing works and the console shows\\n  `[GreatStore] Chat is unavailable on <origin>\u2026` \u2014 check this first whenever\\n  the embed appears dead. You can verify and fix it yourself with the `gs`\\n  CLI (read-merge-write on `extraOrigins` \u2014 see\\n  [references/store-admin.md](references/store-admin.md)).\\n- Every SDK call is safe immediately after the script tag \u2014 pre-mount calls\\n  queue and replay in order, and the SDK pre-warms itself in the background.\\n\\n## Recipes\\n\\nComplete, framework-free implementations, one per file. Shared conventions:\\ncontainers start `hidden` and reveal only on success (a failed generation\\nchanges nothing); generated strings render via `textContent`, never\\n`innerHTML`; every recipe guards on `window.GreatStore`; prompts stay\\ndeterministic per page so repeat renders hit the cache.\\nInline real product/page data into prompts where the platform exposes it.\\n\\n| Recipe | What it builds | Use it for |\\n|---|---|---|\\n| [GreatStore launchers](recipes/launchers.md) | Horizontally scrollable AI-generated chips \u2014 engaging first-person questions about the current page; tap to ask the assistant. | Instant engagement on any page type \u2014 product, collection, blog, home. Simple yet effective; start here. |\\n| [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 \u2014 anywhere a shopper hesitates. |\\n| [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. |\\n| [Comparison table](recipes/comparison-table.md) | AI-picked representative products compared on category-relevant criteria. | Collection pages where shoppers weigh options. |\\n| [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. |\\n| [Campaign hero](recipes/campaign-hero.md) | Seasonal homepage hero copy, cache-keyed to the ISO week. | Fresh homepage/campaign copy without manual rewrites. |\\n| [Gift finder funnel](recipes/gift-finder-funnel.md) | Quiz teaser \u2192 chat handoff \u2192 page-tool navigation; the full funnel. | Gifting seasons, guided discovery, homepage engagement. |\\n| [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. |\\n| [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. |\\n\\n## How the facets combine\\n\\nThe strongest pattern is the **teaser \u2192 conversation \u2192 action** funnel:\\n`generateStructuredContent` renders a grounded teaser in the merchant\'s\\ndesign; each option\'s click handler calls `sendMessage` with the shopper\'s\\nchoice, dropping them into a conversation with momentum; WebMCP page tools\\nand custom chat components let that conversation actually do things \u2014 add to\\ncart, configure a product, book a slot \u2014 so it ends in a conversion, not a\\ncopy-paste. The [gift finder funnel](recipes/gift-finder-funnel.md)\\nrecipe is this funnel end to end.\\n","recipes/ask-about-this.md":"# \\"Ask about this\\" entry points (`sendMessage` only)\\n\\n> **Treat this code as a reference, not a drop-in.** Samples are\\n> framework-free vanilla JS so they stay portable \u2014 re-express the same\\n> logic in the conventions of the repo you\'re working in (React, Vue,\\n> Shopify Liquid sections, Svelte, \u2026) instead of retrofitting the sample\\n> as-is.\\n\\nZero-generation, instant, and often the biggest engagement win per line of\\ncode. Sprinkle context-aware buttons wherever a shopper hesitates:\\n\\n```js\\nconst gs = window.GreatStore;\\nif (gs) {\\n  sizeGuideLink.addEventListener(\\"click\\", (e) => {\\n    e.preventDefault();\\n    gs.sendMessage(`How does the sizing run on \\"${productName}\\"? I usually wear a medium.`);\\n  });\\n\\n  shippingRow.querySelector(\\".ask\\").addEventListener(\\"click\\", () => {\\n    gs.sendMessage(`What are the shipping options and times for \\"${productName}\\"?`);\\n  });\\n\\n  outOfStockBadge?.addEventListener(\\"click\\", () => {\\n    gs.sendMessage(`\\"${productName}\\" looks out of stock \u2014 is there anything similar in stock?`);\\n  });\\n}\\n```\\n\\nWrite each message as something the shopper would plausibly say \u2014 it appears\\nin the transcript as their message.\\n","recipes/campaign-hero.md":"# Campaign hero with deliberate variation\\n\\n> **Treat this code as a reference, not a drop-in.** Samples are\\n> framework-free vanilla JS so they stay portable \u2014 re-express the same\\n> logic in the conventions of the repo you\'re working in (React, Vue,\\n> Shopify Liquid sections, Svelte, \u2026) instead of retrofitting the sample\\n> as-is.\\n\\nCache-friendly variation: key the prompt to a low-cardinality period, not to\\ntime itself.\\n\\n```js\\n// ISO week number \u2192 one generation per store per week, shared by everyone.\\nconst week = (d => {\\n  const t = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));\\n  t.setUTCDate(t.getUTCDate() + 4 - (t.getUTCDay() || 7));\\n  return `${t.getUTCFullYear()}-W${Math.ceil((((t - Date.UTC(t.getUTCFullYear(), 0, 1)) / 864e5) + 1) / 7)}`;\\n})(new Date());\\n\\nconst data = await window.GreatStore.generateStructuredContent(\\n  {\\n    type: \\"object\\",\\n    properties: {\\n      headline: { type: \\"string\\", maxLength: 60 },\\n      subline: { type: \\"string\\", maxLength: 120 },\\n      featuredProductName: { type: \\"string\\", nullable: true },\\n      ctaChatMessage: { type: \\"string\\", maxLength: 120 },\\n    },\\n    required: [\\"headline\\", \\"subline\\", \\"ctaChatMessage\\"],\\n  },\\n  `Variant ${week}. Write a homepage hero for this store: a headline and ` +\\n    `subline spotlighting a real product or category that fits the current ` +\\n    `season, plus ctaChatMessage \u2014 the first-person message a shopper ` +\\n    `would send to start shopping for it.`\\n);\\n\\nheroHeadline.textContent = data.headline;\\nheroSubline.textContent = data.subline;\\nheroCta.addEventListener(\\"click\\", () =>\\n  window.GreatStore.sendMessage(data.ctaChatMessage)\\n);\\nhero.hidden = false;\\n```\\n","recipes/comparison-table.md":"# Collection-page comparison table\\n\\n> **Treat this code as a reference, not a drop-in.** Samples are\\n> framework-free vanilla JS so they stay portable \u2014 re-express the same\\n> logic in the conventions of the repo you\'re working in (React, Vue,\\n> Shopify Liquid sections, Svelte, \u2026) instead of retrofitting the sample\\n> as-is.\\n\\n```html\\n<section id=\\"gs-compare\\" hidden>\\n  <h3>Quick comparison</h3>\\n  <table><thead id=\\"gsc-head\\"></thead><tbody id=\\"gsc-body\\"></tbody></table>\\n</section>\\n\\n<script>\\n  (async () => {\\n    if (!window.GreatStore?.generateStructuredContent) return;\\n    const collection = \\"winter jackets\\"; // \u2190 your collection name\\n    try {\\n      const data = await window.GreatStore.generateStructuredContent(\\n        {\\n          type: \\"object\\",\\n          properties: {\\n            criteria: {\\n              type: \\"array\\", minItems: 2, maxItems: 4,\\n              items: { type: \\"string\\", maxLength: 25 },\\n            },\\n            rows: {\\n              type: \\"array\\", minItems: 2, maxItems: 4,\\n              items: {\\n                type: \\"object\\",\\n                properties: {\\n                  productName: { type: \\"string\\" },\\n                  bestFor: { type: \\"string\\", maxLength: 60 },\\n                  values: {\\n                    type: \\"array\\",\\n                    items: { type: \\"string\\", maxLength: 60 },\\n                  },\\n                },\\n                required: [\\"productName\\", \\"bestFor\\", \\"values\\"],\\n              },\\n            },\\n          },\\n          required: [\\"criteria\\", \\"rows\\"],\\n        },\\n        `The shopper is browsing the \\"${collection}\\" collection. Pick the ` +\\n          `3-4 most representative products and compare them. Choose the ` +\\n          `criteria a shopper actually decides on for this category. ` +\\n          `\\"values\\" must align with \\"criteria\\" by index. Add a one-line ` +\\n          `\\"bestFor\\" verdict per product. Only use real products and facts.`\\n      );\\n\\n      const head = document.getElementById(\\"gsc-head\\");\\n      const hr = document.createElement(\\"tr\\");\\n      for (const h of [\\"Product\\", ...data.criteria, \\"Best for\\"]) {\\n        const th = document.createElement(\\"th\\");\\n        th.textContent = h;\\n        hr.append(th);\\n      }\\n      head.append(hr);\\n\\n      const body = document.getElementById(\\"gsc-body\\");\\n      for (const row of data.rows) {\\n        const tr = document.createElement(\\"tr\\");\\n        const cells = [row.productName, ...(row.values ?? []), row.bestFor];\\n        for (let i = 0; i < data.criteria.length + 2; i++) {\\n          const td = document.createElement(\\"td\\");\\n          td.textContent = cells[i] ?? \\"\u2014\\";\\n          tr.append(td);\\n        }\\n        body.append(tr);\\n      }\\n      document.getElementById(\\"gs-compare\\").hidden = false;\\n    } catch {}\\n  })();\\n</script>\\n```\\n\\nNote the index-aligned `values`/`criteria` trick and the `?? \\"\u2014\\"` guard \u2014\\ngrounding means a value the catalog can\'t support may be missing.\\n","recipes/complete-the-look.md":"# \\"Complete the look\\" cross-sell strip\\n\\n> **Treat this code as a reference, not a drop-in.** Samples are\\n> framework-free vanilla JS so they stay portable \u2014 re-express the same\\n> logic in the conventions of the repo you\'re working in (React, Vue,\\n> Shopify Liquid sections, Svelte, \u2026) instead of retrofitting the sample\\n> as-is.\\n\\n```js\\nconst data = await window.GreatStore.generateStructuredContent(\\n  {\\n    type: \\"object\\",\\n    properties: {\\n      intro: { type: \\"string\\", maxLength: 90 },\\n      picks: {\\n        type: \\"array\\", minItems: 2, maxItems: 4,\\n        items: {\\n          type: \\"object\\",\\n          properties: {\\n            productName: { type: \\"string\\" },\\n            reason: { type: \\"string\\", maxLength: 90 },\\n            imageUrl: { type: \\"string\\", nullable: true },\\n            productUrl: { type: \\"string\\", nullable: true },\\n          },\\n          required: [\\"productName\\", \\"reason\\"],\\n        },\\n      },\\n    },\\n    required: [\\"picks\\"],\\n  },\\n  `The shopper is viewing \\"${productName}\\". From the store\'s real catalog, ` +\\n    `pick 2-4 products that genuinely pair with it and say why each one ` +\\n    `completes the look or use-case. Include image and product URLs only ` +\\n    `if known.`\\n);\\n\\nfor (const pick of data.picks) {\\n  const card = document.createElement(\\"a\\");\\n  if (pick.productUrl) card.href = pick.productUrl;\\n  if (pick.imageUrl) {\\n    const img = document.createElement(\\"img\\");\\n    img.src = pick.imageUrl;\\n    img.alt = pick.productName;\\n    img.loading = \\"lazy\\";\\n    card.append(img);\\n  }\\n  const name = document.createElement(\\"strong\\");\\n  name.textContent = pick.productName;\\n  const why = document.createElement(\\"p\\");\\n  why.textContent = pick.reason;\\n  card.append(name, why);\\n  strip.append(card);\\n}\\nstrip.hidden = false;\\n```\\n\\n`imageUrl`/`productUrl` are `nullable` and optional in the render \u2014 the\\ngrounding contract means they\'re only present when the catalog actually has\\nthem. Never `require` URLs.\\n","recipes/custom-chat-button.md":"# Custom chat button synced to panel state\\n\\n> **Treat this code as a reference, not a drop-in.** Samples are\\n> framework-free vanilla JS so they stay portable \u2014 re-express the same\\n> logic in the conventions of the repo you\'re working in (React, Vue,\\n> Shopify Liquid sections, Svelte, \u2026) instead of retrofitting the sample\\n> as-is.\\n\\nReplace the default launcher with your own UI using the lifecycle surface:\\n\\n```js\\nconst gs = window.GreatStore;\\nconst btn = document.getElementById(\\"my-chat-button\\");\\n\\ngs.ready.then(() => { btn.hidden = false; });\\nbtn.addEventListener(\\"click\\", () => gs.toggle());\\n\\ngs.on(\\"open\\",  () => btn.setAttribute(\\"aria-expanded\\", \\"true\\"));\\ngs.on(\\"close\\", () => btn.setAttribute(\\"aria-expanded\\", \\"false\\"));\\n```\\n\\n`ready` resolves even when `.then()` is attached after mount, so script\\nordering doesn\'t matter. The `open`/`close` events also fire for opens the\\nSDK triggers itself (`sendMessage`, `?gs_chat=open`), keeping your button\\nstate honest.\\n","recipes/gift-finder-funnel.md":"# Gift finder funnel (teaser \u2192 conversation \u2192 action)\\n\\n> **Treat this code as a reference, not a drop-in.** Samples are\\n> framework-free vanilla JS so they stay portable \u2014 re-express the same\\n> logic in the conventions of the repo you\'re working in (React, Vue,\\n> Shopify Liquid sections, Svelte, \u2026) instead of retrofitting the sample\\n> as-is.\\n\\nThe flagship pattern: an AI-generated quiz card in your design, whose answers\\ndrop the shopper into a chat that can act on the page.\\n\\n```html\\n<section id=\\"gift-finder\\" hidden>\\n  <h3 id=\\"gf-question\\"></h3>\\n  <div id=\\"gf-options\\"></div>\\n</section>\\n\\n<script>\\n  (async () => {\\n    const gs = window.GreatStore;\\n    if (!gs?.generateStructuredContent) return;\\n\\n    // Tools the resulting conversation can use. Registered once the\\n    // SDK is ready (so document.modelContext exists); the assistant\\n    // discovers them on its next turn automatically.\\n    gs.ready.then(() => {\\n      document.modelContext.registerTool({\\n        name: \\"go_to_product\\",\\n        description:\\n          \\"Navigate the shopper to a product page on this site. Use when \\" +\\n          \\"the shopper picks a product they want to see.\\",\\n        inputSchema: {\\n          type: \\"object\\",\\n          properties: { url: { type: \\"string\\" } },\\n          required: [\\"url\\"],\\n        },\\n        execute({ url }) {\\n          const u = new URL(String(url), location.origin);\\n          if (u.origin !== location.origin) throw new Error(\\"Only same-site URLs allowed\\");\\n          location.assign(u.href);\\n          return { content: [{ type: \\"text\\", text: \\"Navigating.\\" }] };\\n        },\\n      });\\n    });\\n\\n    try {\\n      const data = await gs.generateStructuredContent(\\n        {\\n          type: \\"object\\",\\n          properties: {\\n            question: { type: \\"string\\", maxLength: 80 },\\n            options: {\\n              type: \\"array\\",\\n              minItems: 3,\\n              maxItems: 4,\\n              items: {\\n                type: \\"object\\",\\n                properties: {\\n                  label: { type: \\"string\\", maxLength: 30 },\\n                  chatMessage: { type: \\"string\\", maxLength: 140 },\\n                },\\n                required: [\\"label\\", \\"chatMessage\\"],\\n              },\\n            },\\n          },\\n          required: [\\"question\\", \\"options\\"],\\n        },\\n        \\"Create one engaging gift-finder opening question for this store, \\" +\\n          \\"with 3-4 answer options that map to real areas of the catalog. \\" +\\n          \\"For each option also write chatMessage: the message a shopper \\" +\\n          \\"would send to a shopping assistant after picking it, phrased in \\" +\\n          \\"first person (e.g. \\\\\\"I\'m shopping for my dad who loves hiking\\\\\\").\\"\\n      );\\n\\n      document.getElementById(\\"gf-question\\").textContent = data.question;\\n      const wrap = document.getElementById(\\"gf-options\\");\\n      for (const opt of data.options) {\\n        const btn = document.createElement(\\"button\\");\\n        btn.type = \\"button\\";\\n        btn.textContent = opt.label;\\n        btn.addEventListener(\\"click\\", () => gs.sendMessage(opt.chatMessage));\\n        wrap.append(btn);\\n      }\\n      document.getElementById(\\"gift-finder\\").hidden = false;\\n    } catch {}\\n  })();\\n</script>\\n```\\n\\nWhy it works: the teaser costs one cached generation per page, each\\nclick opens a conversation that already has direction, and `go_to_product`\\nlets the conversation end on a product page instead of in a dead end.\\n","recipes/launchers.md":"# GreatStore launchers \u2014 AI question chips\\n\\n> **Treat this code as a reference, not a drop-in.** Samples are\\n> framework-free vanilla JS so they stay portable \u2014 re-express the same\\n> logic in the conventions of the repo you\'re working in (React, Vue,\\n> Shopify Liquid sections, Svelte, \u2026) instead of retrofitting the sample\\n> as-is.\\n\\nA horizontally scrollable row of chips, each a highly engaging first-person\\nquestion about the current page. Tapping a chip sends that question to the\\nassistant \u2014 `generateStructuredContent` writes the questions, `sendMessage`\\nfires them. Simple yet effective: it works on every page type, costs one\\ncached generation per page, and every tap starts a conversation that already\\nhas a great opening line.\\n\\n```html\\n<div id=\\"gs-launchers\\" hidden></div>\\n\\n<style>\\n  #gs-launchers {\\n    display: flex;\\n    gap: 0.5em;\\n    overflow-x: auto;\\n    -webkit-overflow-scrolling: touch;\\n    scrollbar-width: none;\\n    padding: 0.5em 1em;\\n  }\\n  #gs-launchers::-webkit-scrollbar { display: none; }\\n  #gs-launchers button {\\n    flex: 0 0 auto;\\n    white-space: nowrap;\\n    border: 1px solid #ddd;\\n    border-radius: 999px;\\n    padding: 0.5em 0.9em;\\n    background: #fff;\\n    cursor: pointer;\\n  }\\n</style>\\n\\n<script>\\n  (async () => {\\n    const gs = window.GreatStore;\\n    if (!gs?.generateStructuredContent) return;\\n    try {\\n      const data = await gs.generateStructuredContent(\\n        {\\n          type: \\"object\\",\\n          properties: {\\n            launchers: {\\n              type: \\"array\\", minItems: 4, maxItems: 6,\\n              items: {\\n                type: \\"object\\",\\n                properties: {\\n                  chip: { type: \\"string\\", maxLength: 32 },\\n                  question: { type: \\"string\\", maxLength: 140 },\\n                },\\n                required: [\\"chip\\", \\"question\\"],\\n              },\\n            },\\n          },\\n          required: [\\"launchers\\"],\\n        },\\n        `The shopper is on the page \\"${document.title}\\". Write 4-6 launcher ` +\\n          `chips for a shopping assistant. For each, \\"question\\" is a highly ` +\\n          `engaging first-person question this shopper would genuinely want ` +\\n          `answered on this page \u2014 specific to its product, category, or ` +\\n          `content, never generic \u2014 and \\"chip\\" is a 2-4 word teaser of it. ` +\\n          `Vary the angles: fit and use, comparisons, gifting, care, what\'s ` +\\n          `popular.`\\n      );\\n\\n      const row = document.getElementById(\\"gs-launchers\\");\\n      for (const { chip, question } of data.launchers) {\\n        const btn = document.createElement(\\"button\\");\\n        btn.type = \\"button\\";\\n        btn.textContent = chip;\\n        btn.title = question;\\n        btn.addEventListener(\\"click\\", () => gs.sendMessage(question));\\n        row.append(btn);\\n      }\\n      row.hidden = false;\\n    } catch {}\\n  })();\\n</script>\\n```\\n\\nWhy it works:\\n\\n- **The chip is the teaser, the question is the payload.** A 2-4 word chip\\n  scans instantly; the full first-person question lands in the transcript\\n  reading like something the shopper typed, and gives the assistant a\\n  well-formed prompt. The `title` attribute previews the full question on\\n  hover.\\n- **Per-page for free.** The page URL is part of the generation context and\\n  the cache key, so one site-wide snippet yields different chips on every\\n  page \u2014 each served from cache on repeat renders.\\n- **Placement is the lever.** Under the product title, above the grid on\\n  collections, at the end of a blog post \u2014 wherever a shopper pauses to\\n  wonder, the chips name the question for them.\\n\\nTips:\\n\\n- Inline the product or collection name into the prompt when the platform\\n  exposes it \u2014 it beats relying on `document.title`.\\n- Restyle the chips to the site\'s design system; the CSS above is just the\\n  scroll mechanics (flex row, `overflow-x: auto`, hidden scrollbars,\\n  `white-space: nowrap`).\\n- Resist adding more than ~6 chips \u2014 a launcher row is an invitation, not a\\n  sitemap.\\n","recipes/page-action-suite.md":"# Page-action suite (WebMCP)\\n\\n> **Treat this code as a reference, not a drop-in.** Samples are\\n> framework-free vanilla JS so they stay portable \u2014 re-express the same\\n> logic in the conventions of the repo you\'re working in (React, Vue,\\n> Shopify Liquid sections, Svelte, \u2026) instead of retrofitting the sample\\n> as-is.\\n\\nGive every conversation on the site real capabilities. Register once in a\\nshared snippet, after the SDK is ready (which guarantees\\n`document.modelContext` exists):\\n\\n```js\\nwindow.GreatStore?.ready.then(() => {\\n  const text = (value) => ({\\n    content: [{ type: \\"text\\", text: JSON.stringify(value) }],\\n  });\\n\\n  document.modelContext.registerTool({\\n    name: \\"get_cart\\",\\n    description:\\n      \\"Read the shopper\'s current cart on this site: items, quantities, \\" +\\n      \\"and totals. Use before answering any cart question.\\",\\n    inputSchema: { type: \\"object\\", properties: {} },\\n    async execute() {\\n      return text(await (await fetch(\\"/cart.js\\")).json());\\n    },\\n  });\\n\\n  document.modelContext.registerTool({\\n    name: \\"add_to_cart\\",\\n    description:\\n      \\"Add a product variant to the cart on this site. Use when the \\" +\\n      \\"shopper asks to add or buy something. Confirm the variant with \\" +\\n      \\"the shopper first if ambiguous.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        variantId: { type: \\"string\\" },\\n        quantity: { type: \\"integer\\", minimum: 1, maximum: 10 },\\n      },\\n      required: [\\"variantId\\"],\\n    },\\n    async execute({ variantId, quantity }) {\\n      if (!variantId) throw new Error(\\"variantId is required\\");\\n      const res = await fetch(\\"/cart/add.js\\", {\\n        method: \\"POST\\",\\n        headers: { \\"Content-Type\\": \\"application/json\\" },\\n        body: JSON.stringify({ id: variantId, quantity: quantity ?? 1 }),\\n      });\\n      if (!res.ok) throw new Error(`Could not add to cart (${res.status})`);\\n      document.dispatchEvent(new CustomEvent(\\"cart:refresh\\"));\\n      return text(await res.json());\\n    },\\n  });\\n\\n  document.modelContext.registerTool({\\n    name: \\"get_current_page\\",\\n    description:\\n      \\"Read what page the shopper is currently on, including structured \\" +\\n      \\"product data when on a product page.\\",\\n    inputSchema: { type: \\"object\\", properties: {} },\\n    execute() {\\n      return text({\\n        url: location.href,\\n        title: document.title,\\n        productJson: document.querySelector(\\"#product-json\\")?.textContent ?? null,\\n      });\\n    },\\n  });\\n});\\n```\\n\\nPrinciples at work: throw on failure (the assistant explains and recovers),\\nreturn fresh state after mutations (the assistant confirms accurately), cap\\nquantities in the schema, and notify your own UI (`cart:refresh`) so the\\npage reflects what the AI did.\\n\\nFor a product-page-only tool, register with an `AbortSignal` and abort on\\nSPA navigation:\\n\\n```js\\nconst ac = new AbortController();\\ndocument.modelContext.registerTool(reviewsTool, { signal: ac.signal });\\nrouter.onLeave(\\"/products/:handle\\", () => ac.abort());\\n```\\n","recipes/product-faq.md":"# Product FAQ accordion\\n\\n> **Treat this code as a reference, not a drop-in.** Samples are\\n> framework-free vanilla JS so they stay portable \u2014 re-express the same\\n> logic in the conventions of the repo you\'re working in (React, Vue,\\n> Shopify Liquid sections, Svelte, \u2026) instead of retrofitting the sample\\n> as-is.\\n\\n```js\\nconst data = await window.GreatStore.generateStructuredContent(\\n  {\\n    type: \\"object\\",\\n    properties: {\\n      faqs: {\\n        type: \\"array\\", minItems: 3, maxItems: 5,\\n        items: {\\n          type: \\"object\\",\\n          properties: {\\n            question: { type: \\"string\\", maxLength: 90 },\\n            answer: { type: \\"string\\", maxLength: 300 },\\n          },\\n          required: [\\"question\\", \\"answer\\"],\\n        },\\n      },\\n    },\\n    required: [\\"faqs\\"],\\n  },\\n  `Generate the questions shoppers most plausibly have before buying the ` +\\n    `product \\"${productName}\\", with accurate answers grounded in the real ` +\\n    `product details and store policies. Skip any question the store data ` +\\n    `can\'t answer confidently.`\\n);\\n\\nconst wrap = document.getElementById(\\"gs-faq\\");\\nfor (const { question, answer } of data.faqs) {\\n  const details = document.createElement(\\"details\\");\\n  const summary = document.createElement(\\"summary\\");\\n  summary.textContent = question;\\n  const p = document.createElement(\\"p\\");\\n  p.textContent = answer;\\n  details.append(summary, p);\\n  wrap.append(details);\\n}\\nwrap.hidden = false;\\n```\\n\\nEngagement bonus \u2014 append a hand-off row so unanswered questions become\\nconversations:\\n\\n```js\\nconst ask = document.createElement(\\"button\\");\\nask.type = \\"button\\";\\nask.textContent = \\"Have a different question? Ask us\\";\\nask.addEventListener(\\"click\\", () =>\\n  window.GreatStore.sendMessage(`I have a question about \\"${productName}\\".`)\\n);\\nwrap.append(ask);\\n```\\n","references/agents-and-mcp.md":"# AI agents and the store\'s MCP endpoints\\n\\nBeyond the widget, every GreatStore store is reachable by AI agents directly\\nover the Model Context Protocol. Three URLs, all on the store\'s subdomain,\\nnone requiring authentication:\\n\\n| URL | What it is |\\n|---|---|\\n| `https://<slug>.greatstore.ai/.well-known/mcp/server-card.json` | Standard MCP server card \u2014 machine-readable discovery document for the store. |\\n| `https://<slug>.greatstore.ai/mcp` | The store\'s **shopping tools** over MCP \u2014 product search and related catalog actions, the same capabilities the assistant itself shops with. |\\n| `https://<slug>.greatstore.ai/admin-mcp` | A **documentation server for coding agents**: its tools return usage docs for the `gs` CLI. |\\n\\n## Shopping tools \u2014 `/mcp`\\n\\nConnect any MCP-capable agent to let it browse and shop the store\\nprogrammatically. This is the integration point for agentic-shopping\\nclients, comparison bots, or the merchant\'s own automations that need live\\ncatalog answers.\\n\\n## CLI docs for coding agents \u2014 `/admin-mcp`\\n\\nA stateless HTTP MCP whose tools hand back markdown documentation for `gs`\\nCLI commands. When accessed via the store\'s subdomain, every example comes\\npre-pinned to that store\'s slug, so the agent never has to ask which store\\nto target.\\n\\n```\\nclaude mcp add --transport http greatstore https://my-store.greatstore.ai/admin-mcp\\n```\\n\\nUseful when a coding agent is shipping chat components\\n([chat-components.md](chat-components.md)) and needs the exact command for\\nthe next step. If this skill is installed, the agent already has the\\nworkflow \u2014 the MCP is the self-serve alternative for agents that don\'t.\\n\\n## What to use when\\n\\n- **Building the merchant\'s site** \u2192 this skill\'s other references (the SDK,\\n  structured content, page tools).\\n- **A coding agent shipping chat components** \u2192 the `gs` CLI, with\\n  `/admin-mcp` as its built-in documentation.\\n- **Reading or changing store settings** (origin allowlists, CSP hosts, MCP\\n  connectors, brand config) \u2192 the `gs` CLI\'s admin commands \u2014\\n  [store-admin.md](store-admin.md), including which changes are safe to make\\n  without asking the merchant.\\n- **An agent that needs to *shop* the store** (search products, read catalog\\n  data) from outside any web page \u2192 `/mcp`.\\n","references/chat-components.md":"# Custom chat components \u2014 authoring with the `gs` CLI\\n\\nRemote components are React components the assistant renders **inside the\\nconversation** \u2014 product configurators, quizzes, size guides, booking forms,\\nanything richer than text. Each component is an AI-callable tool: the\\nmanifest\'s `description` tells the assistant *when* to show it, its\\n`inputSchema` declares the props the assistant fills in, and a `displayMode`\\npicks where it appears.\\n\\nAuthoring requires store-owner access (`gs login` signs in with the store\\nowner\'s account).\\n\\n## Workflow\\n\\n```\\nnpm install -g @greatstore/cli     # or npx @greatstore/cli <command>\\ngs login                           # browser sign-in\\ngs apps init --store my-store      # scaffold a project root\\ncd <project> && npm install\\ngs apps init size_guide            # scaffold components/size_guide/\\n# \u2026 edit components/size_guide/{component.tsx,manifest.json} \u2026\\ngs apps build                      # bundle every component\\ngs apps push                       # upload changed components as drafts\\ngs apps publish size_guide         # promote to live\\n```\\n\\n`gs apps list` shows what\'s deployed (with dashboard links); `gs apps pull`\\nround-trips remote components back to disk. `gs apps push` hashes components\\nand only uploads what changed. (The subcommands also work at the top level \u2014\\n`gs push` == `gs apps push`.)\\n\\nThe scaffold writes an `AGENTS.md` into the project (with `CLAUDE.md` /\\n`GEMINI.md` symlinked) containing the complete design rules and brand\\nvariable table \u2014 your coding agent picks it up automatically when working in\\nthe project. The store\'s `/admin-mcp` endpoint serves the same CLI docs to\\nagents over MCP (see [agents-and-mcp.md](agents-and-mcp.md)).\\n\\n## `manifest.json`\\n\\n```json\\n{\\n  \\"name\\": \\"size_guide\\",\\n  \\"displayName\\": \\"Size guide\\",\\n  \\"description\\": \\"Interactive size guide. Show when the shopper asks about sizing or fit for apparel.\\",\\n  \\"displayMode\\": \\"inline\\",\\n  \\"inputSchema\\": {\\n    \\"type\\": \\"object\\",\\n    \\"properties\\": {\\n      \\"productName\\": { \\"type\\": \\"string\\" },\\n      \\"category\\": { \\"type\\": \\"string\\" }\\n    },\\n    \\"required\\": [\\"productName\\"]\\n  }\\n}\\n```\\n\\n| Field | Meaning |\\n|---|---|\\n| `name` | Tool name, snake_case (`^[a-z][a-z0-9_]*$`), matches the folder under `components/`. |\\n| `displayName` | Friendly label shown in chat UI. |\\n| `description` | **Load-bearing** \u2014 how the assistant decides when to render the component. Say what it shows *and* when to use it, like any good tool description. |\\n| `displayMode` | Where it renders \u2014 see below. |\\n| `inputSchema` | JSON Schema for the props the assistant fills. Keep it tight; required fields the AI can\'t infer cause bad calls. |\\n| `async` | Set `true` for backend-backed components (see Async below). |\\n\\n### Display modes\\n\\n- `inline` \u2014 a bubble inside the chat transcript; persists with the message\\n  log.\\n- `over-input` \u2014 floats above the chat input (like a question overlay);\\n  cleared by the next user turn or an explicit close.\\n- `fullscreen` \u2014 takes over the full preview surface; persists until the\\n  next widget-emitting tool call or an explicit close.\\n\\n## The component contract\\n\\n`component.tsx` default-exports a React component. Its props are the\\n`inputSchema` fields the assistant filled, plus three GreatStore-injected\\nlifecycle props (always present):\\n\\n| Prop | What it does |\\n|---|---|\\n| `onSendMessage(text)` | Send text into the chat as if the shopper typed it \u2014 lets the component drive the conversation (\\"Selected size M, what\'s the return policy?\\"). |\\n| `onCallTool(name, args)` | Chain into another remote-component tool by name. |\\n| `onClose()` | Dismiss the host slot. `over-input` clears the overlay, `fullscreen` reverts the pane, `inline` is a no-op. |\\n\\n```tsx\\nimport React from \\"react\\";\\n\\ninterface Props {\\n  productName: string;\\n  category?: string;\\n  onSendMessage: (text: string) => void;\\n  onCallTool: (name: string, args: Record<string, unknown>) => void;\\n  onClose: () => void;\\n}\\n\\nexport default function SizeGuide({ productName, onSendMessage }: Props) {\\n  return (\\n    <div\\n      style={{\\n        padding: \\"1em\\",\\n        border: \\"1px solid var(--color-border-default)\\",\\n        borderRadius: \\"var(--radius-lg)\\",\\n        background: \\"var(--color-surface)\\",\\n        color: \\"var(--color-foreground)\\",\\n        fontFamily: \\"var(--font-sans)\\",\\n      }}\\n    >\\n      {/* \u2026 sizes for {productName} \u2026 */}\\n      <button onClick={() => onSendMessage(`Size M of \\"${productName}\\" \u2014 is it in stock?`)}>\\n        Check size M\\n      </button>\\n    </div>\\n  );\\n}\\n```\\n\\n## Design rules (non-negotiable)\\n\\nComponents render inside arbitrary publisher pages *and* the GreatStore\\nstorefront; you control neither the host\'s root font size nor its colors.\\n\\n1. **Size in `em`, never `rem`** \u2014 `rem` resolves against the host page\'s\\n   root font size, which is arbitrary (`html { font-size: 8px }` breaks every\\n   `rem` dimension). `em` stays self-consistent anywhere. Borders may stay\\n   `px`.\\n2. **Never hardcode colors, fonts, or radii** \u2014 read the brand CSS variables\\n   GreatStore injects (`--color-primary`, `--color-surface`,\\n   `--color-foreground`, `--color-border-default`, `--font-sans`,\\n   `--radius-lg`, \u2026) so the component restyles itself with the store\'s\\n   theme. The scaffolded `AGENTS.md` has the full variable table.\\n\\n## Async components (backend-backed data)\\n\\nIf a component must load data before it can render correctly, don\'t render a\\nshell and fetch in `useEffect` \u2014 set `\\"async\\": true` in the manifest and\\nexport an **async** default. GreatStore shows its own loading state, awaits\\nyour promise, and renders what it resolves to.\\n\\nA thrown error is a **retry signal**: the assistant sees it and usually\\nre-calls the tool. So only throw when a *different* call could help:\\n\\n1. Validate the AI-passed props first and throw on bad input \u2014 the AI can\\n   fix the args and retry. (Don\'t validate the API\'s *output* and throw: the\\n   AI can\'t fix your backend, it\'ll just loop.)\\n2. Throw on failures where retrying differently could succeed, and say what\\n   to change (e.g. empty search \u2192 `\\"no results for X \u2014 try a broader keyword\\"`).\\n3. For idempotent failures (500, timeout, missing record) render a graceful\\n   fallback instead of throwing \u2014 re-running the same call changes nothing.\\n\\n```tsx\\nexport default async function Results(props: Props) {\\n  if (!props.query?.trim()) throw new Error(\\"missing required prop: query\\");\\n  const res = await fetch(`/api/search?q=${encodeURIComponent(props.query)}`);\\n  if (res.ok) {\\n    const { results } = await res.json();\\n    if (results.length === 0)\\n      throw new Error(`no results for \\"${props.query}\\" \u2014 try a broader keyword`);\\n    return <ul>{/* render results */}</ul>;\\n  }\\n  return <p>Couldn\'t load results right now.</p>; // idempotent: don\'t throw\\n}\\n```\\n\\n## When to build a component vs. the other facets\\n\\n- Content for the **merchant\'s page** \u2192 `generateStructuredContent`\\n  ([structured-content.md](structured-content.md)).\\n- Letting the assistant **act on the page** \u2192 WebMCP page tools\\n  ([embed-api.md](embed-api.md)).\\n- Rich, interactive UI **inside the conversation itself**, available on the\\n  storefront and every embed without page changes \u2192 a chat component.\\n","references/embed-api.md":"# `window.GreatStore` API reference\\n\\n## Setup\\n\\n```html\\n<script src=\\"https://my-store.greatstore.ai/embed.js\\"></script>\\n```\\n\\nOne script tag, anywhere on the page (end of `<body>` preferred), with the\\nstore\'s slug in the host. The `window.GreatStore` object exists synchronously\\nonce the script executes; every method below is safe to call before the chat\\nUI has finished loading \u2014 pre-mount calls are queued and replayed in order\\nonce it mounts. The SDK pre-warms its chat bundle in the background\\nautomatically; the panel stays closed until `open()` / `toggle()` /\\n`sendMessage()` is called or the shopper clicks the launcher.\\n\\nRequirements:\\n\\n- The page\'s domain must be in the store\'s **allowed domains** (GreatStore\\n  store settings) \u2014 see Troubleshooting below for the failure signature.\\n- If the store also wants push notifications, host `gs.js` at the site root\\n  and load that instead of `embed.js` \u2014 it injects the embed for you. See\\n  [push-notifications.md](push-notifications.md).\\n\\nCode samples throughout are framework-free reference implementations \u2014\\nre-express them in the host repo\'s framework (React, Vue, Shopify Liquid,\\n\u2026) rather than retrofitting them as-is.\\n\\n## Properties\\n\\n| Property | Type | Description |\\n|---|---|---|\\n| `slug` | `string` | The store identifier the script was loaded for. |\\n| `host` | `string` | `\\"greatstore.ai\\"`. |\\n| `embedHost` | `string` | Origin the embed assets load from, e.g. `https://<slug>.greatstore.ai`. |\\n| `ready` | `Promise<void>` | Resolves when the chat UI has mounted and `open()` would render instantly. Resolved promises replay, so `.then()` works no matter when it\'s attached. The recommended readiness signal. |\\n| `isReady` | `boolean` | Synchronous alternative to `ready`. `false` until mount. |\\n\\nA `greatstore:ready` `CustomEvent` (with the SDK object as `detail`) is also\\ndispatched on `window` at the moment `ready` resolves, for declarative\\ntooling. Unlike the promise, the listener must be attached before mount\\ncompletes \u2014 attach it before (or immediately after) the embed script tag.\\n\\n## Methods\\n\\n### `load(): void`\\n\\nPre-warms the chat bundle and identity in the background without opening the\\npanel. Called automatically when `embed.js` runs, so you rarely need it.\\nIdempotent.\\n\\n### `open(): void` / `close(): void` / `toggle(): void`\\n\\nOpen, close, or toggle the chat panel. On desktop the panel is a floating\\nside panel; under 768px viewport width it\'s a full-height drawer. All three\\nqueue if called before mount.\\n\\n### `sendMessage(text: string): void`\\n\\nSends `text` as the shopper\'s own visible chat message and **opens the panel\\nif it\'s closed**. The text is trimmed; empty or whitespace-only strings are\\nsilently dropped. Queues if called before mount.\\n\\nThis is the highest-leverage one-liner in the SDK: any element on the page\\ncan become a conversation entry point with context baked into the question.\\n\\n```js\\ndocument.querySelector(\\"#ask-fit\\").addEventListener(\\"click\\", () => {\\n  window.GreatStore.sendMessage(\\n    `I\'m looking at \\"${productName}\\" \u2014 how does the sizing run?`\\n  );\\n});\\n```\\n\\nBecause the message renders as if the shopper typed it, write it in the\\nshopper\'s voice. It is not a hidden-context channel \u2014 don\'t stuff it with\\ninvisible instructions or data dumps.\\n\\n### `on(event: string, handler: (...args) => void): () => void`\\n\\nSubscribe to SDK events. Returns an unsubscribe function. Listeners attached\\nbefore mount are queued and wired up at mount. Handler exceptions are caught\\nand reported \u2014 they won\'t break the chat.\\n\\nEvents emitted:\\n\\n| Event | Fired when |\\n|---|---|\\n| `\\"open\\"` | Panel transitions closed \u2192 open (including via `sendMessage` or the shopper\'s own click). |\\n| `\\"close\\"` | Panel transitions open \u2192 closed. |\\n\\n### `generateStructuredContent(schema: object, prompt: string): Promise<unknown>`\\n\\nGenerates JSON matching `schema` from `prompt`, grounded in the store\'s live\\ncatalog. Resolves to the generated data object itself. Rejects with `Error`\\non any failure (invalid input, decline, validation failure, rate limit,\\nnetwork). See [structured-content.md](structured-content.md) for the full\\ncontract, schema support, caching, and error semantics.\\n\\nAccepts either a plain JSON Schema object or any object exposing a\\n`.toJSONSchema()` method (e.g. Zod schemas) \u2014 the conversion is called for\\nyou.\\n\\nThrows synchronously (rejects) if `prompt` is not a non-empty string or\\n`schema` is not an object.\\n\\n### `enableNotifications(): Promise<{ ok: boolean }>`\\n\\nOpts this browser into Web Push notifications from the store. Requirements:\\n\\n- Must be called from a user gesture (e.g. a click handler).\\n- The site must host GreatStore\'s `gs.js` service-worker file. By default the\\n  SDK looks for it at `/gs.js`; if it\'s hosted elsewhere, point to it via an\\n  attribute on the embed script tag:\\n  `<script src=\\"\u2026/embed.js\\" data-push-sw-path=\\"/path/to/gs.js\\"></script>`.\\n\\nResolves `{ ok: true }` on success and `{ ok: false }` on any failure\\n(unsupported browser, no service worker hosted, permission denied). It never\\nrejects.\\n\\n## Page tools \u2014 WebMCP (`document.modelContext`)\\n\\nThe recommended way to expose page capabilities to the assistant is the\\nWebMCP standard. The GreatStore assistant discovers every tool registered on\\n`document.modelContext`, re-reading the list on each conversational turn \u2014\\nso tools registered mid-session appear on the next message without a reload.\\n\\n### Availability\\n\\nIf the browser implements WebMCP natively, `document.modelContext` is just\\nthere. Otherwise the SDK installs a spec-tracking polyfill on the page\\nautomatically \u2014 but asynchronously, so at your script\'s first run\\n`document.modelContext` may not exist yet. Two robust patterns:\\n\\n```js\\n// 1. Register once GreatStore is ready (polyfill is in place by then):\\nwindow.GreatStore?.ready.then(() => {\\n  document.modelContext.registerTool(/* \u2026 */);\\n});\\n\\n// 2. Or ship your own polyfill (npm: @mcp-b/webmcp-polyfill) and register\\n//    immediately \u2014 the SDK detects an existing implementation and uses it.\\n```\\n\\n(`navigator.modelContext` is a deprecated alias for the same object; use\\n`document.modelContext` in new code.)\\n\\n### `registerTool(tool, options?)`\\n\\n```ts\\ndocument.modelContext.registerTool(\\n  {\\n    name: string,                 // required, non-empty, unique on the page\\n    description: string,          // required \u2014 how the AI decides when to call it\\n    inputSchema?: object,         // JSON Schema for execute\'s args;\\n                                  // defaults to { type: \\"object\\", properties: {} }\\n    execute(args): Result | Promise<Result>,\\n  },\\n  options?: { signal?: AbortSignal },  // abort to unregister\\n);\\n```\\n\\n- **Result shape**: `execute` returns MCP content blocks \u2014\\n  `{ content: [{ type: \\"text\\", text: \\"\u2026\\" }] }`. For structured data,\\n  `JSON.stringify` it into `text`. Add `isError: true` to mark a handled\\n  failure.\\n- **Errors**: a thrown error or rejected promise is delivered to the\\n  assistant as a *failed* tool call carrying the error message \u2014 the\\n  assistant can explain or adapt. Errors never escape into your page.\\n- **Duplicate names throw.** To replace a tool, abort its registration first.\\n- **Unregistration is `AbortSignal`-driven**: pass `{ signal }` and call\\n  `abort()` when the tool\'s context goes away (SPA navigation, modal close).\\n  A pre-aborted signal skips registration. (A legacy\\n  `unregisterTool(name)` exists but is deprecated in the spec.)\\n- **Treat `args` as untrusted input**: values are AI-generated. Validate\\n  before passing to your own APIs, and never `eval` anything from them.\\n\\nA complete tool, registered once GreatStore is ready:\\n\\n```js\\nwindow.GreatStore?.ready.then(() => {\\n  document.modelContext.registerTool({\\n    name: \\"add_to_cart\\",\\n    description:\\n      \\"Add a product variant to the shopper\'s cart on this site. \\" +\\n      \\"Use when the shopper asks to add, buy, or get a product.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        variantId: { type: \\"string\\" },\\n        quantity: { type: \\"integer\\", minimum: 1 },\\n      },\\n      required: [\\"variantId\\"],\\n    },\\n    async execute({ variantId, quantity }) {\\n      const res = await fetch(\\"/cart/add.js\\", {\\n        method: \\"POST\\",\\n        headers: { \\"Content-Type\\": \\"application/json\\" },\\n        body: JSON.stringify({ id: variantId, quantity: quantity ?? 1 }),\\n      });\\n      if (!res.ok) throw new Error(`Cart add failed (${res.status})`);\\n      const cart = await res.json();\\n      return { content: [{ type: \\"text\\", text: JSON.stringify(cart) }] };\\n    },\\n  });\\n});\\n```\\n\\nReturning the fresh cart state after the mutation lets the assistant confirm\\naccurately. Good tool families: cart (`get_cart`, `add_to_cart`), navigation\\n(`go_to_page`), page state (`get_current_product`, `apply_filters`), UI\\n(`highlight_section`, `scroll_to_reviews`).\\n\\nAnd a context-scoped tool, unregistered via `AbortSignal`:\\n\\n```js\\nconst ac = new AbortController();\\ndocument.modelContext.registerTool(\\n  {\\n    name: \\"get_product_reviews\\",\\n    description: \\"Read the reviews shown on the current product page.\\",\\n    inputSchema: { type: \\"object\\", properties: {} },\\n    execute: () => ({\\n      content: [{ type: \\"text\\", text: JSON.stringify(collectReviews()) }],\\n    }),\\n  },\\n  { signal: ac.signal },\\n);\\n\\n// On SPA route change away from the product page:\\nac.abort();\\n```\\n\\n## URL parameter: `?gs_chat=open`\\n\\nWhen the page URL carries `gs_chat=open`, the panel opens automatically once\\nthe embed mounts. The param is consumed and stripped from the URL via\\n`history.replaceState`, so a manual reload doesn\'t re-open the panel. Use it\\nin campaign links, emails, and post-login redirects.\\n\\n## Shopify login gate\\n\\nStores can enable a per-store \\"log in to chat\\" gate that applies **only to\\nthe embed** (never the store\'s GreatStore storefront). When enabled, the chat\\ninput is replaced with a login prompt until a Shopify customer signal is\\ndetected on the host page (standard Shopify globals/meta tags). The login\\nbutton sends the shopper through Shopify\'s customer login and back with\\n`?gs_chat=open` appended. This is a courtesy UX gate, not a security\\nboundary \u2014 don\'t rely on it to protect anything sensitive.\\n\\n## Troubleshooting\\n\\n| Symptom | Likely cause |\\n|---|---|\\n| Console: `[GreatStore] Chat is unavailable on <origin>\u2026 this domain isn\'t in the store\'s allowed domains` | The page\'s origin isn\'t in the store\'s allowed domains. Add it in store settings. Until then every SDK network call fails. |\\n| Console: `[GreatStore] Embed script must be loaded from <slug>.greatstore.ai/embed.js` | The script was copied/self-hosted instead of loaded from the store\'s embed URL. Always load it from `https://<slug>.greatstore.ai/embed.js`. |\\n| `generateStructuredContent` rejects with a rate-limit message | More than ~20 requests/minute from one visitor. Consolidate calls into fewer, richer schemas. |\\n| Panel won\'t auto-open on mobile after returning to the page | Intentional: the mobile drawer never auto-opens on resume \u2014 it would cover the content the shopper is reading. The transcript is preserved; they\'ll see it when they tap the launcher. |\\n| Tools registered but the assistant doesn\'t use them | Check the `description` \u2014 it\'s the only signal for *when* to call. Also confirm the registration ran (`document.modelContext` exists after `ready`) on the same page the conversation is on. |\\n","references/push-notifications.md":"# Web push re-engagement\\n\\nShoppers who opt in receive browser notifications from the store \u2014 under the\\nmerchant\'s own domain and branding, with the permission prompt shown inline\\non the merchant\'s page. Setup is two pieces: a single file hosted at the site\\nroot, and an opt-in button.\\n\\n## 1. Host `gs.js` at the site root\\n\\nDownload the store\'s loader and serve it at `/gs.js` on the merchant\'s\\ndomain:\\n\\n```\\nhttps://<slug>.greatstore.ai/gs.js   \u2192   https://www.merchant-site.com/gs.js\\n```\\n\\nAlways download it from the **store\'s own subdomain** \u2014 the file is built for\\nthat store; don\'t copy one from elsewhere.\\n\\nThen load it with one tag (replacing the `embed.js` tag \u2014 `gs.js` injects the\\nembed for you and registers itself as the service worker):\\n\\n```html\\n<script src=\\"/gs.js\\"></script>\\n```\\n\\nHosting this file is what enables push. Without it, push is simply off \u2014\\n`enableNotifications()` returns `{ ok: false }` and nothing else changes.\\n\\n### Non-root hosting\\n\\nIf the platform can\'t serve files at the site root (e.g. Shopify themes\\nserve assets under a path), keep the regular `embed.js` tag and point it at\\nwhere the file lives \u2014 the path must be on the merchant\'s own origin:\\n\\n```html\\n<script\\n  src=\\"https://my-store.greatstore.ai/embed.js\\"\\n  data-push-sw-path=\\"/cdn/shop/files/gs.js\\"\\n></script>\\n```\\n\\n## 2. Offer the opt-in from a user gesture\\n\\n```js\\noptInButton.addEventListener(\\"click\\", async () => {\\n  const { ok } = await window.GreatStore.enableNotifications();\\n  optInButton.hidden = ok;          // done \u2014 or quietly keep the button\\n});\\n```\\n\\nRules that make this work well:\\n\\n- **Always call it from a click** \u2014 browsers ignore or penalize permission\\n  prompts that aren\'t user-initiated, and the call is designed for gesture\\n  context.\\n- **Never prompt on page load.** Tie the button to a moment where\\n  notifications have obvious value (\\"Notify me when this is back in stock\\",\\n  post-purchase, after a chat conversation).\\n- `{ ok: false }` covers every failure the same way \u2014 unsupported browser, no\\n  `gs.js` hosted, permission denied. It never rejects, and there\'s no popup\\n  fallback. Design the button so a decline just leaves the page as it was;\\n  don\'t show an error.\\n- The promise resolving `{ ok: true }` means this browser is subscribed.\\n  There\'s nothing else to wire \u2014 notification delivery is handled by\\n  GreatStore.\\n","references/store-admin.md":"# Store administration from the CLI\\n\\nThe `gs` CLI is a full admin surface for a GreatStore store, mirroring the\\nmerchant\'s admin dashboard one-to-one: `gs configure` \u2194 the Configure panel,\\n`gs connectors` \u2194 the Connectors panel, `gs apps` \u2194 the Apps panel. Same\\nfields, same behaviour \u2014 anything you change is what the merchant sees in\\ntheir dashboard.\\n\\nThat makes the CLI the way a coding agent grounds and unblocks its own work:\\nread the store\'s configuration to make better decisions, and make the narrow\\nclass of additive, integration-enabling changes yourself instead of telling\\nthe user to go click through a dashboard.\\n\\n## Setup\\n\\n```\\nnpm install -g @greatstore/cli     # or npx @greatstore/cli <command>\\ngs login                           # one-time browser sign-in (needs a human)\\n```\\n\\nCredentials persist across runs. Admin commands take `--store <slug>`\\ndirectly, or read the nearest `.gsrc` (`{\\"store\\":\\"my-store\\"}`) \u2014 so they work\\nfrom any repo, not just a scaffolded component project. Every read supports\\n`--json` for machine-readable output.\\n\\n## Read freely \u2014 always safe\\n\\nReading store state is never destructive. Do it whenever it would improve a\\ndecision:\\n\\n```\\ngs configure --store my-store --json     # brand config\\ngs connectors --store my-store --json    # MCP connectors feeding the assistant\\ngs connectors health --store my-store    # live-probe them (reports tool counts)\\ngs apps list --store my-store --json     # deployed custom chat components\\n```\\n\\nWhat each read is good for:\\n\\n- **`gs configure`** \u2014 the store\'s `extraOrigins` (is the site you\'re\\n  integrating actually allowlisted? \u2014 see the embed troubleshooting note in\\n  [embed-api.md](embed-api.md)), `theme` (match generated on-page UI to the\\n  brand\'s colors/radius), `storeLink`, CSP host lists, and whether the\\n  Shopify login gate is on.\\n- **`gs connectors`** \u2014 which MCP connectors the assistant has, and whether\\n  the Maker MCP is on. This tells you what the assistant can actually *do*:\\n  check it before building features that lean on catalog data (e.g.\\n  [structured content](structured-content.md) grounding), and before\\n  registering WebMCP page tools that would duplicate a capability a\\n  server-side connector already provides.\\n- **`gs connectors health`** \u2014 a connector being listed doesn\'t mean it\'s\\n  reachable; this probes each one live. Run it when assistant behaviour\\n  suggests a tool isn\'t responding.\\n\\n## Safe to change without asking\\n\\nWhen the task the user gave you requires it, these changes are yours to\\nmake: they\'re additive, easy to undo, and invisible to shoppers.\\n\\n- **`extraOrigins`** \u2014 the origin allowlist for the embed. Installing the\\n  widget on a new site/staging domain? Add that origin yourself instead of\\n  reporting \\"ask the merchant to allowlist it\\".\\n- **`cspScriptHosts` / `cspConnectHosts`** \u2014 hosts the storefront accepts\\n  for scripts/connections. Add a host when a custom chat component\\n  legitimately needs a third-party SDK or API.\\n\\n**List flags replace the stored list \u2014 always read-merge-write.** Fetch the\\ncurrent value, append yours, write the union:\\n\\n```\\ngs configure --store my-store --json\\n# extraOrigins is [\\"https://shop.example.com\\"] \u2192 write both, comma-separated:\\ngs configure set --store my-store \\\\\\n  --extraOrigins \\"https://shop.example.com,https://staging.example.com\\"\\n```\\n\\nNever drop an entry you didn\'t add, and say what you changed (and why) when\\nyou report back to the user.\\n\\n## Ask the merchant first\\n\\nEverything below is shopper-visible or changes what the live assistant can\\ndo for every shopper. Propose it, don\'t do it unprompted:\\n\\n- **Brand-visible config** \u2014 `displayName`, `assistantName`, `salesGuide`,\\n  `storeLink`, `theme`, `shopifyLoginGate`, and asset uploads\\n  (`gs configure upload|clear icon|logoLight|logoDark`).\\n- **Connector mutations** \u2014 `gs connectors add|remove|enable|disable` and\\n  `gs connectors maker on|off`. (`add` probes the connector for tool\\n  discovery before saving and refuses if it doesn\'t answer; `--force`\\n  overrides. Still: adding capabilities to the merchant\'s assistant is the\\n  merchant\'s call.)\\n- **Anything that clears** \u2014 passing `\\"\\"` to empty a field, removing list\\n  entries, `clear`ing assets.\\n\\nWhen the user has *explicitly asked* for one of these (\\"set the assistant\'s\\nname to Voyager\\", \\"connect this MCP server\\"), that\'s the go-ahead \u2014 do it\\nand confirm the result with a read.\\n\\n## Command reference\\n\\n```\\ngs configure [--json]                      show configuration\\ngs configure set --<field> <value>         displayName, assistantName,\\n                                           salesGuide (--salesGuideFile <path>),\\n                                           storeLink, extraOrigins a,b,\\n                                           shopifyLoginGate true|false,\\n                                           theme \'<json>\' (--themeFile <path>),\\n                                           cspScriptHosts a,b, cspConnectHosts a,b\\n                                           (\\"\\" clears a field)\\ngs configure upload <kind> <file>          icon | logoLight | logoDark (.png/.jpg/.webp)\\ngs configure clear <kind>                  remove an uploaded asset\\n\\ngs connectors [--json]                     list Maker toggle + custom connectors\\ngs connectors add <name> --url <url>       [--token <t>] [--profileUrl <u>]\\n                                           [--disabled] [--force]\\ngs connectors remove <name|id>\\ngs connectors enable|disable <name|id>\\ngs connectors maker on|off\\ngs connectors health [<name|id>] [--json]\\n\\ngs apps <init|build|list|pull|push|publish|unpublish|delete>\\n                                           see chat-components.md for the workflow\\n```\\n","references/structured-content.md":"# `generateStructuredContent` deep dive\\n\\nAI-generated, catalog-grounded JSON for UI you render yourself \u2014 the chat\\npanel is not involved.\\n\\n```js\\nconst data = await window.GreatStore.generateStructuredContent(schema, prompt);\\n```\\n\\n- `schema` \u2014 a JSON Schema describing the output (or a Zod schema exposing\\n  `.toJSONSchema()`).\\n- `prompt` \u2014 what to generate.\\n- Resolves to **the generated JSON object itself**, matching the schema.\\n  Rejects with an `Error` on any failure.\\n\\nCode samples here are framework-free reference implementations \u2014 re-express\\nthem in the host repo\'s framework (React, Vue, Shopify Liquid, \u2026) rather\\nthan retrofitting them as-is.\\n\\n## The rules that make it work well\\n\\nEach is unpacked in the sections below; this is the checklist.\\n\\n1. **Top level must be an object.** Want a list? Wrap it:\\n   `{ type: \\"object\\", properties: { items: { type: \\"array\\", \u2026 } }, required: [\\"items\\"] }`.\\n2. **Steer with the prompt, not schema `description`s** \u2014 free-text schema\\n   fields are stripped before the AI sees them. Use self-explanatory\\n   property names (`benefitHeadline`, not `text1`).\\n3. **Only `require` what\'s guaranteed.** `required` is strictly enforced; if\\n   the catalog can\'t ground a required field the whole call can fail. Require\\n   structural fields, keep per-product details (image URLs, prices) optional,\\n   and make rendering tolerate missing values.\\n4. **Point, don\'t paste.** GreatStore researches the store\'s live catalog on\\n   its own \u2014 name the entity (`` `\u2026the product \\"${productName}\\" (SKU ${sku})` ``)\\n   and let it look the facts up. Don\'t fetch specs/prices/descriptions\\n   yourself and paste them into the prompt. The one thing it *can\'t* see is\\n   your page, so page-only context (which page the shopper is on, what the\\n   section is for) does belong in the prompt.\\n5. **Research is bounded by the store\'s connectors \u2014 validate before you\\n   build.** The AI can only look up what the store\'s MCP connectors actually\\n   provide. Ask for something outside them \u2014 currency conversion, live\\n   shipping rates, review data the store never wired up \u2014 and it has nothing\\n   to ground on, so it will decline, omit\u2026 or hallucinate. Before writing a\\n   prompt or schema that depends on a data capability, run `gs connectors`\\n   (and `gs connectors health`, [store-admin.md](store-admin.md)) and confirm\\n   a connector for it exists; if it doesn\'t, don\'t ask for it.\\n6. **Responses are cached** for up to ~24h per page + prompt + schema \u2014\\n   shared across anonymous visitors, per-shopper for identified ones. Keep\\n   prompts deterministic per page \u2014 no timestamps, random values, or\\n   per-visitor data (GreatStore already knows who the shopper is; see below).\\n7. **Progressive enhancement, always.** Generate after the page renders into\\n   a hidden container, reveal on success, leave the fallback on error. Render\\n   generated strings via `textContent`, never `innerHTML`.\\n8. **One rich call beats many small ones** \u2014 there\'s a per-visitor rate limit\\n   (~20 requests/minute); fetch multiple surfaces with one combined schema.\\n\\n## What actually happens\\n\\n1. The SDK posts your schema + prompt to the store\'s GreatStore endpoint,\\n   along with the current **page URL and page title** (sent automatically \u2014\\n   you don\'t pass them, and you can\'t override them).\\n2. GreatStore first **researches**: it looks up real data from the store\'s\\n   live catalog (products, prices, availability, store info) using read-only\\n   lookups. The page URL/title serve as hints about which product or category\\n   to look up \u2014 they are *not* treated as a source of product data, and the\\n   page\'s DOM is never read. Research happens on GreatStore\'s side \u2014 your\\n   prompt only needs to *point* it at the right SKU, product, or collection,\\n   not carry the material. Its reach is exactly the store\'s MCP connectors:\\n   validate with `gs connectors` ([store-admin.md](store-admin.md)) that a\\n   connector for the data you want actually exists before you build on it \u2014\\n   research can\'t exceed the wired-up connectors, and prompts that assume\\n   otherwise invite hallucinated filler.\\n3. The AI then fills your schema from the researched data, under a strict\\n   grounding contract: it must not invent product names, prices, images, IDs,\\n   or descriptions. Fields it can\'t ground are omitted or `null`. For an\\n   identified shopper this step also sees their shopper profile \u2014 the same\\n   identity the chat assistant has \u2014 so the output can be subtly personalized\\n   without you passing anything about the visitor.\\n4. The output is validated against your schema (with internal retries) before\\n   being returned and cached.\\n\\nGreatStore already knows who\'s reading: identity rides the request the same\\nway it does for chat, and responses for identified shoppers are cached just\\nfor them (anonymous visitors share one entry). The practical consequence:\\nnever put shopper data in the prompt \u2014 it\'s redundant, and it poisons the\\ncache key.\\n\\n## Schema support\\n\\nTop level **must describe an object**: `type: \\"object\\"` (or a bare\\n`properties` / `anyOf`). To get a list, wrap it in an object property.\\n\\nSupported keywords (anything else is tolerated but ignored):\\n\\n- Types: `object`, `array`, `string`, `number`, `integer`, `boolean`, `null`\\n- Structure: `properties`, `required`, `items`, `additionalProperties`\\n- Choice: `enum`, `const`, `anyOf`, `nullable`\\n- Constraints: `minimum`, `maximum`, `minLength`, `maxLength`, `minItems`,\\n  `maxItems`, `pattern`, `format`, `default`\\n\\nValidation of the output is real: `required` is enforced, `enum`/`const`\\nmust match, numeric and length bounds are checked, and\\n`additionalProperties: false` rejects extra keys. Constraints are therefore a\\n*tool* \u2014 `maxItems: 4` reliably caps a list, `enum` reliably restricts a\\nfield \u2014 but every constraint is also a way for generation to fail, so apply\\nthem only where you\'d rather have no content than non-conforming content.\\n\\nZod schemas (or anything with a `.toJSONSchema()` method) are accepted and\\nconverted automatically.\\n\\n### Free-text schema fields are stripped\\n\\n`description`, `title`, and `example` are removed from the schema before the\\nAI sees it (they\'re a prompt-injection surface, so they\'re filtered\\nserver-side). Consequences:\\n\\n- Schema descriptions **cannot** steer generation. All steering lives in the\\n  prompt string.\\n- Property *names* are the only in-schema signal of intent \u2014 make them\\n  self-documenting: `ctaLabel`, `warmthRating`, `priceJustification`.\\n\\n## Prompting guide\\n\\nThe prompt is the entire instruction channel. A good prompt states, in order:\\n\\n1. **Context** \u2014 what page/situation the shopper is in, naming the entity so\\n   research targets the right thing (the AI can\'t see your DOM, so identify\\n   it explicitly):\\n   `The shopper is viewing the product \\"Aurora Down Parka\\" (SKU AUR-021) on its product page.`\\n2. **Task** \u2014 what to generate, mapped loosely onto your schema\'s fields:\\n   `Write a heading and 3 reasons to love it; each reason has a short title and one supporting sentence.`\\n3. **Grounding expectations** \u2014 what store data to draw on:\\n   `Base every claim on the product\'s real materials, features, and price.`\\n4. **Voice** \u2014 tone and constraints:\\n   `Warm and concrete. No exclamation marks, no generic marketing filler.`\\n\\nNote what\'s *not* in that prompt: no pasted specs, prices, or descriptions.\\nPointing at the SKU is enough \u2014 GreatStore researches the rest itself, from\\ndata that\'s live rather than whatever was true when you wrote the prompt.\\n\\nAnti-patterns:\\n\\n- **Pasting researched material into the prompt** (specs, prices,\\n  descriptions you fetched from your platform\'s API). GreatStore researches\\n  the live catalog itself \u2014 point it at the SKU/product/collection and let\\n  it look things up. Pasted facts go stale, bloat the cache key, and compete\\n  with the fresher data research returns.\\n- **Per-visitor or per-moment data in the prompt** (names, cart contents,\\n  timestamps, `Math.random()`): destroys caching, so every visitor pays full\\n  generation latency and the store pays for every call \u2014 and it\'s redundant,\\n  because GreatStore already knows the shopper and personalizes for\\n  identified ones server-side. If you need per-shopper *interaction*, that\'s\\n  what `sendMessage` and the chat panel are for.\\n- **Asking for data no connector provides** (\\"convert the price to EUR\\",\\n  \\"estimate delivery to the shopper\'s city\\"): research can\'t exceed the\\n  store\'s MCP connectors, and the AI may hallucinate plausible-looking\\n  values rather than leave the field empty. Validate first \u2014 `gs connectors`\\n  shows what\'s wired up ([store-admin.md](store-admin.md)); if there\'s no\\n  connector for it, don\'t ask for it.\\n- **Asking it to read the page** (\\"summarize the reviews shown below\\") \u2014 it\\n  can\'t. Page-only data (review snippets, UGC, things that exist nowhere but\\n  the DOM) is the one kind worth inlining \u2014 keep it stable per page so\\n  caching still works.\\n- **Asking for minute-fresh operational data** (exact live stock counts,\\n  delivery countdowns). Even when a connector could answer, responses cache\\n  for up to ~24h \u2014 display operational data from your own platform APIs and\\n  use GreatStore for *editorial intelligence over the catalog*.\\n- **Burying instructions in schema descriptions** \u2014 stripped, see above.\\n\\n## Caching: design for it\\n\\nResponses are cached server-side for up to **24 hours**, keyed by the\\ncombination of page URL + page title + prompt + schema. Anonymous visitors\\nshare one entry per key; identified shoppers each get their own (their\\noutput may be personalized, so it\'s only ever served back to them).\\n(Tracking query params like `utm_*`/`gclid` and the URL fragment are\\nignored, so ad-tagged visits share the campaign-free page\'s cache entry.\\nMeaningful params like `?product=123` are part of the key.)\\n\\nPractical consequences:\\n\\n- **The first render pays, repeats fly.** Expect a few seconds on a cache\\n  miss and near-instant responses after \u2014 shared across all anonymous\\n  traffic, per-shopper for identified traffic (the research underneath is\\n  cached briefly and shared, so even those misses are cheaper than cold).\\n  Design loading states for the miss case.\\n- **Same call on different pages = different content**, automatically \u2014 the\\n  page URL is in the key and in the AI\'s hints. A single site-wide snippet\\n  with a constant prompt yields per-page content for free.\\n- **Content refreshes roughly daily.** Don\'t build experiences that assume\\n  minute-level freshness.\\n- **To force different content, change the prompt or schema** (e.g. a\\n  campaign variant string that changes weekly \u2014 deliberate, low-cardinality\\n  variation is fine; per-visitor cardinality is not).\\n\\nThe catalog research underneath is also cached briefly, so several distinct\\nsurfaces on the same page (different prompts/schemas) stay cheap even on\\ncold cache.\\n\\n## Errors and how to handle them\\n\\nThe promise rejects with `new Error(message)`. The message is\\ndeveloper-facing \u2014 never render it to shoppers. Cases:\\n\\n| Case | Message you\'ll see | Retry? |\\n|---|---|---|\\n| Bad input (empty prompt, non-object schema) | thrown immediately by the SDK | Fix the call |\\n| Invalid schema shape | `Invalid schema: \u2026` | Fix the schema |\\n| AI declined the request | `The assistant declined to generate content for this request.` | No \u2014 permanent for that prompt/schema. Rework the prompt. |\\n| Output couldn\'t satisfy the schema | `Failed to produce valid structured content` | No \u2014 usually `required`/constraints demand data the catalog lacks. Loosen the schema. |\\n| Rate limit (~20/min per visitor) | rate-limit message | Later \u2014 and consolidate calls |\\n| Network / server | varies | Next page load |\\n\\nThe uniform shopper-facing strategy: render into a hidden-by-default\\ncontainer, reveal on success, leave hidden (or show your static fallback) on\\nany rejection. One `try/catch`, no case analysis needed unless you\'re\\nlogging.\\n\\n## Performance pattern\\n\\nFire generation as early as possible without blocking render \u2014 top of your\\ndeferred script, before other work:\\n\\n```js\\nconst highlightsPromise = window.GreatStore?.generateStructuredContent\\n  ? window.GreatStore.generateStructuredContent(schema, prompt).catch(() => null)\\n  : Promise.resolve(null);\\n\\n// \u2026rest of page setup\u2026\\n\\nconst data = await highlightsPromise;\\nif (data) renderHighlights(data);\\n```\\n\\nThe `.catch(() => null)` attached immediately avoids unhandled-rejection\\nnoise while keeping a single render path.\\n\\nFor multiple surfaces on one page, prefer **one call with a combined\\nschema** over parallel calls \u2014 it\'s one research pass, one cache entry, and\\nno rate-limit pressure:\\n\\n```js\\nconst schema = {\\n  type: \\"object\\",\\n  properties: {\\n    highlights: { /* \u2026 */ },\\n    faq:        { /* \u2026 */ },\\n    crossSell:  { /* \u2026 */ },\\n  },\\n  required: [\\"highlights\\"],\\n};\\n```\\n"}') : readTreeFromDisk(new URL("../../skill/", import.meta.url));
+  if (!cache2["SKILL.md"]) {
+    throw new Error("internal: agent skill tree is missing SKILL.md");
   }
-  return {
-    manifestHash,
-    sourceHash: hashFile(path3.join(componentDir, "component.tsx"))
-  };
+  return cache2;
 }
-function readSyncState(componentDir) {
-  const file = path3.join(componentDir, SYNC_FILE);
-  if (!fs3.existsSync(file)) return null;
-  try {
-    const parsed = JSON.parse(fs3.readFileSync(file, "utf8"));
-    if (typeof parsed.version === "number" && typeof parsed.manifestHash === "string" && typeof parsed.sourceHash === "string") {
-      return {
-        version: parsed.version,
-        manifestHash: parsed.manifestHash,
-        sourceHash: parsed.sourceHash
-      };
-    }
-    return null;
-  } catch {
-    return null;
+
+// src/commands/skill.ts
+function skillCommand(args) {
+  const global = flagBool(args.flags, "global");
+  const dirFlag = flagString(args.flags, "dir");
+  if (global && dirFlag !== void 0) {
+    throw new Error("Pass either --global or --dir <path>, not both.");
   }
-}
-function writeSyncState(componentDir, state) {
-  fs3.writeFileSync(
-    path3.join(componentDir, SYNC_FILE),
-    JSON.stringify(state, null, 2) + "\n"
+  const skillsDir = dirFlag !== void 0 ? path3.resolve(dirFlag) : global ? path3.join(os2.homedir(), ".claude", "skills") : path3.resolve(".claude", "skills");
+  const dest = path3.join(skillsDir, SKILL_DIR_NAME);
+  const existed = fs3.existsSync(path3.join(dest, "SKILL.md"));
+  for (const [rel, content] of Object.entries(loadSkill())) {
+    const full = path3.join(dest, ...rel.split("/"));
+    fs3.mkdirSync(path3.dirname(full), { recursive: true });
+    fs3.writeFileSync(full, content);
+  }
+  process.stdout.write(
+    [
+      `${existed ? "Updated" : "Installed"} the GreatStore agent skill at ${displayPath(dest)}.`,
+      "",
+      "Your coding agent picks it up automatically. Try asking it:",
+      `  "Add an AI-powered gift finder to my product page with GreatStore."`,
+      ""
+    ].join("\n")
   );
 }
-function hasLocalChanges(componentDir, state) {
-  const hashes = safeComputeHashes(componentDir);
-  if (!hashes) return false;
-  if (state === null) return true;
-  if (hashes.manifestHash !== state.manifestHash) return true;
-  const localSource = hashes.sourceHash ?? "";
-  const storedSource = state.sourceHash ?? "";
-  return localSource !== storedSource;
-}
-function safeComputeHashes(componentDir) {
-  try {
-    return computeComponentHashes(componentDir);
-  } catch {
-    return null;
+function displayPath(dest) {
+  const home = os2.homedir();
+  if (dest.startsWith(home + path3.sep)) {
+    return `~${dest.slice(home.length)}`;
   }
+  const rel = path3.relative(process.cwd(), dest);
+  return rel && !rel.startsWith("..") ? rel : dest;
 }
 
-// src/commands/pull.ts
-async function pullCommand(args) {
-  const slug = requireProjectStore();
-  const force = flagBool(args.flags, "force");
-  const targets = args.positional;
-  const root = process.cwd();
-  if (targets.length === 0 || targets.length === 1 && targets[0] === "*") {
-    return pullAll({ slug, root, args, force });
+// src/commands/apps/init.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
+var NAME_REGEX = /^[a-z][a-z0-9_]*$/;
+function initCommand(args) {
+  const name = args.positional[0];
+  if (name !== void 0 && !NAME_REGEX.test(name)) {
+    throw new Error(`Invalid component name: "${name}" (must match ${NAME_REGEX}).`);
   }
-  if (targets.length > 1 && flagString(args.flags, "version")) {
+  const force = flagBool(args.flags, "force");
+  const storeFlag = flagString(args.flags, "store");
+  const outRel = flagString(args.flags, "out") ?? ".";
+  const root = path4.resolve(outRel);
+  const rootExisted = hasRootScaffold(root);
+  if (rootExisted) {
+    if (storeFlag !== void 0) {
+      throw new Error(
+        `Project at ${root} is already pinned to a store via .gsrc. Drop --store; a project folder ships to exactly one store.`
+      );
+    }
+  } else if (storeFlag === void 0) {
+    const example = name ? `gs apps init ${name} --store <slug>` : `gs apps init --store <slug>`;
     throw new Error(
-      "--version is per-component; pass it together with a single `gs pull <name>`."
+      `--store <slug> is required when scaffolding a new project root. Run \`${example}\`.`
     );
   }
-  ensureComponentsDir(root);
-  const revisionQuery = buildRevisionQuery(args);
-  const outcomes = [];
-  for (const name of targets) {
-    const outcome = await pullOne({
-      slug,
-      componentDir: path4.join(root, "components", name),
-      name,
-      revisionQuery,
-      force
-    });
-    outcomes.push(outcome);
-    printOutcome(outcome, force);
-  }
-  if (outcomes.length > 1) printPullSummary(outcomes, slug);
-  if (outcomes.some((o) => o.status === "failed")) process.exitCode = 1;
-}
-async function pullAll(opts) {
-  const { slug, root, args, force } = opts;
-  if (flagString(args.flags, "version")) {
-    throw new Error(
-      "--version is per-component; pass it together with `gs pull <name>`."
+  const writtenRootFiles = ensureRoot(root, rootExisted, force, { store: storeFlag });
+  if (!name) {
+    const lines = [];
+    if (rootExisted) {
+      lines.push(`Updated GreatStore project root in ${root}.`);
+      if (writtenRootFiles.length > 0) {
+        lines.push("", `Added: ${writtenRootFiles.join(", ")}`);
+      } else {
+        lines.push("", "Already up to date \u2014 nothing to add.");
+      }
+    } else {
+      lines.push(`Scaffolded GreatStore project root in ${root}.`);
+    }
+    lines.push(
+      "",
+      "Next steps:",
+      `  cd ${path4.relative(process.cwd(), root) || "."}`,
+      "  npm install",
+      "  gs apps init <component_name>     # add your first component",
+      ""
     );
-  }
-  ensureComponentsDir(root);
-  const revisionQuery = buildRevisionQuery(args);
-  const listUrl = `${apiBaseFor(slug)}/api/builder/components`;
-  const list = await request(listUrl);
-  if (list.components.length === 0) {
-    process.stdout.write(`(no components in ${slug})
-`);
+    process.stdout.write(lines.join("\n"));
     return;
   }
-  const outcomes = [];
-  for (const entry of list.components) {
-    const componentDir = path4.join(root, "components", entry.name);
-    const outcome = await pullOne({
-      slug,
-      componentDir,
-      name: entry.name,
-      revisionQuery,
-      force
-    });
-    outcomes.push(outcome);
-    printOutcome(outcome, force);
-  }
-  printPullSummary(outcomes, slug);
-  if (outcomes.some((o) => o.status === "failed")) process.exitCode = 1;
-}
-function printPullSummary(outcomes, slug) {
-  const pulled = outcomes.filter((o) => o.status === "pulled").length;
-  const skipped = outcomes.filter((o) => o.status === "skipped").length;
-  const failed = outcomes.filter((o) => o.status === "failed").length;
-  const summary = [`${pulled} pulled`, `${skipped} skipped`];
-  if (failed > 0) summary.push(`${failed} failed`);
+  const componentDir = path4.join(root, "components", name);
+  ensureComponent(componentDir, name, force);
+  const projectLabel = path4.relative(process.cwd(), root) || ".";
   process.stdout.write(
-    `
-${summary.join(", ")} (of ${outcomes.length}) \u2190 ${slug}
-`
+    [
+      `Added component "${name}" at components/${name}/.`,
+      ...rootExisted && writtenRootFiles.length > 0 ? ["", `Also added to the project root: ${writtenRootFiles.join(", ")}`] : [],
+      "",
+      "Next steps:",
+      ...rootExisted ? [] : [`  cd ${projectLabel}`, "  npm install"],
+      `  # edit components/${name}/component.tsx and manifest.json`,
+      "  gs apps build",
+      "  gs apps push",
+      ""
+    ].join("\n")
   );
 }
-async function pullOne(opts) {
-  const { slug, componentDir, name, revisionQuery, force } = opts;
-  if (!force && fs4.existsSync(componentDir)) {
-    const sync = readSyncState(componentDir);
-    if (hasLocalChanges(componentDir, sync)) {
-      return {
+function hasRootScaffold(dir) {
+  return fs4.existsSync(path4.join(dir, "package.json")) && fs4.existsSync(path4.join(dir, ".gsrc"));
+}
+function ensureRoot(root, rootExisted, force, opts) {
+  fs4.mkdirSync(root, { recursive: true });
+  if (!rootExisted && !force) {
+    const entries = fs4.readdirSync(root).filter((e) => e !== ".gsrc");
+    if (entries.length > 0) {
+      throw new Error(
+        `Refusing to scaffold project root into non-empty directory ${root}. Pass --force to override.`
+      );
+    }
+  }
+  const files = rootExisted ? existingRootFiles() : rootFiles({ store: opts.store });
+  const written = writeRootFiles(root, files, force);
+  fs4.mkdirSync(path4.join(root, "components"), { recursive: true });
+  return written;
+}
+function writeRootFiles(root, files, force) {
+  const written = [];
+  for (const [relPath, content] of files) {
+    const full = path4.join(root, relPath);
+    fs4.mkdirSync(path4.dirname(full), { recursive: true });
+    if (force || !fs4.existsSync(full)) {
+      fs4.writeFileSync(full, content);
+      written.push(relPath);
+    }
+  }
+  for (const link of ["CLAUDE.md", "GEMINI.md"]) {
+    const linkPath = path4.join(root, link);
+    if (force && pathExists(linkPath)) fs4.rmSync(linkPath);
+    if (!pathExists(linkPath)) {
+      fs4.symlinkSync("AGENTS.md", linkPath);
+      written.push(link);
+    }
+  }
+  return written;
+}
+function pathExists(p) {
+  try {
+    fs4.lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function ensureComponent(componentDir, name, force) {
+  if (fs4.existsSync(componentDir) && !force) {
+    const entries = fs4.readdirSync(componentDir);
+    if (entries.length > 0) {
+      throw new Error(
+        `Refusing to overwrite existing components/${name}/. Pass --force to override.`
+      );
+    }
+  }
+  fs4.mkdirSync(componentDir, { recursive: true });
+  for (const [relPath, content] of componentFiles(name)) {
+    fs4.writeFileSync(path4.join(componentDir, relPath), content);
+  }
+}
+function templateFiles(prefix, vars, exclude = /* @__PURE__ */ new Set()) {
+  const tree = loadTemplate();
+  return Object.entries(tree).filter(([rel]) => rel.startsWith(prefix)).map(([rel, content]) => [rel.slice(prefix.length), content]).filter(([dest]) => !exclude.has(dest)).map(([dest, content]) => [dest, applyTemplate(content, vars)]);
+}
+function rootFiles(opts) {
+  if (!opts.store) {
+    throw new Error("internal: rootFiles called without a store slug");
+  }
+  return templateFiles("root/", { store: opts.store });
+}
+function existingRootFiles() {
+  return templateFiles("root/", {}, /* @__PURE__ */ new Set([".gsrc"]));
+}
+function componentFiles(name) {
+  return templateFiles("component/", {
+    name,
+    pascalName: pascal(name),
+    displayName: defaultDisplayName(name)
+  });
+}
+function defaultDisplayName(name) {
+  const words = name.split("_").filter(Boolean);
+  if (words.length === 0) return name;
+  const first = words[0];
+  return first.charAt(0).toUpperCase() + first.slice(1) + (words.length > 1 ? " " + words.slice(1).join(" ") : "");
+}
+function pascal(name) {
+  return name.split(/[_-]/).filter(Boolean).map((part) => part[0]?.toUpperCase() + part.slice(1)).join("");
+}
+
+// src/commands/apps/build.ts
+import * as fs5 from "fs";
+import * as path5 from "path";
+import { createRequire } from "module";
+var COMPONENTS_DIR = "components";
+async function buildCommand(args) {
+  const root = process.cwd();
+  if (!fs5.existsSync(path5.join(root, "package.json")) || !fs5.existsSync(path5.join(root, COMPONENTS_DIR))) {
+    throw new Error(
+      `\`gs apps build\` must run from a project root (contains \`package.json\` and \`${COMPONENTS_DIR}/\`). Current dir: ${root}`
+    );
+  }
+  const components = listComponents(root);
+  if (components.length === 0) {
+    process.stdout.write(
+      `(no components in ./${COMPONENTS_DIR} \u2014 run \`gs apps init <name>\` to add one)
+`
+    );
+    return;
+  }
+  const target = args.positional[0];
+  const queue = target ? components.filter((c) => c === target) : components;
+  if (target && queue.length === 0) {
+    throw new Error(`No component named "${target}" in ./${COMPONENTS_DIR}`);
+  }
+  const { build, reactPlugin, transformWithEsbuild } = await loadVite(root);
+  for (const name of queue) {
+    const dir = path5.join(root, COMPONENTS_DIR, name);
+    const bundlePath = path5.join(dir, "bundle.js");
+    await build({
+      plugins: [reactPlugin()],
+      logLevel: "warn",
+      build: {
+        lib: {
+          entry: path5.join(dir, "component.tsx"),
+          formats: ["es"],
+          fileName: () => "bundle.js"
+        },
+        outDir: dir,
+        emptyOutDir: false,
+        rollupOptions: {
+          external: ["react", "react-dom", "react/jsx-runtime"],
+          output: {
+            entryFileNames: "bundle.js",
+            paths: {
+              react: "/assets/remote-components/_runtime.js",
+              "react-dom": "/assets/remote-components/_runtime.js",
+              "react/jsx-runtime": "/assets/remote-components/_runtime.js"
+            }
+          }
+        },
+        minify: true,
+        sourcemap: false
+      }
+    });
+    const beforeBytes = fs5.statSync(bundlePath).size;
+    const src = fs5.readFileSync(bundlePath, "utf8");
+    const { code } = await transformWithEsbuild(src, bundlePath, {
+      minify: true,
+      legalComments: "none",
+      target: "esnext",
+      loader: "js",
+      sourcemap: false
+    });
+    fs5.writeFileSync(bundlePath, code);
+    const afterBytes = Buffer.byteLength(code, "utf8");
+    process.stdout.write(
+      `built ${COMPONENTS_DIR}/${name}/bundle.js (${formatBytes(afterBytes)}, ${pctSmaller(beforeBytes, afterBytes)} smaller)
+`
+    );
+  }
+  process.stdout.write(
+    `
+Built locally \u2014 nothing uploaded yet. Next: \`gs apps push\` to upload, then \`gs apps publish <name>\` to ship. If you're an AI assistant: confirm with the user before running these (or just run them if they already asked you to ship end-to-end).
+`
+  );
+}
+function listComponents(root) {
+  const dir = path5.join(root, COMPONENTS_DIR);
+  return fs5.readdirSync(dir).filter((entry) => {
+    const candidate = path5.join(dir, entry);
+    return fs5.statSync(candidate).isDirectory() && fs5.existsSync(path5.join(candidate, "component.tsx"));
+  }).sort();
+}
+function formatBytes(n) {
+  if (n < 1024) return `${n} B`;
+  return `${(n / 1024).toFixed(1)} KB`;
+}
+function pctSmaller(before, after) {
+  if (before === 0) return "0%";
+  return `${Math.round((1 - after / before) * 100)}%`;
+}
+async function loadVite(root) {
+  const localRequire = createRequire(path5.join(root, "package.json"));
+  const vitePath = resolveEsmEntry(localRequire, "vite");
+  if (!vitePath) {
+    throw new Error(
+      "Cannot find `vite` in this project. Run `npm install` first."
+    );
+  }
+  const reactPath = resolveEsmEntry(localRequire, "@vitejs/plugin-react");
+  if (!reactPath) {
+    throw new Error(
+      "Cannot find `@vitejs/plugin-react` in this project. Run `npm install` first."
+    );
+  }
+  const viteMod = await import(vitePath);
+  const build = viteMod.build ?? viteMod.default?.build;
+  if (typeof build !== "function") {
+    throw new Error(
+      `Loaded \`vite\` from ${vitePath} but couldn't find its \`build()\` export. Reinstall vite (>= 5) and retry.`
+    );
+  }
+  const transformWithEsbuild = viteMod.transformWithEsbuild ?? viteMod.default?.transformWithEsbuild;
+  if (typeof transformWithEsbuild !== "function") {
+    throw new Error(
+      `Loaded \`vite\` from ${vitePath} but couldn't find its \`transformWithEsbuild()\` export. Reinstall vite (>= 5) and retry.`
+    );
+  }
+  const reactMod = await import(reactPath);
+  const reactPlugin = reactMod.default ?? reactMod;
+  if (typeof reactPlugin !== "function") {
+    throw new Error(
+      `Loaded \`@vitejs/plugin-react\` from ${reactPath} but couldn't find its default export.`
+    );
+  }
+  return {
+    build,
+    reactPlugin,
+    transformWithEsbuild
+  };
+}
+function resolveEsmEntry(req, specifier) {
+  let anchor;
+  try {
+    anchor = req.resolve(specifier);
+  } catch {
+    return null;
+  }
+  const pkgJsonPath = findOwningPackageJson(anchor, specifier);
+  if (!pkgJsonPath) return null;
+  const pkgDir = path5.dirname(pkgJsonPath);
+  let pkg;
+  try {
+    pkg = JSON.parse(fs5.readFileSync(pkgJsonPath, "utf8"));
+  } catch {
+    return null;
+  }
+  const fromExports = pickImportEntry(pkg.exports);
+  const entry = fromExports ?? (typeof pkg.module === "string" ? pkg.module : null) ?? (typeof pkg.main === "string" ? pkg.main : null);
+  if (!entry) return null;
+  return path5.resolve(pkgDir, entry);
+}
+function findOwningPackageJson(start, specifier) {
+  let dir = path5.dirname(start);
+  while (true) {
+    const candidate = path5.join(dir, "package.json");
+    if (fs5.existsSync(candidate)) {
+      try {
+        const parsed = JSON.parse(fs5.readFileSync(candidate, "utf8"));
+        if (parsed.name === specifier) return candidate;
+      } catch {
+      }
+    }
+    const parent = path5.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function pickImportEntry(exports) {
+  if (typeof exports !== "object" || exports === null) return null;
+  const map = exports;
+  const dot = map["."] ?? exports;
+  if (typeof dot !== "object" || dot === null) return null;
+  const imp = dot.import;
+  if (typeof imp === "string") return imp;
+  if (typeof imp === "object" && imp !== null) {
+    const def = imp.default;
+    if (typeof def === "string") return def;
+  }
+  return null;
+}
+
+// src/commands/apps/list.ts
+async function listCommand(args) {
+  const slug = requireProjectStore();
+  const url = `${apiBaseFor(slug)}/api/builder/components`;
+  const data = await request(url);
+  if (flagBool(args.flags, "json")) {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+    return;
+  }
+  if (data.components.length === 0) {
+    process.stdout.write(`(no components in ${slug})
+`);
+    return;
+  }
+  const rows = data.components.map((c) => ({
+    name: c.name,
+    draft: c.draft ? `v${c.draft.version}` : "\u2014",
+    live: c.live ? `v${c.live.version}` : "\u2014",
+    updated: c.live?.updatedAt ?? c.draft?.updatedAt ?? "",
+    permalink: c.permalink ?? ""
+  }));
+  const widths = {
+    name: Math.max(4, ...rows.map((r) => r.name.length)),
+    draft: Math.max(5, ...rows.map((r) => r.draft.length)),
+    live: Math.max(4, ...rows.map((r) => r.live.length)),
+    updated: Math.max(7, ...rows.map((r) => r.updated.length))
+  };
+  const header = `${pad("NAME", widths.name)}  ${pad("DRAFT", widths.draft)}  ${pad("LIVE", widths.live)}  ${pad("UPDATED", widths.updated)}  LINK`;
+  process.stdout.write(header + "\n");
+  for (const r of rows) {
+    process.stdout.write(
+      `${pad(r.name, widths.name)}  ${pad(r.draft, widths.draft)}  ${pad(r.live, widths.live)}  ${pad(r.updated, widths.updated)}  ${r.permalink}
+`
+    );
+  }
+}
+function pad(s, width) {
+  return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+
+// src/commands/apps/pull.ts
+import * as fs7 from "fs";
+import * as path7 from "path";
+
+// src/sync.ts
+import * as crypto2 from "crypto";
+import * as fs6 from "fs";
+import * as path6 from "path";
+var SYNC_FILE = ".gssync.json";
+function hashString(text) {
+  return crypto2.createHash("sha256").update(text).digest("hex");
+}
+function hashFile(filePath) {
+  if (!fs6.existsSync(filePath)) return null;
+  return hashString(fs6.readFileSync(filePath, "utf8"));
+}
+function computeComponentHashes(componentDir) {
+  const manifestHash = hashFile(path6.join(componentDir, "manifest.json"));
+  if (manifestHash === null) {
+    throw new Error(`Missing manifest.json in ${componentDir}`);
+  }
+  return {
+    manifestHash,
+    sourceHash: hashFile(path6.join(componentDir, "component.tsx"))
+  };
+}
+function readSyncState(componentDir) {
+  const file = path6.join(componentDir, SYNC_FILE);
+  if (!fs6.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs6.readFileSync(file, "utf8"));
+    if (typeof parsed.version === "number" && typeof parsed.manifestHash === "string" && typeof parsed.sourceHash === "string") {
+      return {
+        version: parsed.version,
+        manifestHash: parsed.manifestHash,
+        sourceHash: parsed.sourceHash
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function writeSyncState(componentDir, state) {
+  fs6.writeFileSync(
+    path6.join(componentDir, SYNC_FILE),
+    JSON.stringify(state, null, 2) + "\n"
+  );
+}
+function hasLocalChanges(componentDir, state) {
+  const hashes = safeComputeHashes(componentDir);
+  if (!hashes) return false;
+  if (state === null) return true;
+  if (hashes.manifestHash !== state.manifestHash) return true;
+  const localSource = hashes.sourceHash ?? "";
+  const storedSource = state.sourceHash ?? "";
+  return localSource !== storedSource;
+}
+function safeComputeHashes(componentDir) {
+  try {
+    return computeComponentHashes(componentDir);
+  } catch {
+    return null;
+  }
+}
+
+// src/commands/apps/pull.ts
+async function pullCommand(args) {
+  const slug = requireProjectStore();
+  const force = flagBool(args.flags, "force");
+  const targets = args.positional;
+  const root = process.cwd();
+  if (targets.length === 0 || targets.length === 1 && targets[0] === "*") {
+    return pullAll({ slug, root, args, force });
+  }
+  if (targets.length > 1 && flagString(args.flags, "version")) {
+    throw new Error(
+      "--version is per-component; pass it together with a single `gs apps pull <name>`."
+    );
+  }
+  ensureComponentsDir(root);
+  const revisionQuery = buildRevisionQuery(args);
+  const outcomes = [];
+  for (const name of targets) {
+    const outcome = await pullOne({
+      slug,
+      componentDir: path7.join(root, "components", name),
+      name,
+      revisionQuery,
+      force
+    });
+    outcomes.push(outcome);
+    printOutcome(outcome, force);
+  }
+  if (outcomes.length > 1) printPullSummary(outcomes, slug);
+  if (outcomes.some((o) => o.status === "failed")) process.exitCode = 1;
+}
+async function pullAll(opts) {
+  const { slug, root, args, force } = opts;
+  if (flagString(args.flags, "version")) {
+    throw new Error(
+      "--version is per-component; pass it together with `gs apps pull <name>`."
+    );
+  }
+  ensureComponentsDir(root);
+  const revisionQuery = buildRevisionQuery(args);
+  const listUrl = `${apiBaseFor(slug)}/api/builder/components`;
+  const list = await request(listUrl);
+  if (list.components.length === 0) {
+    process.stdout.write(`(no components in ${slug})
+`);
+    return;
+  }
+  const outcomes = [];
+  for (const entry of list.components) {
+    const componentDir = path7.join(root, "components", entry.name);
+    const outcome = await pullOne({
+      slug,
+      componentDir,
+      name: entry.name,
+      revisionQuery,
+      force
+    });
+    outcomes.push(outcome);
+    printOutcome(outcome, force);
+  }
+  printPullSummary(outcomes, slug);
+  if (outcomes.some((o) => o.status === "failed")) process.exitCode = 1;
+}
+function printPullSummary(outcomes, slug) {
+  const pulled = outcomes.filter((o) => o.status === "pulled").length;
+  const skipped = outcomes.filter((o) => o.status === "skipped").length;
+  const failed = outcomes.filter((o) => o.status === "failed").length;
+  const summary = [`${pulled} pulled`, `${skipped} skipped`];
+  if (failed > 0) summary.push(`${failed} failed`);
+  process.stdout.write(
+    `
+${summary.join(", ")} (of ${outcomes.length}) \u2190 ${slug}
+`
+  );
+}
+async function pullOne(opts) {
+  const { slug, componentDir, name, revisionQuery, force } = opts;
+  if (!force && fs7.existsSync(componentDir)) {
+    const sync = readSyncState(componentDir);
+    if (hasLocalChanges(componentDir, sync)) {
+      return {
         name,
         status: "skipped",
         message: "local has uncommitted changes; pass --force to overwrite"
@@ -728,14 +1158,14 @@ async function pullOne(opts) {
       message: err instanceof Error ? err.message : String(err)
     };
   }
-  fs4.mkdirSync(componentDir, { recursive: true });
+  fs7.mkdirSync(componentDir, { recursive: true });
   const manifestText = JSON.stringify(data.manifest, null, 2) + "\n";
-  fs4.writeFileSync(path4.join(componentDir, "manifest.json"), manifestText);
-  fs4.writeFileSync(path4.join(componentDir, "bundle.js"), data.bundle);
+  fs7.writeFileSync(path7.join(componentDir, "manifest.json"), manifestText);
+  fs7.writeFileSync(path7.join(componentDir, "bundle.js"), data.bundle);
   const wrote = ["manifest.json", "bundle.js"];
   let sourceHash = "";
   if (data.source !== null) {
-    fs4.writeFileSync(path4.join(componentDir, "component.tsx"), data.source);
+    fs7.writeFileSync(path7.join(componentDir, "component.tsx"), data.source);
     wrote.push("component.tsx");
     sourceHash = hashString(data.source);
   }
@@ -753,7 +1183,7 @@ async function pullOne(opts) {
   return { name, status: "pulled", version: data.version, wrote };
 }
 function ensureComponentsDir(root) {
-  fs4.mkdirSync(path4.join(root, "components"), { recursive: true });
+  fs7.mkdirSync(path7.join(root, "components"), { recursive: true });
 }
 function buildRevisionQuery(args) {
   const version = flagString(args.flags, "version");
@@ -786,17 +1216,17 @@ function printOutcome(outcome, force) {
   void force;
 }
 
-// src/commands/push.ts
-import * as fs5 from "fs";
-import * as path5 from "path";
+// src/commands/apps/push.ts
+import * as fs8 from "fs";
+import * as path8 from "path";
 async function pushCommand(args) {
   const slug = requireProjectStore();
   const root = process.cwd();
   rejectLegacyLayout(root);
-  const componentsDir = path5.join(root, "components");
-  if (!fs5.existsSync(componentsDir)) {
+  const componentsDir = path8.join(root, "components");
+  if (!fs8.existsSync(componentsDir)) {
     throw new Error(
-      "No components/ directory here. Run `gs init <name>` to scaffold the project root and your first component."
+      "No components/ directory here. Run `gs apps init <name>` to scaffold the project root and your first component."
     );
   }
   const named = args.positional;
@@ -804,7 +1234,7 @@ async function pushCommand(args) {
   const bundleOverride = flagString(args.flags, "bundle");
   if (named.length !== 1 && (manifestOverride || bundleOverride)) {
     throw new Error(
-      "--manifest / --bundle can only be used together with a single `gs push <name>`."
+      "--manifest / --bundle can only be used together with a single `gs apps push <name>`."
     );
   }
   if (named.length > 0) {
@@ -828,7 +1258,7 @@ async function pushCommand(args) {
   const names = listLocalComponents(componentsDir);
   if (names.length === 0) {
     process.stdout.write(
-      "(no components in ./components \u2014 run `gs init <name>` to add one)\n"
+      "(no components in ./components \u2014 run `gs apps init <name>` to add one)\n"
     );
     return;
   }
@@ -853,28 +1283,28 @@ ${summary.join(", ")} (of ${outcomes.length}) \u2192 ${slug}
 }
 async function pushOne(opts) {
   const { slug, root, name, force } = opts;
-  const componentDir = path5.join(root, "components", name);
-  if (!fs5.existsSync(componentDir)) {
+  const componentDir = path8.join(root, "components", name);
+  if (!fs8.existsSync(componentDir)) {
     return {
       name,
       status: "failed",
       message: `components/${name}/ does not exist`
     };
   }
-  const manifestPath = opts.manifestPath ? path5.resolve(opts.manifestPath) : path5.join(componentDir, "manifest.json");
-  const bundlePath = opts.bundlePath ? path5.resolve(opts.bundlePath) : path5.join(componentDir, "bundle.js");
-  const sourcePath = path5.join(componentDir, "component.tsx");
-  if (!fs5.existsSync(manifestPath)) {
+  const manifestPath = opts.manifestPath ? path8.resolve(opts.manifestPath) : path8.join(componentDir, "manifest.json");
+  const bundlePath = opts.bundlePath ? path8.resolve(opts.bundlePath) : path8.join(componentDir, "bundle.js");
+  const sourcePath = path8.join(componentDir, "component.tsx");
+  if (!fs8.existsSync(manifestPath)) {
     return { name, status: "failed", message: `manifest not found: ${manifestPath}` };
   }
-  if (!fs5.existsSync(bundlePath)) {
+  if (!fs8.existsSync(bundlePath)) {
     return {
       name,
       status: "failed",
       message: `bundle not found: ${bundlePath} (did you run \`npm run build\`?)`
     };
   }
-  const manifestText = fs5.readFileSync(manifestPath, "utf8");
+  const manifestText = fs8.readFileSync(manifestPath, "utf8");
   let manifestName;
   try {
     const parsed = JSON.parse(manifestText);
@@ -901,8 +1331,8 @@ async function pushOne(opts) {
       return { name, status: "unchanged" };
     }
   }
-  const bundleText = fs5.readFileSync(bundlePath, "utf8");
-  const sourceText = fs5.existsSync(sourcePath) ? fs5.readFileSync(sourcePath, "utf8") : null;
+  const bundleText = fs8.readFileSync(bundlePath, "utf8");
+  const sourceText = fs8.existsSync(sourcePath) ? fs8.readFileSync(sourcePath, "utf8") : null;
   const form = new FormData();
   form.append(
     "manifest",
@@ -946,20 +1376,20 @@ async function pushOne(opts) {
   };
 }
 function listLocalComponents(componentsDir) {
-  return fs5.readdirSync(componentsDir).filter((entry) => {
-    const dir = path5.join(componentsDir, entry);
-    return fs5.statSync(dir).isDirectory() && fs5.existsSync(path5.join(dir, "manifest.json"));
+  return fs8.readdirSync(componentsDir).filter((entry) => {
+    const dir = path8.join(componentsDir, entry);
+    return fs8.statSync(dir).isDirectory() && fs8.existsSync(path8.join(dir, "manifest.json"));
   }).sort();
 }
 function rejectLegacyLayout(root) {
-  const rootManifest = path5.join(root, "manifest.json");
-  const componentsDir = path5.join(root, "components");
-  if (fs5.existsSync(rootManifest) && !fs5.existsSync(componentsDir)) {
+  const rootManifest = path8.join(root, "manifest.json");
+  const componentsDir = path8.join(root, "components");
+  if (fs8.existsSync(rootManifest) && !fs8.existsSync(componentsDir)) {
     throw new Error(
       [
         "Detected the old single-component layout (manifest.json at the project root).",
         "The Builder CLI now uses a multi-component layout: scaffold a fresh dir with",
-        "`gs init`, then move your component into `components/<name>/`. Re-run `gs push`",
+        "`gs apps init`, then move your component into `components/<name>/`. Re-run `gs apps push`",
         "from the new project root."
       ].join(" ")
     );
@@ -986,11 +1416,11 @@ function printOutcome2(outcome) {
   }
 }
 
-// src/commands/publish.ts
+// src/commands/apps/publish.ts
 async function publishCommand(args) {
   const names = args.positional;
   if (names.length === 0) {
-    throw new Error("Usage: gs publish <name> [<name>...] [--version N]");
+    throw new Error("Usage: gs apps publish <name> [<name>...] [--version N]");
   }
   const slug = requireProjectStore();
   const versionFlag = flagString(args.flags, "version");
@@ -998,7 +1428,7 @@ async function publishCommand(args) {
   if (versionFlag !== void 0) {
     if (names.length > 1) {
       throw new Error(
-        "--version is per-component; pass it together with a single `gs publish <name>`."
+        "--version is per-component; pass it together with a single `gs apps publish <name>`."
       );
     }
     const n = Number.parseInt(versionFlag, 10);
@@ -1067,10 +1497,10 @@ function printOutcome3(outcome) {
   );
 }
 
-// src/commands/unpublish.ts
+// src/commands/apps/unpublish.ts
 async function unpublishCommand(args) {
   const name = args.positional[0];
-  if (!name) throw new Error("Usage: gs unpublish <name>");
+  if (!name) throw new Error("Usage: gs apps unpublish <name>");
   const slug = requireProjectStore();
   const url = `${apiBaseFor(slug)}/api/builder/components/${encodeURIComponent(name)}/unpublish`;
   await request(url, { method: "POST", body: {} });
@@ -1078,11 +1508,11 @@ async function unpublishCommand(args) {
 `);
 }
 
-// src/commands/delete.ts
+// src/commands/apps/delete.ts
 import * as readline from "readline";
 async function deleteCommand(args) {
   const name = args.positional[0];
-  if (!name) throw new Error("Usage: gs delete <name> [--yes]");
+  if (!name) throw new Error("Usage: gs apps delete <name> [--yes]");
   const slug = requireProjectStore();
   if (!flagBool(args.flags, "yes")) {
     const confirmed = await prompt(
@@ -1099,436 +1529,541 @@ async function deleteCommand(args) {
 `);
 }
 function prompt(question) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve8) => {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     rl.question(question, (answer) => {
       rl.close();
-      resolve6(answer);
+      resolve8(answer);
     });
   });
 }
 
-// src/commands/init.ts
-import * as fs6 from "fs";
-import * as path6 from "path";
+// src/commands/apps/index.ts
+var APPS_HELP = `gs apps \u2014 author and ship custom in-chat apps
 
-// src/template.ts
-import { readdirSync as readdirSync2, readFileSync as readFileSync5 } from "fs";
-import { fileURLToPath } from "url";
-var cache = null;
-function loadTemplate() {
-  if (cache) return cache;
-  cache = true ? JSON.parse('{"component/component.tsx":"import React from \\"react\\";\\n\\n// Add your tool args (matching manifest.json#inputSchema.properties)\\n// alongside the GreatStore-injected lifecycle props. See AGENTS.md for\\n// what each lifecycle prop does.\\ninterface Props {\\n  onSendMessage: (text: string) => void;\\n  onCallTool: (name: string, args: Record<string, unknown>) => void;\\n  onClose: () => void;\\n}\\n\\n// See AGENTS.md for the design rules (em-based sizing, brand CSS\\n// variables), the lifecycle props, and how to write an async,\\n// backend-backed component.\\nexport default function __GS_PASCAL__(_props: Props): React.ReactElement {\\n  return (\\n    <div\\n      style={{\\n        padding: \\"1em\\",\\n        border: \\"1px solid var(--color-border-default)\\",\\n        borderRadius: \\"var(--radius-lg)\\",\\n        background: \\"var(--color-surface)\\",\\n        color: \\"var(--color-foreground)\\",\\n        fontFamily: \\"var(--font-sans)\\",\\n      }}\\n    >\\n      <strong>__GS_NAME__</strong> \u2014 hello from your component!\\n    </div>\\n  );\\n}\\n","component/manifest.json":"{\\n  \\"name\\": \\"__GS_NAME__\\",\\n  \\"displayName\\": \\"__GS_DISPLAY_NAME__\\",\\n  \\"description\\": \\"Renders the __GS_NAME__ widget.\\",\\n  \\"displayMode\\": \\"inline\\",\\n  \\"inputSchema\\": {\\n    \\"type\\": \\"object\\",\\n    \\"properties\\": {}\\n  }\\n}\\n","root/.gitignore":"node_modules/\\ncomponents/*/bundle.js\\ncomponents/*/.gssync.json\\n*.tsbuildinfo\\n.DS_Store\\n","root/.gsrc":"{\\n  \\"store\\": \\"__GS_STORE__\\"\\n}\\n","root/AGENTS.md":"# AGENTS.md\\n\\nGuidance for AI coding agents working on the components in this project.\\n`CLAUDE.md` and `GEMINI.md` are symlinks to this file.\\n\\nThese components render inside arbitrary publisher websites (the embed\\nwidget mounts on a host page) as well as the GreatStore storefront. You\\ncontrol neither the host page\'s base font size nor its color scheme, and\\nthe store owner controls the look from GreatStore theme settings. The\\nrules below keep components portable across both.\\n\\n## Design requirements\\n\\n### Never use `rem` for fonts and sizing \u2014 always use `em`\\n\\n`rem` resolves against the host page\'s root font size, which is\\narbitrary and outside our control. A host that sets `html { font-size:\\n8px }` (or 200%) will shrink or blow up every `rem`-based dimension.\\n`em` resolves against the component\'s own font size, so it stays\\nself-consistent wherever the component is mounted.\\n\\nUse `em` for font sizes, padding, margins, gaps, widths, heights,\\nand any other length. Borders may stay in `px` (hairlines should not\\nscale with text).\\n\\n```tsx\\n// Bad \u2014 breaks on hosts with a non-default root font size\\n<div style={{ padding: \\"1rem\\", fontSize: \\"0.875rem\\" }} />\\n\\n// Good\\n<div style={{ padding: \\"1em\\", fontSize: \\"0.875em\\" }} />\\n```\\n\\n### Don\'t hardcode colors, fonts, or corner radius \u2014 use GreatStore brand variables\\n\\nThe store owner themes the assistant from GreatStore settings. Hardcoded\\nvalues ignore that and make the component clash with the rest of the\\nstore. Read from the CSS variables GreatStore injects on the surface\\ninstead, so the component restyles itself when the theme changes.\\n\\nAvailable variables:\\n\\n| Purpose | Variable |\\n| --- | --- |\\n| Surface background | `--color-surface` |\\n| Secondary surface | `--color-surface-secondary` |\\n| Accent surface | `--color-surface-accent` |\\n| Hover surface | `--color-surface-hover` |\\n| Foreground text | `--color-foreground` |\\n| Secondary text | `--color-foreground-secondary` |\\n| Muted text | `--color-foreground-muted` |\\n| Accent text | `--color-foreground-accent` |\\n| Border | `--color-border-default` |\\n| Focus border | `--color-border-focus` |\\n| Primary / brand | `--color-primary` |\\n| Text on primary | `--color-primary-foreground` |\\n| Primary hover | `--color-primary-hover` |\\n| Primary muted | `--color-primary-muted` |\\n| Text on primary muted | `--color-primary-muted-foreground` |\\n| Primary tint | `--color-primary-tint` |\\n| Link | `--color-link` |\\n| Font family | `--font-sans` |\\n| Corner radius (scale) | `--radius-xs` \u2026 `--radius-4xl`, `--radius-pill` |\\n\\n```tsx\\n// Bad \u2014 hardcoded, ignores the store\'s theme\\n<button style={{ background: \\"#4f46e5\\", borderRadius: 8, fontFamily: \\"Inter\\" }} />\\n\\n// Good\\n<button\\n  style={{\\n    background: \\"var(--color-primary)\\",\\n    color: \\"var(--color-primary-foreground)\\",\\n    borderRadius: \\"var(--radius-lg)\\",\\n    fontFamily: \\"var(--font-sans)\\",\\n  }}\\n/>\\n```\\n\\nProvide a sensible fallback only when a value might be absent, e.g.\\n`var(--color-primary, currentColor)`.\\n\\n## Component props\\n\\nEach component receives its tool args (the fields you declare in\\n`manifest.json#inputSchema.properties`) plus these GreatStore-injected\\nlifecycle props, which are always present:\\n\\n| Prop | What it does |\\n| --- | --- |\\n| `onSendMessage(text)` | Send text into the chat as if the shopper typed it. |\\n| `onCallTool(name, args)` | Chain into another remote-component tool by name. |\\n| `onClose()` | Dismiss the host slot. Over-input clears the overlay, fullscreen reverts the pane, inline is a no-op. |\\n\\n## Async components (backend-backed, render-blocking data)\\n\\nIf a component must load data from a backend/API before it can render\\ncorrectly, make it async \u2014 don\'t render an empty shell and fetch in a\\n`useEffect`. Set `\\"async\\": true` in `manifest.json` and export an async\\ndefault. GreatStore waits for your promise (showing a normal loading\\nstate, so you don\'t render your own placeholder), then renders what it\\nresolves to. Components that render purely from their props stay\\nsynchronous.\\n\\nA thrown error is a **retry signal**: the in-store AI sees it and\\nusually re-calls the tool. So only throw when a *different* call could\\nhelp:\\n\\n1. `await` the backend call, then return the finished JSX.\\n2. Validate the AI-passed props first and throw on bad input \u2014 the AI\\n   can fix the args and retry. (Don\'t validate the API\'s *output* and\\n   throw: the AI can\'t fix the backend, it\'ll just loop.)\\n3. Broadcast a backend failure ONLY when retrying differently could\\n   succeed, and say what to change (e.g. empty search \u2192 \\"try a broader\\n   keyword\\"). For idempotent failures (500, timeout, missing record)\\n   re-running the same call changes nothing \u2014 render a graceful fallback\\n   instead of throwing.\\n\\n```tsx\\nexport default async function Example(props: Props) {\\n  if (!props.query?.trim()) throw new Error(\\"missing required prop: query\\");\\n  const res = await fetch(`/api/search?q=${encodeURIComponent(props.query)}`);\\n  if (res.ok) {\\n    const { results } = await res.json();\\n    if (results.length === 0)\\n      throw new Error(`no results for \\"${props.query}\\" \u2014 try a broader keyword`);\\n    return <ul>{/* render results */}</ul>;\\n  }\\n  return <p>Couldn\'t load results right now.</p>; // idempotent: don\'t throw\\n}\\n```\\n","root/README.md":"# GreatStore components\\n\\nCustom React components published to your GreatStore tenant. Each\\ncomponent lives in its own folder under `components/`.\\n\\n```\\nnpm install\\ngs init <component_name>      # add a new component\\ngs build                      # builds every components/<name>/bundle.js\\ngs push                       # uploads every changed component as a draft\\ngs publish <component_name>   # promote a specific component to live\\n```\\n\\n- `gs push` (no args) hashes each component and only uploads the ones\\n  that have changed since the last sync.\\n- `gs pull` (no args) refreshes every remote component into\\n  `components/<name>/`. Components with unsaved local edits are skipped\\n  with a warning; pass `--force` to overwrite.\\n\\nSee `AGENTS.md` for the design rules every component must follow\\n(em-based sizing, brand CSS variables) \u2014 it doubles as guidance for AI\\ncoding agents (`CLAUDE.md` / `GEMINI.md` symlink to it).\\n","root/package.json":"{\\n  \\"name\\": \\"greatstore-components\\",\\n  \\"version\\": \\"0.0.1\\",\\n  \\"private\\": true,\\n  \\"type\\": \\"module\\",\\n  \\"scripts\\": {\\n    \\"build\\": \\"gs build\\",\\n    \\"push\\": \\"gs build && gs push\\"\\n  },\\n  \\"dependencies\\": {\\n    \\"react\\": \\"^19.0.0\\",\\n    \\"react-dom\\": \\"^19.0.0\\"\\n  },\\n  \\"devDependencies\\": {\\n    \\"@types/react\\": \\"^19.0.0\\",\\n    \\"@types/react-dom\\": \\"^19.0.0\\",\\n    \\"@vitejs/plugin-react\\": \\"^4.3.0\\",\\n    \\"typescript\\": \\"^5.6.0\\",\\n    \\"vite\\": \\"^5.4.0\\"\\n  }\\n}\\n","root/tsconfig.json":"{\\n  \\"compilerOptions\\": {\\n    \\"target\\": \\"ES2022\\",\\n    \\"module\\": \\"ESNext\\",\\n    \\"moduleResolution\\": \\"Bundler\\",\\n    \\"jsx\\": \\"react-jsx\\",\\n    \\"lib\\": [\\"ES2022\\", \\"DOM\\"],\\n    \\"strict\\": true,\\n    \\"esModuleInterop\\": true,\\n    \\"skipLibCheck\\": true,\\n    \\"isolatedModules\\": true,\\n    \\"noEmit\\": true\\n  },\\n  \\"include\\": [\\"components/**/component.tsx\\", \\"vite.config.ts\\"]\\n}\\n","root/vite.config.ts":"import { defineConfig } from \\"vite\\";\\nimport react from \\"@vitejs/plugin-react\\";\\n\\n// Real builds happen in `gs build` (one Vite invocation per\\n// component, externals + runtime shim paths owned by the CLI). This\\n// file exists only so editors / language servers can resolve the\\n// React plugin when inspecting components/*/component.tsx.\\nexport default defineConfig({\\n  plugins: [react()],\\n});\\n"}') : readTreeFromDisk(new URL("../template/", import.meta.url));
-  return cache;
-}
-var TOKENS = {
-  name: "__GS_NAME__",
-  pascalName: "__GS_PASCAL__",
-  displayName: "__GS_DISPLAY_NAME__",
-  store: "__GS_STORE__"
-};
-function applyTemplate(content, vars) {
-  let out = content;
-  for (const key of Object.keys(TOKENS)) {
-    const value = vars[key];
-    if (value !== void 0) out = out.split(TOKENS[key]).join(value);
-  }
-  const leftover = out.match(/__GS_[A-Z_]+__/);
-  if (leftover) {
-    throw new Error(
-      `internal: template placeholder ${leftover[0]} was not provided`
-    );
-  }
-  return out;
-}
+Usage:
+  gs apps <subcommand> [args] [flags]
 
-// src/commands/init.ts
-var NAME_REGEX = /^[a-z][a-z0-9_]*$/;
-function initCommand(args) {
-  const name = args.positional[0];
-  if (name !== void 0 && !NAME_REGEX.test(name)) {
-    throw new Error(`Invalid component name: "${name}" (must match ${NAME_REGEX}).`);
-  }
-  const force = flagBool(args.flags, "force");
-  const storeFlag = flagString(args.flags, "store");
-  const outRel = flagString(args.flags, "out") ?? ".";
-  const root = path6.resolve(outRel);
-  const rootExisted = hasRootScaffold(root);
-  if (rootExisted) {
-    if (storeFlag !== void 0) {
-      throw new Error(
-        `Project at ${root} is already pinned to a store via .gsrc. Drop --store; a project folder ships to exactly one store.`
-      );
-    }
-  } else if (storeFlag === void 0) {
-    const example = name ? `gs init ${name} --store <slug>` : `gs init --store <slug>`;
-    throw new Error(
-      `--store <slug> is required when scaffolding a new project root. Run \`${example}\`.`
-    );
-  }
-  const writtenRootFiles = ensureRoot(root, rootExisted, force, { store: storeFlag });
-  if (!name) {
-    const lines = [];
-    if (rootExisted) {
-      lines.push(`Updated GreatStore project root in ${root}.`);
-      if (writtenRootFiles.length > 0) {
-        lines.push("", `Added: ${writtenRootFiles.join(", ")}`);
-      } else {
-        lines.push("", "Already up to date \u2014 nothing to add.");
-      }
-    } else {
-      lines.push(`Scaffolded GreatStore project root in ${root}.`);
-    }
-    lines.push(
-      "",
-      "Next steps:",
-      `  cd ${path6.relative(process.cwd(), root) || "."}`,
-      "  npm install",
-      "  gs init <component_name>     # add your first component",
-      ""
-    );
-    process.stdout.write(lines.join("\n"));
-    return;
-  }
-  const componentDir = path6.join(root, "components", name);
-  ensureComponent(componentDir, name, force);
-  const projectLabel = path6.relative(process.cwd(), root) || ".";
-  process.stdout.write(
-    [
-      `Added component "${name}" at components/${name}/.`,
-      ...rootExisted && writtenRootFiles.length > 0 ? ["", `Also added to the project root: ${writtenRootFiles.join(", ")}`] : [],
-      "",
-      "Next steps:",
-      ...rootExisted ? [] : [`  cd ${projectLabel}`, "  npm install"],
-      `  # edit components/${name}/component.tsx and manifest.json`,
-      "  gs build",
-      "  gs push",
-      ""
-    ].join("\n")
-  );
-}
-function hasRootScaffold(dir) {
-  return fs6.existsSync(path6.join(dir, "package.json")) && fs6.existsSync(path6.join(dir, ".gsrc"));
-}
-function ensureRoot(root, rootExisted, force, opts) {
-  fs6.mkdirSync(root, { recursive: true });
-  if (!rootExisted && !force) {
-    const entries = fs6.readdirSync(root).filter((e) => e !== ".gsrc");
-    if (entries.length > 0) {
-      throw new Error(
-        `Refusing to scaffold project root into non-empty directory ${root}. Pass --force to override.`
-      );
-    }
-  }
-  const files = rootExisted ? existingRootFiles() : rootFiles({ store: opts.store });
-  const written = writeRootFiles(root, files, force);
-  fs6.mkdirSync(path6.join(root, "components"), { recursive: true });
-  return written;
-}
-function writeRootFiles(root, files, force) {
-  const written = [];
-  for (const [relPath, content] of files) {
-    const full = path6.join(root, relPath);
-    fs6.mkdirSync(path6.dirname(full), { recursive: true });
-    if (force || !fs6.existsSync(full)) {
-      fs6.writeFileSync(full, content);
-      written.push(relPath);
-    }
-  }
-  for (const link of ["CLAUDE.md", "GEMINI.md"]) {
-    const linkPath = path6.join(root, link);
-    if (force && pathExists(linkPath)) fs6.rmSync(linkPath);
-    if (!pathExists(linkPath)) {
-      fs6.symlinkSync("AGENTS.md", linkPath);
-      written.push(link);
-    }
-  }
-  return written;
-}
-function pathExists(p) {
-  try {
-    fs6.lstatSync(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function ensureComponent(componentDir, name, force) {
-  if (fs6.existsSync(componentDir) && !force) {
-    const entries = fs6.readdirSync(componentDir);
-    if (entries.length > 0) {
-      throw new Error(
-        `Refusing to overwrite existing components/${name}/. Pass --force to override.`
-      );
-    }
-  }
-  fs6.mkdirSync(componentDir, { recursive: true });
-  for (const [relPath, content] of componentFiles(name)) {
-    fs6.writeFileSync(path6.join(componentDir, relPath), content);
-  }
-}
-function templateFiles(prefix, vars, exclude = /* @__PURE__ */ new Set()) {
-  const tree = loadTemplate();
-  return Object.entries(tree).filter(([rel]) => rel.startsWith(prefix)).map(([rel, content]) => [rel.slice(prefix.length), content]).filter(([dest]) => !exclude.has(dest)).map(([dest, content]) => [dest, applyTemplate(content, vars)]);
-}
-function rootFiles(opts) {
-  if (!opts.store) {
-    throw new Error("internal: rootFiles called without a store slug");
-  }
-  return templateFiles("root/", { store: opts.store });
-}
-function existingRootFiles() {
-  return templateFiles("root/", {}, /* @__PURE__ */ new Set([".gsrc"]));
-}
-function componentFiles(name) {
-  return templateFiles("component/", {
-    name,
-    pascalName: pascal(name),
-    displayName: defaultDisplayName(name)
-  });
-}
-function defaultDisplayName(name) {
-  const words = name.split("_").filter(Boolean);
-  if (words.length === 0) return name;
-  const first = words[0];
-  return first.charAt(0).toUpperCase() + first.slice(1) + (words.length > 1 ? " " + words.slice(1).join(" ") : "");
-}
-function pascal(name) {
-  return name.split(/[_-]/).filter(Boolean).map((part) => part[0]?.toUpperCase() + part.slice(1)).join("");
-}
+Subcommands:
+  init [<name>]                  Scaffold project root; add \`components/<name>/\` if name given.
+  build [<name>]                 Build component bundle(s) via the project's Vite. No args = all.
+  list                           List components in the current store.
+  pull [<name>...|*]             Download remote component(s) into \`components/<name>/\`.
+  push [<name>...]               Upload changed components from \`components/\`.
+  publish <name>...              Promote the draft(s) (or --version N) to live.
+  unpublish <name>               Clear the live pointer.
+  delete <name>                  Soft-delete the component.
+`;
+async function appsCommand(args) {
+  const sub = args.positional[0];
+  const rest = { ...args, positional: args.positional.slice(1) };
+  switch (sub) {
+    case void 0:
+    case "help":
+      process.stdout.write(APPS_HELP);
+      return 0;
+    case "init":
+      initCommand(rest);
+      return 0;
+    case "build":
+      await buildCommand(rest);
+      return 0;
+    case "list":
+      await listCommand(rest);
+      return 0;
+    case "pull":
+      await pullCommand(rest);
+      return 0;
+    case "push":
+      await pushCommand(rest);
+      return 0;
+    case "publish":
+      await publishCommand(rest);
+      return 0;
+    case "unpublish":
+      await unpublishCommand(rest);
+      return 0;
+    case "delete":
+      await deleteCommand(rest);
+      return 0;
+    default:
+      process.stderr.write(`Unknown apps subcommand: ${sub}
 
-// src/commands/build.ts
-import * as fs7 from "fs";
-import * as path7 from "path";
-import { createRequire } from "module";
-var COMPONENTS_DIR = "components";
-async function buildCommand(args) {
-  const root = process.cwd();
-  if (!fs7.existsSync(path7.join(root, "package.json")) || !fs7.existsSync(path7.join(root, COMPONENTS_DIR))) {
-    throw new Error(
-      `\`gs build\` must run from a project root (contains \`package.json\` and \`${COMPONENTS_DIR}/\`). Current dir: ${root}`
-    );
-  }
-  const components = listComponents(root);
-  if (components.length === 0) {
-    process.stdout.write(
-      `(no components in ./${COMPONENTS_DIR} \u2014 run \`gs init <name>\` to add one)
-`
-    );
-    return;
-  }
-  const target = args.positional[0];
-  const queue = target ? components.filter((c) => c === target) : components;
-  if (target && queue.length === 0) {
-    throw new Error(`No component named "${target}" in ./${COMPONENTS_DIR}`);
-  }
-  const { build, reactPlugin, transformWithEsbuild } = await loadVite(root);
-  for (const name of queue) {
-    const dir = path7.join(root, COMPONENTS_DIR, name);
-    const bundlePath = path7.join(dir, "bundle.js");
-    await build({
-      plugins: [reactPlugin()],
-      logLevel: "warn",
-      build: {
-        lib: {
-          entry: path7.join(dir, "component.tsx"),
-          formats: ["es"],
-          fileName: () => "bundle.js"
-        },
-        outDir: dir,
-        emptyOutDir: false,
-        rollupOptions: {
-          external: ["react", "react-dom", "react/jsx-runtime"],
-          output: {
-            entryFileNames: "bundle.js",
-            paths: {
-              react: "/assets/remote-components/_runtime.js",
-              "react-dom": "/assets/remote-components/_runtime.js",
-              "react/jsx-runtime": "/assets/remote-components/_runtime.js"
-            }
-          }
-        },
-        minify: true,
-        sourcemap: false
-      }
-    });
-    const beforeBytes = fs7.statSync(bundlePath).size;
-    const src = fs7.readFileSync(bundlePath, "utf8");
-    const { code } = await transformWithEsbuild(src, bundlePath, {
-      minify: true,
-      legalComments: "none",
-      target: "esnext",
-      loader: "js",
-      sourcemap: false
-    });
-    fs7.writeFileSync(bundlePath, code);
-    const afterBytes = Buffer.byteLength(code, "utf8");
-    process.stdout.write(
-      `built ${COMPONENTS_DIR}/${name}/bundle.js (${formatBytes(afterBytes)}, ${pctSmaller(beforeBytes, afterBytes)} smaller)
-`
-    );
+${APPS_HELP}`);
+      return 1;
   }
-  process.stdout.write(
-    `
-Built locally \u2014 nothing uploaded yet. Next: \`gs push\` to upload, then \`gs publish <name>\` to ship. If you're an AI assistant: confirm with the user before running these (or just run them if they already asked you to ship end-to-end).
-`
-  );
 }
-function listComponents(root) {
-  const dir = path7.join(root, COMPONENTS_DIR);
-  return fs7.readdirSync(dir).filter((entry) => {
-    const candidate = path7.join(dir, entry);
-    return fs7.statSync(candidate).isDirectory() && fs7.existsSync(path7.join(candidate, "component.tsx"));
-  }).sort();
+
+// src/commands/configure/show.ts
+async function showConfig(args) {
+  const slug = resolveAdminStore(args);
+  const url = `${apiBaseFor(slug)}/admin/configure/config`;
+  const data = await request(url);
+  if (flagBool(args.flags, "json")) {
+    process.stdout.write(JSON.stringify(data.brand, null, 2) + "\n");
+    return;
+  }
+  printBrand(slug, data.brand);
+}
+function printBrand(slug, brand) {
+  const lines = [`Configuration for ${slug}:`, ""];
+  lines.push(`  displayName       ${brand.displayName ?? "\u2014"}`);
+  lines.push(`  assistantName     ${brand.assistantName ?? "\u2014"}`);
+  lines.push(`  storeLink         ${brand.storeLink ?? "\u2014"}`);
+  lines.push(`  extraOrigins      ${formatList(brand.extraOrigins)}`);
+  lines.push(`  shopifyLoginGate  ${brand.shopifyLoginGate ? "on" : "off"}`);
+  lines.push(`  icon              ${brand.icon?.url ?? "\u2014"}`);
+  lines.push(`  logoLight         ${brand.logo?.light?.url ?? "\u2014"}`);
+  lines.push(`  logoDark          ${brand.logo?.dark?.url ?? "\u2014"}`);
+  lines.push(`  theme             ${brand.theme ? JSON.stringify(brand.theme) : "\u2014"}`);
+  lines.push(`  cspScriptHosts    ${formatList(brand.cspScriptHosts)}`);
+  lines.push(`  cspConnectHosts   ${formatList(brand.cspConnectHosts)}`);
+  lines.push(`  salesGuide        ${formatSalesGuide(brand.salesGuide)}`);
+  process.stdout.write(lines.join("\n") + "\n");
 }
-function formatBytes(n) {
-  if (n < 1024) return `${n} B`;
-  return `${(n / 1024).toFixed(1)} KB`;
+function formatList(list) {
+  if (!list || list.length === 0) return "\u2014";
+  return list.join(", ");
 }
-function pctSmaller(before, after) {
-  if (before === 0) return "0%";
-  return `${Math.round((1 - after / before) * 100)}%`;
+function formatSalesGuide(guide) {
+  if (!guide) return "\u2014";
+  const flat = guide.replace(/\s+/g, " ").trim();
+  return flat.length > 60 ? `${flat.slice(0, 57)}\u2026 (${guide.length} chars)` : flat;
 }
-async function loadVite(root) {
-  const localRequire = createRequire(path7.join(root, "package.json"));
-  const vitePath = resolveEsmEntry(localRequire, "vite");
-  if (!vitePath) {
-    throw new Error(
-      "Cannot find `vite` in this project. Run `npm install` first."
-    );
+
+// src/commands/configure/set.ts
+import * as fs9 from "fs";
+import * as path9 from "path";
+var TEXT_FIELDS = [
+  "displayName",
+  "assistantName",
+  "salesGuide",
+  "storeLink"
+];
+var LIST_FIELDS = ["extraOrigins", "cspScriptHosts", "cspConnectHosts"];
+async function setConfig(args) {
+  const slug = resolveAdminStore(args);
+  const body = {};
+  for (const field of TEXT_FIELDS) {
+    if (!(field in args.flags)) continue;
+    const v = args.flags[field];
+    if (typeof v !== "string") {
+      throw new Error(`--${field} requires a value (use --${field} "" to clear).`);
+    }
+    body[field] = v === "" ? null : v;
   }
-  const reactPath = resolveEsmEntry(localRequire, "@vitejs/plugin-react");
-  if (!reactPath) {
-    throw new Error(
-      "Cannot find `@vitejs/plugin-react` in this project. Run `npm install` first."
-    );
+  const salesGuideFile = flagString(args.flags, "salesGuideFile");
+  if (salesGuideFile !== void 0) {
+    if ("salesGuide" in body) {
+      throw new Error("Pass either --salesGuide or --salesGuideFile, not both.");
+    }
+    body["salesGuide"] = readTextFile(salesGuideFile, "--salesGuideFile");
   }
-  const viteMod = await import(vitePath);
-  const build = viteMod.build ?? viteMod.default?.build;
-  if (typeof build !== "function") {
-    throw new Error(
-      `Loaded \`vite\` from ${vitePath} but couldn't find its \`build()\` export. Reinstall vite (>= 5) and retry.`
-    );
+  for (const field of LIST_FIELDS) {
+    if (!(field in args.flags)) continue;
+    const v = args.flags[field];
+    if (typeof v !== "string") {
+      throw new Error(
+        `--${field} requires a comma-separated value (use --${field} "" to clear).`
+      );
+    }
+    const entries = v.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    body[field] = entries.length === 0 ? null : entries;
   }
-  const transformWithEsbuild = viteMod.transformWithEsbuild ?? viteMod.default?.transformWithEsbuild;
-  if (typeof transformWithEsbuild !== "function") {
-    throw new Error(
-      `Loaded \`vite\` from ${vitePath} but couldn't find its \`transformWithEsbuild()\` export. Reinstall vite (>= 5) and retry.`
-    );
+  if ("shopifyLoginGate" in args.flags) {
+    const v = args.flags["shopifyLoginGate"];
+    if (v !== true && v !== "true" && v !== "false") {
+      throw new Error("--shopifyLoginGate must be true or false.");
+    }
+    body["shopifyLoginGate"] = v === true || v === "true";
   }
-  const reactMod = await import(reactPath);
-  const reactPlugin = reactMod.default ?? reactMod;
-  if (typeof reactPlugin !== "function") {
+  const themeFile = flagString(args.flags, "themeFile");
+  if ("theme" in args.flags && themeFile !== void 0) {
+    throw new Error("Pass either --theme or --themeFile, not both.");
+  }
+  if ("theme" in args.flags) {
+    const v = args.flags["theme"];
+    if (typeof v !== "string") {
+      throw new Error('--theme requires a JSON value (use --theme "" to clear).');
+    }
+    body["theme"] = v === "" ? null : parseThemeJson(v, "--theme");
+  } else if (themeFile !== void 0) {
+    body["theme"] = parseThemeJson(readTextFile(themeFile, "--themeFile"), "--themeFile");
+  }
+  if (Object.keys(body).length === 0) {
     throw new Error(
-      `Loaded \`@vitejs/plugin-react\` from ${reactPath} but couldn't find its default export.`
+      'Nothing to save. Pass at least one field flag, e.g. `gs configure set --displayName "Acme"`.'
     );
   }
-  return {
-    build,
-    reactPlugin,
-    transformWithEsbuild
-  };
+  const url = `${apiBaseFor(slug)}/admin/configure/save`;
+  const data = await request(url, {
+    method: "POST",
+    body
+  });
+  if (flagBool(args.flags, "json")) {
+    process.stdout.write(JSON.stringify(data.config, null, 2) + "\n");
+    return;
+  }
+  process.stdout.write(`Saved ${Object.keys(body).join(", ")} \u2192 ${slug}
+`);
 }
-function resolveEsmEntry(req, specifier) {
-  let anchor;
-  try {
-    anchor = req.resolve(specifier);
-  } catch {
-    return null;
+function readTextFile(filePath, flag) {
+  const resolved = path9.resolve(filePath);
+  if (!fs9.existsSync(resolved)) {
+    throw new Error(`${flag}: file not found: ${resolved}`);
   }
-  const pkgJsonPath = findOwningPackageJson(anchor, specifier);
-  if (!pkgJsonPath) return null;
-  const pkgDir = path7.dirname(pkgJsonPath);
-  let pkg;
+  return fs9.readFileSync(resolved, "utf8");
+}
+function parseThemeJson(raw, flag) {
+  let parsed;
   try {
-    pkg = JSON.parse(fs7.readFileSync(pkgJsonPath, "utf8"));
-  } catch {
-    return null;
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${flag}: not valid JSON: ${err.message}`);
   }
-  const fromExports = pickImportEntry(pkg.exports);
-  const entry = fromExports ?? (typeof pkg.module === "string" ? pkg.module : null) ?? (typeof pkg.main === "string" ? pkg.main : null);
-  if (!entry) return null;
-  return path7.resolve(pkgDir, entry);
-}
-function findOwningPackageJson(start, specifier) {
-  let dir = path7.dirname(start);
-  while (true) {
-    const candidate = path7.join(dir, "package.json");
-    if (fs7.existsSync(candidate)) {
-      try {
-        const parsed = JSON.parse(fs7.readFileSync(candidate, "utf8"));
-        if (parsed.name === specifier) return candidate;
-      } catch {
-      }
-    }
-    const parent = path7.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${flag}: theme must be a JSON object.`);
   }
+  return parsed;
 }
-function pickImportEntry(exports) {
-  if (typeof exports !== "object" || exports === null) return null;
-  const map = exports;
-  const dot = map["."] ?? exports;
-  if (typeof dot !== "object" || dot === null) return null;
-  const imp = dot.import;
-  if (typeof imp === "string") return imp;
-  if (typeof imp === "object" && imp !== null) {
-    const def = imp.default;
-    if (typeof def === "string") return def;
+
+// src/commands/configure/upload.ts
+import * as fs10 from "fs";
+import * as path10 from "path";
+
+// src/commands/configure/shared.ts
+var ASSET_KINDS = ["icon", "logoLight", "logoDark"];
+function parseAssetKind(raw) {
+  if (raw && ASSET_KINDS.includes(raw)) {
+    return raw;
   }
-  return null;
+  throw new Error(`Asset kind must be one of: ${ASSET_KINDS.join(", ")}.`);
 }
 
-// src/commands/skill.ts
-import * as fs8 from "fs";
-import * as os2 from "os";
-import * as path8 from "path";
+// src/commands/configure/upload.ts
+var MIME_BY_EXT = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp"
+};
+async function uploadAsset(args) {
+  const slug = resolveAdminStore(args);
+  const kind = parseAssetKind(args.positional[0]);
+  const filePath = args.positional[1];
+  if (!filePath) {
+    throw new Error(`Usage: gs configure upload <${ASSET_KINDS.join("|")}> <file>`);
+  }
+  const resolved = path10.resolve(filePath);
+  if (!fs10.existsSync(resolved)) {
+    throw new Error(`File not found: ${resolved}`);
+  }
+  const mime = MIME_BY_EXT[path10.extname(resolved).toLowerCase()];
+  if (!mime) {
+    throw new Error("Unsupported image type. Use .png, .jpg, or .webp.");
+  }
+  const bytes = fs10.readFileSync(resolved);
+  const form = new FormData();
+  form.append(
+    "file",
+    new Blob([new Uint8Array(bytes)], { type: mime }),
+    path10.basename(resolved)
+  );
+  const url = `${apiBaseFor(slug)}/admin/configure/upload/${kind}`;
+  const data = await request(url, {
+    method: "POST",
+    multipart: form
+  });
+  process.stdout.write(`Uploaded ${kind} \u2192 ${data.url}
+`);
+}
 
-// src/skill.ts
-var SKILL_DIR_NAME = "greatstore";
-var cache2 = null;
-function loadSkill() {
-  if (cache2) return cache2;
-  cache2 = true ? JSON.parse('{"SKILL.md":"---\\nname: greatstore\\ndescription: 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, setting up web push re-engagement, or connecting AI agents to a store\'s MCP endpoints. Covers setup, schema design, caching behavior, component authoring, and ready-made recipes.\\n---\\n\\n# Building with GreatStore\\n\\nGreatStore gives a store an AI shopping assistant on two surfaces: a hosted\\nstorefront at `https://<slug>.greatstore.ai/`, and an embedded chat widget on\\nthe merchant\'s own site, installed with one script tag:\\n\\n```html\\n<script src=\\"https://my-store.greatstore.ai/embed.js\\"></script>\\n```\\n\\nEverything else a site can do with GreatStore is documented in the\\nreferences below. Read the one that matches the task before writing code \u2014\\neach facet has non-obvious rules (caching, grounding, result shapes, design\\nconstraints) that the references spell out.\\n\\n## Index\\n\\n| Goal | Use | Read |\\n|---|---|---|\\n| Install the widget; control the panel; readiness, events, troubleshooting | `window.GreatStore` SDK | [references/embed-api.md](references/embed-api.md) |\\n| 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) |\\n| Copy-paste on-page experiences | recipes built on the SDK | the [Recipes](#recipes) table below |\\n| Contextual **conversation entry points** anywhere on the page | `sendMessage(text)`, `open()`, `?gs_chat=open` | [references/embed-api.md](references/embed-api.md) |\\n| Let the assistant **act on the page** (cart, navigation, filters) | WebMCP: `document.modelContext.registerTool(...)` | [references/embed-api.md](references/embed-api.md) |\\n| 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) |\\n| **Re-engage shoppers** with browser notifications | merchant-hosted `gs.js` + `enableNotifications()` | [references/push-notifications.md](references/push-notifications.md) |\\n| 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) |\\n\\n## Two things to know before any of it\\n\\n- The page\'s domain **must be in the store\'s allowed domains** (GreatStore\\n  store settings). If it isn\'t, nothing works and the console shows\\n  `[GreatStore] Chat is unavailable on <origin>\u2026` \u2014 check this first whenever\\n  the embed appears dead.\\n- Every SDK call is safe immediately after the script tag \u2014 pre-mount calls\\n  queue and replay in order, and the SDK pre-warms itself in the background.\\n\\n## Recipes\\n\\nComplete, framework-free implementations, one per file. Shared conventions:\\ncontainers start `hidden` and reveal only on success (a failed generation\\nchanges nothing); generated strings render via `textContent`, never\\n`innerHTML`; every recipe guards on `window.GreatStore`; prompts stay\\ndeterministic per page so every visitor after the first hits the cache.\\nInline real product/page data into prompts where the platform exposes it.\\n\\n| Recipe | What it builds | Use it for |\\n|---|---|---|\\n| [GreatStore launchers](recipes/launchers.md) | Horizontally scrollable AI-generated chips \u2014 engaging first-person questions about the current page; tap to ask the assistant. | Instant engagement on any page type \u2014 product, collection, blog, home. Simple yet effective; start here. |\\n| [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 \u2014 anywhere a shopper hesitates. |\\n| [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. |\\n| [Comparison table](recipes/comparison-table.md) | AI-picked representative products compared on category-relevant criteria. | Collection pages where shoppers weigh options. |\\n| [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. |\\n| [Campaign hero](recipes/campaign-hero.md) | Seasonal homepage hero copy, cache-keyed to the ISO week. | Fresh homepage/campaign copy without manual rewrites. |\\n| [Gift finder funnel](recipes/gift-finder-funnel.md) | Quiz teaser \u2192 chat handoff \u2192 page-tool navigation; the full funnel. | Gifting seasons, guided discovery, homepage engagement. |\\n| [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. |\\n| [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. |\\n\\n## How the facets combine\\n\\nThe strongest pattern is the **teaser \u2192 conversation \u2192 action** funnel:\\n`generateStructuredContent` renders a grounded teaser in the merchant\'s\\ndesign; each option\'s click handler calls `sendMessage` with the shopper\'s\\nchoice, dropping them into a conversation with momentum; WebMCP page tools\\nand custom chat components let that conversation actually do things \u2014 add to\\ncart, configure a product, book a slot \u2014 so it ends in a conversion, not a\\ncopy-paste. The [gift finder funnel](recipes/gift-finder-funnel.md)\\nrecipe is this funnel end to end.\\n","recipes/ask-about-this.md":"# \\"Ask about this\\" entry points (`sendMessage` only)\\n\\nZero-generation, instant, and often the biggest engagement win per line of\\ncode. Sprinkle context-aware buttons wherever a shopper hesitates:\\n\\n```js\\nconst gs = window.GreatStore;\\nif (gs) {\\n  sizeGuideLink.addEventListener(\\"click\\", (e) => {\\n    e.preventDefault();\\n    gs.sendMessage(`How does the sizing run on \\"${productName}\\"? I usually wear a medium.`);\\n  });\\n\\n  shippingRow.querySelector(\\".ask\\").addEventListener(\\"click\\", () => {\\n    gs.sendMessage(`What are the shipping options and times for \\"${productName}\\"?`);\\n  });\\n\\n  outOfStockBadge?.addEventListener(\\"click\\", () => {\\n    gs.sendMessage(`\\"${productName}\\" looks out of stock \u2014 is there anything similar in stock?`);\\n  });\\n}\\n```\\n\\nWrite each message as something the shopper would plausibly say \u2014 it appears\\nin the transcript as their message.\\n","recipes/campaign-hero.md":"# Campaign hero with deliberate variation\\n\\nCache-friendly variation: key the prompt to a low-cardinality period, not to\\ntime itself.\\n\\n```js\\n// ISO week number \u2192 one generation per store per week, shared by everyone.\\nconst week = (d => {\\n  const t = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));\\n  t.setUTCDate(t.getUTCDate() + 4 - (t.getUTCDay() || 7));\\n  return `${t.getUTCFullYear()}-W${Math.ceil((((t - Date.UTC(t.getUTCFullYear(), 0, 1)) / 864e5) + 1) / 7)}`;\\n})(new Date());\\n\\nconst data = await window.GreatStore.generateStructuredContent(\\n  {\\n    type: \\"object\\",\\n    properties: {\\n      headline: { type: \\"string\\", maxLength: 60 },\\n      subline: { type: \\"string\\", maxLength: 120 },\\n      featuredProductName: { type: \\"string\\", nullable: true },\\n      ctaChatMessage: { type: \\"string\\", maxLength: 120 },\\n    },\\n    required: [\\"headline\\", \\"subline\\", \\"ctaChatMessage\\"],\\n  },\\n  `Variant ${week}. Write a homepage hero for this store: a headline and ` +\\n    `subline spotlighting a real product or category that fits the current ` +\\n    `season, plus ctaChatMessage \u2014 the first-person message a shopper ` +\\n    `would send to start shopping for it.`\\n);\\n\\nheroHeadline.textContent = data.headline;\\nheroSubline.textContent = data.subline;\\nheroCta.addEventListener(\\"click\\", () =>\\n  window.GreatStore.sendMessage(data.ctaChatMessage)\\n);\\nhero.hidden = false;\\n```\\n","recipes/comparison-table.md":"# Collection-page comparison table\\n\\n```html\\n<section id=\\"gs-compare\\" hidden>\\n  <h3>Quick comparison</h3>\\n  <table><thead id=\\"gsc-head\\"></thead><tbody id=\\"gsc-body\\"></tbody></table>\\n</section>\\n\\n<script>\\n  (async () => {\\n    if (!window.GreatStore?.generateStructuredContent) return;\\n    const collection = \\"winter jackets\\"; // \u2190 your collection name\\n    try {\\n      const data = await window.GreatStore.generateStructuredContent(\\n        {\\n          type: \\"object\\",\\n          properties: {\\n            criteria: {\\n              type: \\"array\\", minItems: 2, maxItems: 4,\\n              items: { type: \\"string\\", maxLength: 25 },\\n            },\\n            rows: {\\n              type: \\"array\\", minItems: 2, maxItems: 4,\\n              items: {\\n                type: \\"object\\",\\n                properties: {\\n                  productName: { type: \\"string\\" },\\n                  bestFor: { type: \\"string\\", maxLength: 60 },\\n                  values: {\\n                    type: \\"array\\",\\n                    items: { type: \\"string\\", maxLength: 60 },\\n                  },\\n                },\\n                required: [\\"productName\\", \\"bestFor\\", \\"values\\"],\\n              },\\n            },\\n          },\\n          required: [\\"criteria\\", \\"rows\\"],\\n        },\\n        `The shopper is browsing the \\"${collection}\\" collection. Pick the ` +\\n          `3-4 most representative products and compare them. Choose the ` +\\n          `criteria a shopper actually decides on for this category. ` +\\n          `\\"values\\" must align with \\"criteria\\" by index. Add a one-line ` +\\n          `\\"bestFor\\" verdict per product. Only use real products and facts.`\\n      );\\n\\n      const head = document.getElementById(\\"gsc-head\\");\\n      const hr = document.createElement(\\"tr\\");\\n      for (const h of [\\"Product\\", ...data.criteria, \\"Best for\\"]) {\\n        const th = document.createElement(\\"th\\");\\n        th.textContent = h;\\n        hr.append(th);\\n      }\\n      head.append(hr);\\n\\n      const body = document.getElementById(\\"gsc-body\\");\\n      for (const row of data.rows) {\\n        const tr = document.createElement(\\"tr\\");\\n        const cells = [row.productName, ...(row.values ?? []), row.bestFor];\\n        for (let i = 0; i < data.criteria.length + 2; i++) {\\n          const td = document.createElement(\\"td\\");\\n          td.textContent = cells[i] ?? \\"\u2014\\";\\n          tr.append(td);\\n        }\\n        body.append(tr);\\n      }\\n      document.getElementById(\\"gs-compare\\").hidden = false;\\n    } catch {}\\n  })();\\n</script>\\n```\\n\\nNote the index-aligned `values`/`criteria` trick and the `?? \\"\u2014\\"` guard \u2014\\ngrounding means a value the catalog can\'t support may be missing.\\n","recipes/complete-the-look.md":"# \\"Complete the look\\" cross-sell strip\\n\\n```js\\nconst data = await window.GreatStore.generateStructuredContent(\\n  {\\n    type: \\"object\\",\\n    properties: {\\n      intro: { type: \\"string\\", maxLength: 90 },\\n      picks: {\\n        type: \\"array\\", minItems: 2, maxItems: 4,\\n        items: {\\n          type: \\"object\\",\\n          properties: {\\n            productName: { type: \\"string\\" },\\n            reason: { type: \\"string\\", maxLength: 90 },\\n            imageUrl: { type: \\"string\\", nullable: true },\\n            productUrl: { type: \\"string\\", nullable: true },\\n          },\\n          required: [\\"productName\\", \\"reason\\"],\\n        },\\n      },\\n    },\\n    required: [\\"picks\\"],\\n  },\\n  `The shopper is viewing \\"${productName}\\". From the store\'s real catalog, ` +\\n    `pick 2-4 products that genuinely pair with it and say why each one ` +\\n    `completes the look or use-case. Include image and product URLs only ` +\\n    `if known.`\\n);\\n\\nfor (const pick of data.picks) {\\n  const card = document.createElement(\\"a\\");\\n  if (pick.productUrl) card.href = pick.productUrl;\\n  if (pick.imageUrl) {\\n    const img = document.createElement(\\"img\\");\\n    img.src = pick.imageUrl;\\n    img.alt = pick.productName;\\n    img.loading = \\"lazy\\";\\n    card.append(img);\\n  }\\n  const name = document.createElement(\\"strong\\");\\n  name.textContent = pick.productName;\\n  const why = document.createElement(\\"p\\");\\n  why.textContent = pick.reason;\\n  card.append(name, why);\\n  strip.append(card);\\n}\\nstrip.hidden = false;\\n```\\n\\n`imageUrl`/`productUrl` are `nullable` and optional in the render \u2014 the\\ngrounding contract means they\'re only present when the catalog actually has\\nthem. Never `require` URLs.\\n","recipes/custom-chat-button.md":"# Custom chat button synced to panel state\\n\\nReplace the default launcher with your own UI using the lifecycle surface:\\n\\n```js\\nconst gs = window.GreatStore;\\nconst btn = document.getElementById(\\"my-chat-button\\");\\n\\ngs.ready.then(() => { btn.hidden = false; });\\nbtn.addEventListener(\\"click\\", () => gs.toggle());\\n\\ngs.on(\\"open\\",  () => btn.setAttribute(\\"aria-expanded\\", \\"true\\"));\\ngs.on(\\"close\\", () => btn.setAttribute(\\"aria-expanded\\", \\"false\\"));\\n```\\n\\n`ready` resolves even when `.then()` is attached after mount, so script\\nordering doesn\'t matter. The `open`/`close` events also fire for opens the\\nSDK triggers itself (`sendMessage`, `?gs_chat=open`), keeping your button\\nstate honest.\\n","recipes/gift-finder-funnel.md":"# Gift finder funnel (teaser \u2192 conversation \u2192 action)\\n\\nThe flagship pattern: an AI-generated quiz card in your design, whose answers\\ndrop the shopper into a chat that can act on the page.\\n\\n```html\\n<section id=\\"gift-finder\\" hidden>\\n  <h3 id=\\"gf-question\\"></h3>\\n  <div id=\\"gf-options\\"></div>\\n</section>\\n\\n<script>\\n  (async () => {\\n    const gs = window.GreatStore;\\n    if (!gs?.generateStructuredContent) return;\\n\\n    // Tools the resulting conversation can use. Registered once the\\n    // SDK is ready (so document.modelContext exists); the assistant\\n    // discovers them on its next turn automatically.\\n    gs.ready.then(() => {\\n      document.modelContext.registerTool({\\n        name: \\"go_to_product\\",\\n        description:\\n          \\"Navigate the shopper to a product page on this site. Use when \\" +\\n          \\"the shopper picks a product they want to see.\\",\\n        inputSchema: {\\n          type: \\"object\\",\\n          properties: { url: { type: \\"string\\" } },\\n          required: [\\"url\\"],\\n        },\\n        execute({ url }) {\\n          const u = new URL(String(url), location.origin);\\n          if (u.origin !== location.origin) throw new Error(\\"Only same-site URLs allowed\\");\\n          location.assign(u.href);\\n          return { content: [{ type: \\"text\\", text: \\"Navigating.\\" }] };\\n        },\\n      });\\n    });\\n\\n    try {\\n      const data = await gs.generateStructuredContent(\\n        {\\n          type: \\"object\\",\\n          properties: {\\n            question: { type: \\"string\\", maxLength: 80 },\\n            options: {\\n              type: \\"array\\",\\n              minItems: 3,\\n              maxItems: 4,\\n              items: {\\n                type: \\"object\\",\\n                properties: {\\n                  label: { type: \\"string\\", maxLength: 30 },\\n                  chatMessage: { type: \\"string\\", maxLength: 140 },\\n                },\\n                required: [\\"label\\", \\"chatMessage\\"],\\n              },\\n            },\\n          },\\n          required: [\\"question\\", \\"options\\"],\\n        },\\n        \\"Create one engaging gift-finder opening question for this store, \\" +\\n          \\"with 3-4 answer options that map to real areas of the catalog. \\" +\\n          \\"For each option also write chatMessage: the message a shopper \\" +\\n          \\"would send to a shopping assistant after picking it, phrased in \\" +\\n          \\"first person (e.g. \\\\\\"I\'m shopping for my dad who loves hiking\\\\\\").\\"\\n      );\\n\\n      document.getElementById(\\"gf-question\\").textContent = data.question;\\n      const wrap = document.getElementById(\\"gf-options\\");\\n      for (const opt of data.options) {\\n        const btn = document.createElement(\\"button\\");\\n        btn.type = \\"button\\";\\n        btn.textContent = opt.label;\\n        btn.addEventListener(\\"click\\", () => gs.sendMessage(opt.chatMessage));\\n        wrap.append(btn);\\n      }\\n      document.getElementById(\\"gift-finder\\").hidden = false;\\n    } catch {}\\n  })();\\n</script>\\n```\\n\\nWhy it works: the teaser costs one cached generation for all visitors, each\\nclick opens a conversation that already has direction, and `go_to_product`\\nlets the conversation end on a product page instead of in a dead end.\\n","recipes/launchers.md":"# GreatStore launchers \u2014 AI question chips\\n\\nA horizontally scrollable row of chips, each a highly engaging first-person\\nquestion about the current page. Tapping a chip sends that question to the\\nassistant \u2014 `generateStructuredContent` writes the questions, `sendMessage`\\nfires them. Simple yet effective: it works on every page type, costs one\\ncached generation per page, and every tap starts a conversation that already\\nhas a great opening line.\\n\\n```html\\n<div id=\\"gs-launchers\\" hidden></div>\\n\\n<style>\\n  #gs-launchers {\\n    display: flex;\\n    gap: 0.5em;\\n    overflow-x: auto;\\n    -webkit-overflow-scrolling: touch;\\n    scrollbar-width: none;\\n    padding: 0.5em 1em;\\n  }\\n  #gs-launchers::-webkit-scrollbar { display: none; }\\n  #gs-launchers button {\\n    flex: 0 0 auto;\\n    white-space: nowrap;\\n    border: 1px solid #ddd;\\n    border-radius: 999px;\\n    padding: 0.5em 0.9em;\\n    background: #fff;\\n    cursor: pointer;\\n  }\\n</style>\\n\\n<script>\\n  (async () => {\\n    const gs = window.GreatStore;\\n    if (!gs?.generateStructuredContent) return;\\n    try {\\n      const data = await gs.generateStructuredContent(\\n        {\\n          type: \\"object\\",\\n          properties: {\\n            launchers: {\\n              type: \\"array\\", minItems: 4, maxItems: 6,\\n              items: {\\n                type: \\"object\\",\\n                properties: {\\n                  chip: { type: \\"string\\", maxLength: 32 },\\n                  question: { type: \\"string\\", maxLength: 140 },\\n                },\\n                required: [\\"chip\\", \\"question\\"],\\n              },\\n            },\\n          },\\n          required: [\\"launchers\\"],\\n        },\\n        `The shopper is on the page \\"${document.title}\\". Write 4-6 launcher ` +\\n          `chips for a shopping assistant. For each, \\"question\\" is a highly ` +\\n          `engaging first-person question this shopper would genuinely want ` +\\n          `answered on this page \u2014 specific to its product, category, or ` +\\n          `content, never generic \u2014 and \\"chip\\" is a 2-4 word teaser of it. ` +\\n          `Vary the angles: fit and use, comparisons, gifting, care, what\'s ` +\\n          `popular.`\\n      );\\n\\n      const row = document.getElementById(\\"gs-launchers\\");\\n      for (const { chip, question } of data.launchers) {\\n        const btn = document.createElement(\\"button\\");\\n        btn.type = \\"button\\";\\n        btn.textContent = chip;\\n        btn.title = question;\\n        btn.addEventListener(\\"click\\", () => gs.sendMessage(question));\\n        row.append(btn);\\n      }\\n      row.hidden = false;\\n    } catch {}\\n  })();\\n</script>\\n```\\n\\nWhy it works:\\n\\n- **The chip is the teaser, the question is the payload.** A 2-4 word chip\\n  scans instantly; the full first-person question lands in the transcript\\n  reading like something the shopper typed, and gives the assistant a\\n  well-formed prompt. The `title` attribute previews the full question on\\n  hover.\\n- **Per-page for free.** The page URL is part of the generation context and\\n  the cache key, so one site-wide snippet yields different chips on every\\n  page \u2014 each cached for all visitors.\\n- **Placement is the lever.** Under the product title, above the grid on\\n  collections, at the end of a blog post \u2014 wherever a shopper pauses to\\n  wonder, the chips name the question for them.\\n\\nTips:\\n\\n- Inline the product or collection name into the prompt when the platform\\n  exposes it \u2014 it beats relying on `document.title`.\\n- Restyle the chips to the site\'s design system; the CSS above is just the\\n  scroll mechanics (flex row, `overflow-x: auto`, hidden scrollbars,\\n  `white-space: nowrap`).\\n- Resist adding more than ~6 chips \u2014 a launcher row is an invitation, not a\\n  sitemap.\\n","recipes/page-action-suite.md":"# Page-action suite (WebMCP)\\n\\nGive every conversation on the site real capabilities. Register once in a\\nshared snippet, after the SDK is ready (which guarantees\\n`document.modelContext` exists):\\n\\n```js\\nwindow.GreatStore?.ready.then(() => {\\n  const text = (value) => ({\\n    content: [{ type: \\"text\\", text: JSON.stringify(value) }],\\n  });\\n\\n  document.modelContext.registerTool({\\n    name: \\"get_cart\\",\\n    description:\\n      \\"Read the shopper\'s current cart on this site: items, quantities, \\" +\\n      \\"and totals. Use before answering any cart question.\\",\\n    inputSchema: { type: \\"object\\", properties: {} },\\n    async execute() {\\n      return text(await (await fetch(\\"/cart.js\\")).json());\\n    },\\n  });\\n\\n  document.modelContext.registerTool({\\n    name: \\"add_to_cart\\",\\n    description:\\n      \\"Add a product variant to the cart on this site. Use when the \\" +\\n      \\"shopper asks to add or buy something. Confirm the variant with \\" +\\n      \\"the shopper first if ambiguous.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        variantId: { type: \\"string\\" },\\n        quantity: { type: \\"integer\\", minimum: 1, maximum: 10 },\\n      },\\n      required: [\\"variantId\\"],\\n    },\\n    async execute({ variantId, quantity }) {\\n      if (!variantId) throw new Error(\\"variantId is required\\");\\n      const res = await fetch(\\"/cart/add.js\\", {\\n        method: \\"POST\\",\\n        headers: { \\"Content-Type\\": \\"application/json\\" },\\n        body: JSON.stringify({ id: variantId, quantity: quantity ?? 1 }),\\n      });\\n      if (!res.ok) throw new Error(`Could not add to cart (${res.status})`);\\n      document.dispatchEvent(new CustomEvent(\\"cart:refresh\\"));\\n      return text(await res.json());\\n    },\\n  });\\n\\n  document.modelContext.registerTool({\\n    name: \\"get_current_page\\",\\n    description:\\n      \\"Read what page the shopper is currently on, including structured \\" +\\n      \\"product data when on a product page.\\",\\n    inputSchema: { type: \\"object\\", properties: {} },\\n    execute() {\\n      return text({\\n        url: location.href,\\n        title: document.title,\\n        productJson: document.querySelector(\\"#product-json\\")?.textContent ?? null,\\n      });\\n    },\\n  });\\n});\\n```\\n\\nPrinciples at work: throw on failure (the assistant explains and recovers),\\nreturn fresh state after mutations (the assistant confirms accurately), cap\\nquantities in the schema, and notify your own UI (`cart:refresh`) so the\\npage reflects what the AI did.\\n\\nFor a product-page-only tool, register with an `AbortSignal` and abort on\\nSPA navigation:\\n\\n```js\\nconst ac = new AbortController();\\ndocument.modelContext.registerTool(reviewsTool, { signal: ac.signal });\\nrouter.onLeave(\\"/products/:handle\\", () => ac.abort());\\n```\\n","recipes/product-faq.md":"# Product FAQ accordion\\n\\n```js\\nconst data = await window.GreatStore.generateStructuredContent(\\n  {\\n    type: \\"object\\",\\n    properties: {\\n      faqs: {\\n        type: \\"array\\", minItems: 3, maxItems: 5,\\n        items: {\\n          type: \\"object\\",\\n          properties: {\\n            question: { type: \\"string\\", maxLength: 90 },\\n            answer: { type: \\"string\\", maxLength: 300 },\\n          },\\n          required: [\\"question\\", \\"answer\\"],\\n        },\\n      },\\n    },\\n    required: [\\"faqs\\"],\\n  },\\n  `Generate the questions shoppers most plausibly have before buying the ` +\\n    `product \\"${productName}\\", with accurate answers grounded in the real ` +\\n    `product details and store policies. Skip any question the store data ` +\\n    `can\'t answer confidently.`\\n);\\n\\nconst wrap = document.getElementById(\\"gs-faq\\");\\nfor (const { question, answer } of data.faqs) {\\n  const details = document.createElement(\\"details\\");\\n  const summary = document.createElement(\\"summary\\");\\n  summary.textContent = question;\\n  const p = document.createElement(\\"p\\");\\n  p.textContent = answer;\\n  details.append(summary, p);\\n  wrap.append(details);\\n}\\nwrap.hidden = false;\\n```\\n\\nEngagement bonus \u2014 append a hand-off row so unanswered questions become\\nconversations:\\n\\n```js\\nconst ask = document.createElement(\\"button\\");\\nask.type = \\"button\\";\\nask.textContent = \\"Have a different question? Ask us\\";\\nask.addEventListener(\\"click\\", () =>\\n  window.GreatStore.sendMessage(`I have a question about \\"${productName}\\".`)\\n);\\nwrap.append(ask);\\n```\\n","references/agents-and-mcp.md":"# AI agents and the store\'s MCP endpoints\\n\\nBeyond the widget, every GreatStore store is reachable by AI agents directly\\nover the Model Context Protocol. Three URLs, all on the store\'s subdomain,\\nnone requiring authentication:\\n\\n| URL | What it is |\\n|---|---|\\n| `https://<slug>.greatstore.ai/.well-known/mcp/server-card.json` | Standard MCP server card \u2014 machine-readable discovery document for the store. |\\n| `https://<slug>.greatstore.ai/mcp` | The store\'s **shopping tools** over MCP \u2014 product search and related catalog actions, the same capabilities the assistant itself shops with. |\\n| `https://<slug>.greatstore.ai/admin-mcp` | A **documentation server for coding agents**: its tools return usage docs for the `gs` CLI (login, init, build, push, publish). |\\n\\n## Shopping tools \u2014 `/mcp`\\n\\nConnect any MCP-capable agent to let it browse and shop the store\\nprogrammatically. This is the integration point for agentic-shopping\\nclients, comparison bots, or the merchant\'s own automations that need live\\ncatalog answers.\\n\\n## CLI docs for coding agents \u2014 `/admin-mcp`\\n\\nA stateless HTTP MCP whose tools hand back markdown documentation for `gs`\\nCLI commands. When accessed via the store\'s subdomain, every example comes\\npre-pinned to that store\'s slug, so the agent never has to ask which store\\nto target.\\n\\n```\\nclaude mcp add --transport http greatstore https://my-store.greatstore.ai/admin-mcp\\n```\\n\\nUseful when a coding agent is shipping chat components\\n([chat-components.md](chat-components.md)) and needs the exact command for\\nthe next step. If this skill is installed, the agent already has the\\nworkflow \u2014 the MCP is the self-serve alternative for agents that don\'t.\\n\\n## What to use when\\n\\n- **Building the merchant\'s site** \u2192 this skill\'s other references (the SDK,\\n  structured content, page tools).\\n- **A coding agent shipping chat components** \u2192 the `gs` CLI, with\\n  `/admin-mcp` as its built-in documentation.\\n- **An agent that needs to *shop* the store** (search products, read catalog\\n  data) from outside any web page \u2192 `/mcp`.\\n","references/chat-components.md":"# Custom chat components \u2014 authoring with the `gs` CLI\\n\\nRemote components are React components the assistant renders **inside the\\nconversation** \u2014 product configurators, quizzes, size guides, booking forms,\\nanything richer than text. Each component is an AI-callable tool: the\\nmanifest\'s `description` tells the assistant *when* to show it, its\\n`inputSchema` declares the props the assistant fills in, and a `displayMode`\\npicks where it appears.\\n\\nAuthoring requires store-owner access (`gs login` signs in with the store\\nowner\'s account).\\n\\n## Workflow\\n\\n```\\nnpm install -g @greatstore/cli     # or npx @greatstore/cli <command>\\ngs login                           # browser sign-in\\ngs init --store my-store           # scaffold a project root\\ncd <project> && npm install\\ngs init size_guide                 # scaffold components/size_guide/\\n# \u2026 edit components/size_guide/{component.tsx,manifest.json} \u2026\\ngs build                           # bundle every component\\ngs push                            # upload changed components as drafts\\ngs publish size_guide              # promote to live\\n```\\n\\n`gs list` shows what\'s deployed (with dashboard links); `gs pull` round-trips\\nremote components back to disk. `gs push` hashes components and only uploads\\nwhat changed.\\n\\nThe scaffold writes an `AGENTS.md` into the project (with `CLAUDE.md` /\\n`GEMINI.md` symlinked) containing the complete design rules and brand\\nvariable table \u2014 your coding agent picks it up automatically when working in\\nthe project. The store\'s `/admin-mcp` endpoint serves the same CLI docs to\\nagents over MCP (see [agents-and-mcp.md](agents-and-mcp.md)).\\n\\n## `manifest.json`\\n\\n```json\\n{\\n  \\"name\\": \\"size_guide\\",\\n  \\"displayName\\": \\"Size guide\\",\\n  \\"description\\": \\"Interactive size guide. Show when the shopper asks about sizing or fit for apparel.\\",\\n  \\"displayMode\\": \\"inline\\",\\n  \\"inputSchema\\": {\\n    \\"type\\": \\"object\\",\\n    \\"properties\\": {\\n      \\"productName\\": { \\"type\\": \\"string\\" },\\n      \\"category\\": { \\"type\\": \\"string\\" }\\n    },\\n    \\"required\\": [\\"productName\\"]\\n  }\\n}\\n```\\n\\n| Field | Meaning |\\n|---|---|\\n| `name` | Tool name, snake_case (`^[a-z][a-z0-9_]*$`), matches the folder under `components/`. |\\n| `displayName` | Friendly label shown in chat UI. |\\n| `description` | **Load-bearing** \u2014 how the assistant decides when to render the component. Say what it shows *and* when to use it, like any good tool description. |\\n| `displayMode` | Where it renders \u2014 see below. |\\n| `inputSchema` | JSON Schema for the props the assistant fills. Keep it tight; required fields the AI can\'t infer cause bad calls. |\\n| `async` | Set `true` for backend-backed components (see Async below). |\\n\\n### Display modes\\n\\n- `inline` \u2014 a bubble inside the chat transcript; persists with the message\\n  log.\\n- `over-input` \u2014 floats above the chat input (like a question overlay);\\n  cleared by the next user turn or an explicit close.\\n- `fullscreen` \u2014 takes over the full preview surface; persists until the\\n  next widget-emitting tool call or an explicit close.\\n\\n## The component contract\\n\\n`component.tsx` default-exports a React component. Its props are the\\n`inputSchema` fields the assistant filled, plus three GreatStore-injected\\nlifecycle props (always present):\\n\\n| Prop | What it does |\\n|---|---|\\n| `onSendMessage(text)` | Send text into the chat as if the shopper typed it \u2014 lets the component drive the conversation (\\"Selected size M, what\'s the return policy?\\"). |\\n| `onCallTool(name, args)` | Chain into another remote-component tool by name. |\\n| `onClose()` | Dismiss the host slot. `over-input` clears the overlay, `fullscreen` reverts the pane, `inline` is a no-op. |\\n\\n```tsx\\nimport React from \\"react\\";\\n\\ninterface Props {\\n  productName: string;\\n  category?: string;\\n  onSendMessage: (text: string) => void;\\n  onCallTool: (name: string, args: Record<string, unknown>) => void;\\n  onClose: () => void;\\n}\\n\\nexport default function SizeGuide({ productName, onSendMessage }: Props) {\\n  return (\\n    <div\\n      style={{\\n        padding: \\"1em\\",\\n        border: \\"1px solid var(--color-border-default)\\",\\n        borderRadius: \\"var(--radius-lg)\\",\\n        background: \\"var(--color-surface)\\",\\n        color: \\"var(--color-foreground)\\",\\n        fontFamily: \\"var(--font-sans)\\",\\n      }}\\n    >\\n      {/* \u2026 sizes for {productName} \u2026 */}\\n      <button onClick={() => onSendMessage(`Size M of \\"${productName}\\" \u2014 is it in stock?`)}>\\n        Check size M\\n      </button>\\n    </div>\\n  );\\n}\\n```\\n\\n## Design rules (non-negotiable)\\n\\nComponents render inside arbitrary publisher pages *and* the GreatStore\\nstorefront; you control neither the host\'s root font size nor its colors.\\n\\n1. **Size in `em`, never `rem`** \u2014 `rem` resolves against the host page\'s\\n   root font size, which is arbitrary (`html { font-size: 8px }` breaks every\\n   `rem` dimension). `em` stays self-consistent anywhere. Borders may stay\\n   `px`.\\n2. **Never hardcode colors, fonts, or radii** \u2014 read the brand CSS variables\\n   GreatStore injects (`--color-primary`, `--color-surface`,\\n   `--color-foreground`, `--color-border-default`, `--font-sans`,\\n   `--radius-lg`, \u2026) so the component restyles itself with the store\'s\\n   theme. The scaffolded `AGENTS.md` has the full variable table.\\n\\n## Async components (backend-backed data)\\n\\nIf a component must load data before it can render correctly, don\'t render a\\nshell and fetch in `useEffect` \u2014 set `\\"async\\": true` in the manifest and\\nexport an **async** default. GreatStore shows its own loading state, awaits\\nyour promise, and renders what it resolves to.\\n\\nA thrown error is a **retry signal**: the assistant sees it and usually\\nre-calls the tool. So only throw when a *different* call could help:\\n\\n1. Validate the AI-passed props first and throw on bad input \u2014 the AI can\\n   fix the args and retry. (Don\'t validate the API\'s *output* and throw: the\\n   AI can\'t fix your backend, it\'ll just loop.)\\n2. Throw on failures where retrying differently could succeed, and say what\\n   to change (e.g. empty search \u2192 `\\"no results for X \u2014 try a broader keyword\\"`).\\n3. For idempotent failures (500, timeout, missing record) render a graceful\\n   fallback instead of throwing \u2014 re-running the same call changes nothing.\\n\\n```tsx\\nexport default async function Results(props: Props) {\\n  if (!props.query?.trim()) throw new Error(\\"missing required prop: query\\");\\n  const res = await fetch(`/api/search?q=${encodeURIComponent(props.query)}`);\\n  if (res.ok) {\\n    const { results } = await res.json();\\n    if (results.length === 0)\\n      throw new Error(`no results for \\"${props.query}\\" \u2014 try a broader keyword`);\\n    return <ul>{/* render results */}</ul>;\\n  }\\n  return <p>Couldn\'t load results right now.</p>; // idempotent: don\'t throw\\n}\\n```\\n\\n## When to build a component vs. the other facets\\n\\n- Content for the **merchant\'s page** \u2192 `generateStructuredContent`\\n  ([structured-content.md](structured-content.md)).\\n- Letting the assistant **act on the page** \u2192 WebMCP page tools\\n  ([embed-api.md](embed-api.md)).\\n- Rich, interactive UI **inside the conversation itself**, available on the\\n  storefront and every embed without page changes \u2192 a chat component.\\n","references/embed-api.md":"# `window.GreatStore` API reference\\n\\n## Setup\\n\\n```html\\n<script src=\\"https://my-store.greatstore.ai/embed.js\\"></script>\\n```\\n\\nOne script tag, anywhere on the page (end of `<body>` preferred), with the\\nstore\'s slug in the host. The `window.GreatStore` object exists synchronously\\nonce the script executes; every method below is safe to call before the chat\\nUI has finished loading \u2014 pre-mount calls are queued and replayed in order\\nonce it mounts. The SDK pre-warms its chat bundle in the background\\nautomatically; the panel stays closed until `open()` / `toggle()` /\\n`sendMessage()` is called or the shopper clicks the launcher.\\n\\nRequirements:\\n\\n- The page\'s domain must be in the store\'s **allowed domains** (GreatStore\\n  store settings) \u2014 see Troubleshooting below for the failure signature.\\n- If the store also wants push notifications, host `gs.js` at the site root\\n  and load that instead of `embed.js` \u2014 it injects the embed for you. See\\n  [push-notifications.md](push-notifications.md).\\n\\n## Properties\\n\\n| Property | Type | Description |\\n|---|---|---|\\n| `slug` | `string` | The store identifier the script was loaded for. |\\n| `host` | `string` | `\\"greatstore.ai\\"`. |\\n| `embedHost` | `string` | Origin the embed assets load from, e.g. `https://<slug>.greatstore.ai`. |\\n| `ready` | `Promise<void>` | Resolves when the chat UI has mounted and `open()` would render instantly. Resolved promises replay, so `.then()` works no matter when it\'s attached. The recommended readiness signal. |\\n| `isReady` | `boolean` | Synchronous alternative to `ready`. `false` until mount. |\\n\\nA `greatstore:ready` `CustomEvent` (with the SDK object as `detail`) is also\\ndispatched on `window` at the moment `ready` resolves, for declarative\\ntooling. Unlike the promise, the listener must be attached before mount\\ncompletes \u2014 attach it before (or immediately after) the embed script tag.\\n\\n## Methods\\n\\n### `load(): void`\\n\\nPre-warms the chat bundle and identity in the background without opening the\\npanel. Called automatically when `embed.js` runs, so you rarely need it.\\nIdempotent.\\n\\n### `open(): void` / `close(): void` / `toggle(): void`\\n\\nOpen, close, or toggle the chat panel. On desktop the panel is a floating\\nside panel; under 768px viewport width it\'s a full-height drawer. All three\\nqueue if called before mount.\\n\\n### `sendMessage(text: string): void`\\n\\nSends `text` as the shopper\'s own visible chat message and **opens the panel\\nif it\'s closed**. The text is trimmed; empty or whitespace-only strings are\\nsilently dropped. Queues if called before mount.\\n\\nThis is the highest-leverage one-liner in the SDK: any element on the page\\ncan become a conversation entry point with context baked into the question.\\n\\n```js\\ndocument.querySelector(\\"#ask-fit\\").addEventListener(\\"click\\", () => {\\n  window.GreatStore.sendMessage(\\n    `I\'m looking at \\"${productName}\\" \u2014 how does the sizing run?`\\n  );\\n});\\n```\\n\\nBecause the message renders as if the shopper typed it, write it in the\\nshopper\'s voice. It is not a hidden-context channel \u2014 don\'t stuff it with\\ninvisible instructions or data dumps.\\n\\n### `on(event: string, handler: (...args) => void): () => void`\\n\\nSubscribe to SDK events. Returns an unsubscribe function. Listeners attached\\nbefore mount are queued and wired up at mount. Handler exceptions are caught\\nand reported \u2014 they won\'t break the chat.\\n\\nEvents emitted:\\n\\n| Event | Fired when |\\n|---|---|\\n| `\\"open\\"` | Panel transitions closed \u2192 open (including via `sendMessage` or the shopper\'s own click). |\\n| `\\"close\\"` | Panel transitions open \u2192 closed. |\\n\\n### `generateStructuredContent(schema: object, prompt: string): Promise<unknown>`\\n\\nGenerates JSON matching `schema` from `prompt`, grounded in the store\'s live\\ncatalog. Resolves to the generated data object itself. Rejects with `Error`\\non any failure (invalid input, decline, validation failure, rate limit,\\nnetwork). See [structured-content.md](structured-content.md) for the full\\ncontract, schema support, caching, and error semantics.\\n\\nAccepts either a plain JSON Schema object or any object exposing a\\n`.toJSONSchema()` method (e.g. Zod schemas) \u2014 the conversion is called for\\nyou.\\n\\nThrows synchronously (rejects) if `prompt` is not a non-empty string or\\n`schema` is not an object.\\n\\n### `enableNotifications(): Promise<{ ok: boolean }>`\\n\\nOpts this browser into Web Push notifications from the store. Requirements:\\n\\n- Must be called from a user gesture (e.g. a click handler).\\n- The site must host GreatStore\'s `gs.js` service-worker file. By default the\\n  SDK looks for it at `/gs.js`; if it\'s hosted elsewhere, point to it via an\\n  attribute on the embed script tag:\\n  `<script src=\\"\u2026/embed.js\\" data-push-sw-path=\\"/path/to/gs.js\\"></script>`.\\n\\nResolves `{ ok: true }` on success and `{ ok: false }` on any failure\\n(unsupported browser, no service worker hosted, permission denied). It never\\nrejects.\\n\\n## Page tools \u2014 WebMCP (`document.modelContext`)\\n\\nThe recommended way to expose page capabilities to the assistant is the\\nWebMCP standard. The GreatStore assistant discovers every tool registered on\\n`document.modelContext`, re-reading the list on each conversational turn \u2014\\nso tools registered mid-session appear on the next message without a reload.\\n\\n### Availability\\n\\nIf the browser implements WebMCP natively, `document.modelContext` is just\\nthere. Otherwise the SDK installs a spec-tracking polyfill on the page\\nautomatically \u2014 but asynchronously, so at your script\'s first run\\n`document.modelContext` may not exist yet. Two robust patterns:\\n\\n```js\\n// 1. Register once GreatStore is ready (polyfill is in place by then):\\nwindow.GreatStore?.ready.then(() => {\\n  document.modelContext.registerTool(/* \u2026 */);\\n});\\n\\n// 2. Or ship your own polyfill (npm: @mcp-b/webmcp-polyfill) and register\\n//    immediately \u2014 the SDK detects an existing implementation and uses it.\\n```\\n\\n(`navigator.modelContext` is a deprecated alias for the same object; use\\n`document.modelContext` in new code.)\\n\\n### `registerTool(tool, options?)`\\n\\n```ts\\ndocument.modelContext.registerTool(\\n  {\\n    name: string,                 // required, non-empty, unique on the page\\n    description: string,          // required \u2014 how the AI decides when to call it\\n    inputSchema?: object,         // JSON Schema for execute\'s args;\\n                                  // defaults to { type: \\"object\\", properties: {} }\\n    execute(args): Result | Promise<Result>,\\n  },\\n  options?: { signal?: AbortSignal },  // abort to unregister\\n);\\n```\\n\\n- **Result shape**: `execute` returns MCP content blocks \u2014\\n  `{ content: [{ type: \\"text\\", text: \\"\u2026\\" }] }`. For structured data,\\n  `JSON.stringify` it into `text`. Add `isError: true` to mark a handled\\n  failure.\\n- **Errors**: a thrown error or rejected promise is delivered to the\\n  assistant as a *failed* tool call carrying the error message \u2014 the\\n  assistant can explain or adapt. Errors never escape into your page.\\n- **Duplicate names throw.** To replace a tool, abort its registration first.\\n- **Unregistration is `AbortSignal`-driven**: pass `{ signal }` and call\\n  `abort()` when the tool\'s context goes away (SPA navigation, modal close).\\n  A pre-aborted signal skips registration. (A legacy\\n  `unregisterTool(name)` exists but is deprecated in the spec.)\\n- **Treat `args` as untrusted input**: values are AI-generated. Validate\\n  before passing to your own APIs, and never `eval` anything from them.\\n\\nA complete tool, registered once GreatStore is ready:\\n\\n```js\\nwindow.GreatStore?.ready.then(() => {\\n  document.modelContext.registerTool({\\n    name: \\"add_to_cart\\",\\n    description:\\n      \\"Add a product variant to the shopper\'s cart on this site. \\" +\\n      \\"Use when the shopper asks to add, buy, or get a product.\\",\\n    inputSchema: {\\n      type: \\"object\\",\\n      properties: {\\n        variantId: { type: \\"string\\" },\\n        quantity: { type: \\"integer\\", minimum: 1 },\\n      },\\n      required: [\\"variantId\\"],\\n    },\\n    async execute({ variantId, quantity }) {\\n      const res = await fetch(\\"/cart/add.js\\", {\\n        method: \\"POST\\",\\n        headers: { \\"Content-Type\\": \\"application/json\\" },\\n        body: JSON.stringify({ id: variantId, quantity: quantity ?? 1 }),\\n      });\\n      if (!res.ok) throw new Error(`Cart add failed (${res.status})`);\\n      const cart = await res.json();\\n      return { content: [{ type: \\"text\\", text: JSON.stringify(cart) }] };\\n    },\\n  });\\n});\\n```\\n\\nReturning the fresh cart state after the mutation lets the assistant confirm\\naccurately. Good tool families: cart (`get_cart`, `add_to_cart`), navigation\\n(`go_to_page`), page state (`get_current_product`, `apply_filters`), UI\\n(`highlight_section`, `scroll_to_reviews`).\\n\\nAnd a context-scoped tool, unregistered via `AbortSignal`:\\n\\n```js\\nconst ac = new AbortController();\\ndocument.modelContext.registerTool(\\n  {\\n    name: \\"get_product_reviews\\",\\n    description: \\"Read the reviews shown on the current product page.\\",\\n    inputSchema: { type: \\"object\\", properties: {} },\\n    execute: () => ({\\n      content: [{ type: \\"text\\", text: JSON.stringify(collectReviews()) }],\\n    }),\\n  },\\n  { signal: ac.signal },\\n);\\n\\n// On SPA route change away from the product page:\\nac.abort();\\n```\\n\\n## URL parameter: `?gs_chat=open`\\n\\nWhen the page URL carries `gs_chat=open`, the panel opens automatically once\\nthe embed mounts. The param is consumed and stripped from the URL via\\n`history.replaceState`, so a manual reload doesn\'t re-open the panel. Use it\\nin campaign links, emails, and post-login redirects.\\n\\n## Shopify login gate\\n\\nStores can enable a per-store \\"log in to chat\\" gate that applies **only to\\nthe embed** (never the store\'s GreatStore storefront). When enabled, the chat\\ninput is replaced with a login prompt until a Shopify customer signal is\\ndetected on the host page (standard Shopify globals/meta tags). The login\\nbutton sends the shopper through Shopify\'s customer login and back with\\n`?gs_chat=open` appended. This is a courtesy UX gate, not a security\\nboundary \u2014 don\'t rely on it to protect anything sensitive.\\n\\n## Troubleshooting\\n\\n| Symptom | Likely cause |\\n|---|---|\\n| Console: `[GreatStore] Chat is unavailable on <origin>\u2026 this domain isn\'t in the store\'s allowed domains` | The page\'s origin isn\'t in the store\'s allowed domains. Add it in store settings. Until then every SDK network call fails. |\\n| Console: `[GreatStore] Embed script must be loaded from <slug>.greatstore.ai/embed.js` | The script was copied/self-hosted instead of loaded from the store\'s embed URL. Always load it from `https://<slug>.greatstore.ai/embed.js`. |\\n| `generateStructuredContent` rejects with a rate-limit message | More than ~20 requests/minute from one visitor. Consolidate calls into fewer, richer schemas. |\\n| Panel won\'t auto-open on mobile after returning to the page | Intentional: the mobile drawer never auto-opens on resume \u2014 it would cover the content the shopper is reading. The transcript is preserved; they\'ll see it when they tap the launcher. |\\n| Tools registered but the assistant doesn\'t use them | Check the `description` \u2014 it\'s the only signal for *when* to call. Also confirm the registration ran (`document.modelContext` exists after `ready`) on the same page the conversation is on. |\\n","references/push-notifications.md":"# Web push re-engagement\\n\\nShoppers who opt in receive browser notifications from the store \u2014 under the\\nmerchant\'s own domain and branding, with the permission prompt shown inline\\non the merchant\'s page. Setup is two pieces: a single file hosted at the site\\nroot, and an opt-in button.\\n\\n## 1. Host `gs.js` at the site root\\n\\nDownload the store\'s loader and serve it at `/gs.js` on the merchant\'s\\ndomain:\\n\\n```\\nhttps://<slug>.greatstore.ai/gs.js   \u2192   https://www.merchant-site.com/gs.js\\n```\\n\\nAlways download it from the **store\'s own subdomain** \u2014 the file is built for\\nthat store; don\'t copy one from elsewhere.\\n\\nThen load it with one tag (replacing the `embed.js` tag \u2014 `gs.js` injects the\\nembed for you and registers itself as the service worker):\\n\\n```html\\n<script src=\\"/gs.js\\"></script>\\n```\\n\\nHosting this file is what enables push. Without it, push is simply off \u2014\\n`enableNotifications()` returns `{ ok: false }` and nothing else changes.\\n\\n### Non-root hosting\\n\\nIf the platform can\'t serve files at the site root (e.g. Shopify themes\\nserve assets under a path), keep the regular `embed.js` tag and point it at\\nwhere the file lives \u2014 the path must be on the merchant\'s own origin:\\n\\n```html\\n<script\\n  src=\\"https://my-store.greatstore.ai/embed.js\\"\\n  data-push-sw-path=\\"/cdn/shop/files/gs.js\\"\\n></script>\\n```\\n\\n## 2. Offer the opt-in from a user gesture\\n\\n```js\\noptInButton.addEventListener(\\"click\\", async () => {\\n  const { ok } = await window.GreatStore.enableNotifications();\\n  optInButton.hidden = ok;          // done \u2014 or quietly keep the button\\n});\\n```\\n\\nRules that make this work well:\\n\\n- **Always call it from a click** \u2014 browsers ignore or penalize permission\\n  prompts that aren\'t user-initiated, and the call is designed for gesture\\n  context.\\n- **Never prompt on page load.** Tie the button to a moment where\\n  notifications have obvious value (\\"Notify me when this is back in stock\\",\\n  post-purchase, after a chat conversation).\\n- `{ ok: false }` covers every failure the same way \u2014 unsupported browser, no\\n  `gs.js` hosted, permission denied. It never rejects, and there\'s no popup\\n  fallback. Design the button so a decline just leaves the page as it was;\\n  don\'t show an error.\\n- The promise resolving `{ ok: true }` means this browser is subscribed.\\n  There\'s nothing else to wire \u2014 notification delivery is handled by\\n  GreatStore.\\n","references/structured-content.md":"# `generateStructuredContent` deep dive\\n\\nAI-generated, catalog-grounded JSON for UI you render yourself \u2014 the chat\\npanel is not involved.\\n\\n```js\\nconst data = await window.GreatStore.generateStructuredContent(schema, prompt);\\n```\\n\\n- `schema` \u2014 a JSON Schema describing the output (or a Zod schema exposing\\n  `.toJSONSchema()`).\\n- `prompt` \u2014 what to generate.\\n- Resolves to **the generated JSON object itself**, matching the schema.\\n  Rejects with an `Error` on any failure.\\n\\n## The rules that make it work well\\n\\nEach is unpacked in the sections below; this is the checklist.\\n\\n1. **Top level must be an object.** Want a list? Wrap it:\\n   `{ type: \\"object\\", properties: { items: { type: \\"array\\", \u2026 } }, required: [\\"items\\"] }`.\\n2. **Steer with the prompt, not schema `description`s** \u2014 free-text schema\\n   fields are stripped before the AI sees them. Use self-explanatory\\n   property names (`benefitHeadline`, not `text1`).\\n3. **Only `require` what\'s guaranteed.** `required` is strictly enforced; if\\n   the catalog can\'t ground a required field the whole call can fail. Require\\n   structural fields, keep per-product details (image URLs, prices) optional,\\n   and make rendering tolerate missing values.\\n4. **The AI can\'t see your page.** If page context matters, put it in the\\n   prompt explicitly: `` `Generate care tips for the product \\"${productName}\\".` ``\\n5. **Responses are cached and shared** for up to ~24h across all visitors of\\n   the same page + prompt + schema. Keep prompts deterministic per page \u2014\\n   no timestamps, random values, or per-visitor data.\\n6. **Progressive enhancement, always.** Generate after the page renders into\\n   a hidden container, reveal on success, leave the fallback on error. Render\\n   generated strings via `textContent`, never `innerHTML`.\\n7. **One rich call beats many small ones** \u2014 there\'s a per-visitor rate limit\\n   (~20 requests/minute); fetch multiple surfaces with one combined schema.\\n\\n## What actually happens\\n\\n1. The SDK posts your schema + prompt to the store\'s GreatStore endpoint,\\n   along with the current **page URL and page title** (sent automatically \u2014\\n   you don\'t pass them, and you can\'t override them).\\n2. GreatStore first **researches**: it looks up real data from the store\'s\\n   live catalog (products, prices, availability, store info) using read-only\\n   lookups. The page URL/title serve as hints about which product or category\\n   to look up \u2014 they are *not* treated as a source of product data, and the\\n   page\'s DOM is never read.\\n3. The AI then fills your schema from the researched data, under a strict\\n   grounding contract: it must not invent product names, prices, images, IDs,\\n   or descriptions. Fields it can\'t ground are omitted or `null`.\\n4. The output is validated against your schema (with internal retries) before\\n   being returned and cached.\\n\\nThe request is anonymous by design \u2014 no shopper identity is attached \u2014 which\\nis what makes the response cacheable across all visitors.\\n\\n## Schema support\\n\\nTop level **must describe an object**: `type: \\"object\\"` (or a bare\\n`properties` / `anyOf`). To get a list, wrap it in an object property.\\n\\nSupported keywords (anything else is tolerated but ignored):\\n\\n- Types: `object`, `array`, `string`, `number`, `integer`, `boolean`, `null`\\n- Structure: `properties`, `required`, `items`, `additionalProperties`\\n- Choice: `enum`, `const`, `anyOf`, `nullable`\\n- Constraints: `minimum`, `maximum`, `minLength`, `maxLength`, `minItems`,\\n  `maxItems`, `pattern`, `format`, `default`\\n\\nValidation of the output is real: `required` is enforced, `enum`/`const`\\nmust match, numeric and length bounds are checked, and\\n`additionalProperties: false` rejects extra keys. Constraints are therefore a\\n*tool* \u2014 `maxItems: 4` reliably caps a list, `enum` reliably restricts a\\nfield \u2014 but every constraint is also a way for generation to fail, so apply\\nthem only where you\'d rather have no content than non-conforming content.\\n\\nZod schemas (or anything with a `.toJSONSchema()` method) are accepted and\\nconverted automatically.\\n\\n### Free-text schema fields are stripped\\n\\n`description`, `title`, and `example` are removed from the schema before the\\nAI sees it (they\'re a prompt-injection surface, so they\'re filtered\\nserver-side). Consequences:\\n\\n- Schema descriptions **cannot** steer generation. All steering lives in the\\n  prompt string.\\n- Property *names* are the only in-schema signal of intent \u2014 make them\\n  self-documenting: `ctaLabel`, `warmthRating`, `priceJustification`.\\n\\n## Prompting guide\\n\\nThe prompt is the entire instruction channel. A good prompt states, in order:\\n\\n1. **Context** \u2014 what page/situation the shopper is in, with concrete page\\n   data inlined (the AI can\'t see your DOM):\\n   `The shopper is viewing the product \\"Aurora Down Parka\\" on its product page.`\\n2. **Task** \u2014 what to generate, mapped loosely onto your schema\'s fields:\\n   `Write a heading and 3 reasons to love it; each reason has a short title and one supporting sentence.`\\n3. **Grounding expectations** \u2014 what store data to draw on:\\n   `Base every claim on the product\'s real materials, features, and price.`\\n4. **Voice** \u2014 tone and constraints:\\n   `Warm and concrete. No exclamation marks, no generic marketing filler.`\\n\\nAnti-patterns:\\n\\n- **Per-visitor or per-moment data in the prompt** (names, cart contents,\\n  timestamps, `Math.random()`): destroys the shared cache, so every visitor\\n  pays full generation latency and the store pays for every call. If you\\n  need per-shopper interaction, that\'s what `sendMessage` and the chat panel\\n  are for.\\n- **Asking it to read the page** (\\"summarize the reviews shown below\\") \u2014 it\\n  can\'t. Inline the data into the prompt instead, and keep what you inline\\n  stable per page so caching still works.\\n- **Asking for data you should fetch yourself** (exact live stock numbers,\\n  shipping ETAs). Use your own platform APIs for operational data; use\\n  GreatStore for *editorial intelligence over the catalog*.\\n- **Burying instructions in schema descriptions** \u2014 stripped, see above.\\n\\n## Caching: design for it\\n\\nResponses are cached server-side for up to **24 hours**, keyed by the\\ncombination of page URL + page title + prompt + schema, and shared across all\\nvisitors. (Tracking query params like `utm_*`/`gclid` and the URL fragment\\nare ignored, so ad-tagged visits share the campaign-free page\'s cache entry.\\nMeaningful params like `?product=123` are part of the key.)\\n\\nPractical consequences:\\n\\n- **First visitor pays, the rest fly.** Expect a few seconds on a cache miss\\n  and near-instant responses after. Design loading states for the miss case.\\n- **Same call on different pages = different content**, automatically \u2014 the\\n  page URL is in the key and in the AI\'s hints. A single site-wide snippet\\n  with a constant prompt yields per-page content for free.\\n- **Content refreshes roughly daily.** Don\'t build experiences that assume\\n  minute-level freshness.\\n- **To force different content, change the prompt or schema** (e.g. a\\n  campaign variant string that changes weekly \u2014 deliberate, low-cardinality\\n  variation is fine; per-visitor cardinality is not).\\n\\nThe catalog research underneath is also cached briefly, so several distinct\\nsurfaces on the same page (different prompts/schemas) stay cheap even on\\ncold cache.\\n\\n## Errors and how to handle them\\n\\nThe promise rejects with `new Error(message)`. The message is\\ndeveloper-facing \u2014 never render it to shoppers. Cases:\\n\\n| Case | Message you\'ll see | Retry? |\\n|---|---|---|\\n| Bad input (empty prompt, non-object schema) | thrown immediately by the SDK | Fix the call |\\n| Invalid schema shape | `Invalid schema: \u2026` | Fix the schema |\\n| AI declined the request | `The assistant declined to generate content for this request.` | No \u2014 permanent for that prompt/schema. Rework the prompt. |\\n| Output couldn\'t satisfy the schema | `Failed to produce valid structured content` | No \u2014 usually `required`/constraints demand data the catalog lacks. Loosen the schema. |\\n| Rate limit (~20/min per visitor) | rate-limit message | Later \u2014 and consolidate calls |\\n| Network / server | varies | Next page load |\\n\\nThe uniform shopper-facing strategy: render into a hidden-by-default\\ncontainer, reveal on success, leave hidden (or show your static fallback) on\\nany rejection. One `try/catch`, no case analysis needed unless you\'re\\nlogging.\\n\\n## Performance pattern\\n\\nFire generation as early as possible without blocking render \u2014 top of your\\ndeferred script, before other work:\\n\\n```js\\nconst highlightsPromise = window.GreatStore?.generateStructuredContent\\n  ? window.GreatStore.generateStructuredContent(schema, prompt).catch(() => null)\\n  : Promise.resolve(null);\\n\\n// \u2026rest of page setup\u2026\\n\\nconst data = await highlightsPromise;\\nif (data) renderHighlights(data);\\n```\\n\\nThe `.catch(() => null)` attached immediately avoids unhandled-rejection\\nnoise while keeping a single render path.\\n\\nFor multiple surfaces on one page, prefer **one call with a combined\\nschema** over parallel calls \u2014 it\'s one research pass, one cache entry, and\\nno rate-limit pressure:\\n\\n```js\\nconst schema = {\\n  type: \\"object\\",\\n  properties: {\\n    highlights: { /* \u2026 */ },\\n    faq:        { /* \u2026 */ },\\n    crossSell:  { /* \u2026 */ },\\n  },\\n  required: [\\"highlights\\"],\\n};\\n```\\n"}') : readTreeFromDisk(new URL("../../skill/", import.meta.url));
-  if (!cache2["SKILL.md"]) {
-    throw new Error("internal: agent skill tree is missing SKILL.md");
+// src/commands/configure/clear.ts
+async function clearAsset(args) {
+  const slug = resolveAdminStore(args);
+  const kind = parseAssetKind(args.positional[0]);
+  const url = `${apiBaseFor(slug)}/admin/configure/delete/${kind}`;
+  await request(url, { method: "POST", body: {} });
+  process.stdout.write(`Cleared ${kind} for ${slug}
+`);
+}
+
+// src/commands/configure/index.ts
+async function configureCommand(args) {
+  const sub = args.positional[0] ?? "show";
+  const rest = { ...args, positional: args.positional.slice(1) };
+  switch (sub) {
+    case "show":
+      await showConfig(rest);
+      return;
+    case "set":
+      await setConfig(rest);
+      return;
+    case "upload":
+      await uploadAsset(rest);
+      return;
+    case "clear":
+      await clearAsset(rest);
+      return;
+    default:
+      throw new Error(
+        `Unknown configure subcommand: ${sub}. Use \`gs configure [set|upload|clear]\`.`
+      );
   }
-  return cache2;
 }
 
-// src/commands/skill.ts
-function skillCommand(args) {
-  const global = flagBool(args.flags, "global");
-  const dirFlag = flagString(args.flags, "dir");
-  if (global && dirFlag !== void 0) {
-    throw new Error("Pass either --global or --dir <path>, not both.");
+// src/commands/connectors/shared.ts
+async function fetchConfig(slug) {
+  const url = `${apiBaseFor(slug)}/admin/connectors/config`;
+  return request(url);
+}
+function echoConnector(row) {
+  return {
+    id: row.id,
+    name: row.name,
+    url: row.url,
+    transport: row.transport,
+    authKind: row.authKind,
+    enabled: row.enabled,
+    profileUrl: row.profileUrl
+  };
+}
+async function saveConfig(slug, config, connectors, makerEnabled = config.makerEnabled) {
+  const url = `${apiBaseFor(slug)}/admin/connectors/save`;
+  return request(url, {
+    method: "POST",
+    body: {
+      makerEnabled,
+      // Maker's slot is only valid in [0, N]; removing a connector can
+      // shrink the list below the stored priority.
+      makerPriority: Math.min(config.makerPriority, connectors.length),
+      connectors
+    }
+  });
+}
+function findConnector(config, ref) {
+  const byId = config.connectors.find((r) => r.id === ref);
+  if (byId) return byId;
+  const byName = config.connectors.filter((r) => r.name === ref);
+  if (byName.length === 1) return byName[0];
+  if (byName.length > 1) {
+    const ids = byName.map((r) => r.id).join(", ");
+    throw new Error(
+      `Multiple connectors are named "${ref}". Use an id instead: ${ids}`
+    );
   }
-  const skillsDir = dirFlag !== void 0 ? path8.resolve(dirFlag) : global ? path8.join(os2.homedir(), ".claude", "skills") : path8.resolve(".claude", "skills");
-  const dest = path8.join(skillsDir, SKILL_DIR_NAME);
-  const existed = fs8.existsSync(path8.join(dest, "SKILL.md"));
-  for (const [rel, content] of Object.entries(loadSkill())) {
-    const full = path8.join(dest, ...rel.split("/"));
-    fs8.mkdirSync(path8.dirname(full), { recursive: true });
-    fs8.writeFileSync(full, content);
+  throw new Error(`No connector named "${ref}". Run \`gs connectors\` to see them.`);
+}
+
+// src/commands/connectors/list.ts
+async function listConnectors(args) {
+  const slug = resolveAdminStore(args);
+  const config = await fetchConfig(slug);
+  if (flagBool(args.flags, "json")) {
+    process.stdout.write(JSON.stringify(config, null, 2) + "\n");
+    return;
   }
   process.stdout.write(
-    [
-      `${existed ? "Updated" : "Installed"} the GreatStore agent skill at ${displayPath(dest)}.`,
-      "",
-      "Your coding agent picks it up automatically. Try asking it:",
-      `  "Add an AI-powered gift finder to my product page with GreatStore."`,
-      ""
-    ].join("\n")
+    `Maker MCP: ${config.makerEnabled ? "on" : "off"} (position ${config.makerPriority + 1})
+`
+  );
+  if (config.connectors.length === 0) {
+    process.stdout.write(`(no custom connectors in ${slug})
+`);
+    return;
+  }
+  const rows = config.connectors.map((r) => ({
+    name: r.name,
+    enabled: r.enabled ? "on" : "off",
+    auth: r.authKind === "bearer" ? r.hasToken ? "bearer" : "bearer (no token)" : "none",
+    url: r.url
+  }));
+  const widths = {
+    name: Math.max(4, ...rows.map((r) => r.name.length)),
+    enabled: Math.max(7, ...rows.map((r) => r.enabled.length)),
+    auth: Math.max(4, ...rows.map((r) => r.auth.length))
+  };
+  process.stdout.write(
+    `${pad2("NAME", widths.name)}  ${pad2("ENABLED", widths.enabled)}  ${pad2("AUTH", widths.auth)}  URL
+`
   );
+  for (const r of rows) {
+    process.stdout.write(
+      `${pad2(r.name, widths.name)}  ${pad2(r.enabled, widths.enabled)}  ${pad2(r.auth, widths.auth)}  ${r.url}
+`
+    );
+  }
 }
-function displayPath(dest) {
-  const home = os2.homedir();
-  if (dest.startsWith(home + path8.sep)) {
-    return `~${dest.slice(home.length)}`;
+function pad2(s, width) {
+  return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+
+// src/commands/connectors/add.ts
+async function addConnector(args) {
+  const slug = resolveAdminStore(args);
+  const name = args.positional[0];
+  if (!name) {
+    throw new Error("Usage: gs connectors add <name> --url <url> [--token <token>]");
+  }
+  const url = flagString(args.flags, "url");
+  if (!url) {
+    throw new Error("--url is required for `gs connectors add`.");
+  }
+  const token = flagString(args.flags, "token");
+  const profileUrl = flagString(args.flags, "profileUrl") ?? null;
+  const enabled = !flagBool(args.flags, "disabled");
+  if (!flagBool(args.flags, "force")) {
+    const probeUrl = `${apiBaseFor(slug)}/admin/connectors/probe`;
+    const probe = await request(
+      probeUrl,
+      {
+        method: "POST",
+        body: {
+          url,
+          ...token !== void 0 ? { token } : {},
+          ...profileUrl !== null ? { profileUrl } : {}
+        }
+      }
+    );
+    if (!probe.ok) {
+      throw new Error(
+        `Connector did not answer tool discovery${probe.error ? `: ${probe.error}` : ""}. Fix the URL/token or pass --force to save it anyway.`
+      );
+    }
+    process.stdout.write(`Probe ok \u2014 ${probe.toolCount ?? 0} tool(s) discovered.
+`);
+  }
+  const config = await fetchConfig(slug);
+  const next = {
+    // The server treats an id it doesn't recognize as "mint a fresh one".
+    id: "",
+    name,
+    url,
+    transport: "http",
+    authKind: token ? "bearer" : "none",
+    enabled,
+    profileUrl,
+    ...token !== void 0 ? { token } : {}
+  };
+  const saved = await saveConfig(slug, config, [
+    ...config.connectors.map(echoConnector),
+    next
+  ]);
+  const row = saved.connectors.find((r) => r.name === name);
+  process.stdout.write(
+    `Added connector "${name}"${row ? ` (${row.id})` : ""} \u2192 ${slug}
+`
+  );
+}
+
+// src/commands/connectors/remove.ts
+async function removeConnector(args) {
+  const slug = resolveAdminStore(args);
+  const ref = args.positional[0];
+  if (!ref) throw new Error("Usage: gs connectors remove <name|id>");
+  const config = await fetchConfig(slug);
+  const target = findConnector(config, ref);
+  const kept = config.connectors.filter((r) => r.id !== target.id).map(echoConnector);
+  await saveConfig(slug, config, kept);
+  process.stdout.write(`Removed connector "${target.name}" from ${slug}
+`);
+}
+
+// src/commands/connectors/enable.ts
+async function setConnectorEnabled(args, enabled) {
+  const slug = resolveAdminStore(args);
+  const ref = args.positional[0];
+  if (!ref) {
+    throw new Error(`Usage: gs connectors ${enabled ? "enable" : "disable"} <name|id>`);
+  }
+  const config = await fetchConfig(slug);
+  const target = findConnector(config, ref);
+  const next = config.connectors.map(
+    (r) => r.id === target.id ? { ...echoConnector(r), enabled } : echoConnector(r)
+  );
+  await saveConfig(slug, config, next);
+  process.stdout.write(
+    `Connector "${target.name}" is now ${enabled ? "enabled" : "disabled"}
+`
+  );
+}
+
+// src/commands/connectors/maker.ts
+async function setMaker(args) {
+  const slug = resolveAdminStore(args);
+  const state = args.positional[0];
+  if (state !== "on" && state !== "off") {
+    throw new Error("Usage: gs connectors maker on|off");
+  }
+  const config = await fetchConfig(slug);
+  await saveConfig(slug, config, config.connectors.map(echoConnector), state === "on");
+  process.stdout.write(`Maker MCP is now ${state}
+`);
+}
+
+// src/commands/connectors/health.ts
+async function healthCheck(args) {
+  const slug = resolveAdminStore(args);
+  const config = await fetchConfig(slug);
+  let onlyId = null;
+  const ref = args.positional[0];
+  if (ref) onlyId = findConnector(config, ref).id;
+  if (config.connectors.length === 0) {
+    process.stdout.write(`(no custom connectors in ${slug})
+`);
+    return;
+  }
+  const url = `${apiBaseFor(slug)}/admin/connectors/health`;
+  const data = await request(url, { method: "POST", body: onlyId ? { id: onlyId } : {} });
+  if (flagBool(args.flags, "json")) {
+    process.stdout.write(JSON.stringify(data.health, null, 2) + "\n");
+    return;
+  }
+  const nameById = new Map(config.connectors.map((r) => [r.id, r.name]));
+  for (const result of data.health) {
+    const name = nameById.get(result.id) ?? result.id;
+    if (result.ok) {
+      process.stdout.write(`  ok      ${name} (${result.toolCount ?? 0} tools)
+`);
+    } else {
+      process.stdout.write(`  failed  ${name}: ${result.error ?? "discovery failed"}
+`);
+      process.exitCode = 1;
+    }
+  }
+}
+
+// src/commands/connectors/index.ts
+async function connectorsCommand(args) {
+  const sub = args.positional[0] ?? "list";
+  const rest = { ...args, positional: args.positional.slice(1) };
+  switch (sub) {
+    case "list":
+      await listConnectors(rest);
+      return;
+    case "add":
+      await addConnector(rest);
+      return;
+    case "remove":
+      await removeConnector(rest);
+      return;
+    case "enable":
+      await setConnectorEnabled(rest, true);
+      return;
+    case "disable":
+      await setConnectorEnabled(rest, false);
+      return;
+    case "maker":
+      await setMaker(rest);
+      return;
+    case "health":
+      await healthCheck(rest);
+      return;
+    default:
+      throw new Error(
+        `Unknown connectors subcommand: ${sub}. Use \`gs connectors [add|remove|enable|disable|maker|health]\`.`
+      );
   }
-  const rel = path8.relative(process.cwd(), dest);
-  return rel && !rel.startsWith("..") ? rel : dest;
 }
 
 // src/changelog.ts
@@ -1550,9 +2085,9 @@ function recentChangelog(text, minItems = 15) {
 }
 
 // src/version-check.ts
-import * as fs9 from "fs";
+import * as fs11 from "fs";
 import * as os3 from "os";
-import * as path9 from "path";
+import * as path11 from "path";
 var NOTICE = "GreatStore CLI is still in early beta and we constantly pushing new features and security update. It is advised to update to the latest version whenever possible.";
 var PKG = "@greatstore/cli";
 var REGISTRY_URL = `https://registry.npmjs.org/${PKG}/latest`;
@@ -1606,11 +2141,11 @@ async function fetchLatest() {
   }
 }
 function cachePath(home) {
-  return path9.join(home, ".greatstore", "version-check.json");
+  return path11.join(home, ".greatstore", "version-check.json");
 }
 function readCache(home) {
   try {
-    const raw = fs9.readFileSync(cachePath(home), "utf8");
+    const raw = fs11.readFileSync(cachePath(home), "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.latest === "string" && typeof parsed.checkedAt === "number") {
       return { latest: parsed.latest, checkedAt: parsed.checkedAt };
@@ -1622,8 +2157,8 @@ function readCache(home) {
 function writeCache(home, cache3) {
   try {
     const file = cachePath(home);
-    fs9.mkdirSync(path9.dirname(file), { recursive: true });
-    fs9.writeFileSync(file, JSON.stringify(cache3));
+    fs11.mkdirSync(path11.dirname(file), { recursive: true });
+    fs11.writeFileSync(file, JSON.stringify(cache3));
   } catch {
   }
 }
@@ -1645,36 +2180,47 @@ function parseVer(v) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.0.26" : "0.0.0-dev";
-var CHANGELOG = true ? "# Changelog\n\nAll notable changes to `@greatstore/cli` are recorded here. The format\nfollows [Keep a Changelog](https://keepachangelog.com/).\n\n## 0.0.26 \u2014 2026-06-11\n\n### Added\n- The agent skill gains a \"GreatStore launchers\" recipe: a horizontally\n  scrollable row of AI-generated chips, each an engaging first-person\n  question about the current page that's sent to the assistant on tap.\n\n### Changed\n- Skill recipes are now one file each under `recipes/`, indexed from\n  SKILL.md by a table with description and use-case columns.\n\n## 0.0.25 \u2014 2026-06-11\n\n### Added\n- `gs skill` installs the GreatStore agent skill \u2014 a guide AI coding\n  agents use to build with GreatStore: AI content for your own UI, chat\n  entry points, page tools, custom in-chat components, push\n  notifications, and the store's MCP endpoints. Installs into\n  `./.claude/skills/`; use `--global` for `~/.claude/skills/`, or\n  `--dir <path>` for agents that read skills from somewhere else. Run\n  it again any time to update an installed copy.\n\n## 0.0.24 \u2014 2026-06-03\n\n### Changed\n- `gs init` in an existing project now fills in any scaffold files that\n  are missing (for example, the `AGENTS.md` design guide added in\n  0.0.23) and leaves your own files alone. Pass `--force` to refresh\n  every scaffold file to the latest version. Your pinned store\n  (`.gsrc`) is never rewritten either way.\n\n## 0.0.23 \u2014 2026-06-03\n\n### Added\n- `gs init` now scaffolds an `AGENTS.md` (with `CLAUDE.md` and\n  `GEMINI.md` symlinked to it) documenting the design rules every\n  component should follow \u2014 use `em` rather than `rem` for sizing, and\n  style from the provided brand CSS variables so components match the\n  store's theme. It doubles as guidance for AI coding agents.\n\n## 0.0.22 \u2014 2026-06-02\n\n### Added\n- `gs list` now shows a link to each component's page in the dashboard,\n  so you can jump straight to a component to preview or publish it. The\n  link is also included in `gs list --json`.\n\n## 0.0.21 \u2014 2026-05-31\n\n### Changed\n- The `gs init` component scaffold now shows how to write **async**\n  components that load data before they render \u2014 including validating\n  inputs up front and signalling a failure by throwing. The scaffolded\n  component no longer includes an `onError` prop; throw from an async\n  component to report a failure instead.\n\n## 0.0.20 \u2014 2026-05-29\n\n### Added\n- `gs pull`, `gs push`, and `gs publish` now accept several component\n  names at once (e.g. `gs publish header footer cart`). Each component\n  is reported on its own line and one failure no longer stops the rest.\n\n## 0.0.19 \u2014 2026-05-28\n\n### Fixed\n- `gs login` on Windows no longer opens a sign-in URL with parameters\n  stripped, which surfaced as a \"Missing redirect_uri or state\n  parameter\" page in the browser.\n\n## 0.0.18 \u2014 2026-05-28\n\n### Changed\n- Push and publish errors now name the specific reason \u2014 including\n  every failing field in `manifest.json` \u2014 instead of the previous\n  generic message.\n\n## 0.0.17 \u2014 2026-05-28\n\n### Added\n- Each command now prints a one-line upgrade notice when a newer\n  `@greatstore/cli` is available on npm.\n\n## 0.0.16 \u2014 2026-05-28\n\n### Changed\n- Simplified error messages.\n\n## 0.0.15 \u2014 2026-05-24\n\n### Added\n- Scaffolded `component.tsx` now declares the four injected lifecycle\n  props (`onSendMessage`, `onCallTool`, `onClose`, `onError`) on\n  `Props`. Use `onError(message)` to report expected failures (failed\n  fetch, host action rejected, invalid host state) so the AI can\n  recover on its next turn. Render-time crashes are reported for you.\n\n## 0.0.14 \u2014 2026-05-24\n\n### Changed\n- `gs build` output is now whitespace-minified \u2014 typically ~50% smaller.\n\n## 0.0.13 \u2014 2026-05-24\n\n### Changed\n- `gs build` prints the next-step hint (`gs push`, then `gs publish`).\n\n## 0.0.12 \u2014 2026-05-24\n\n### Fixed\n- `gs build` failing to load Vite in some setups.\n\n## 0.0.11 \u2014 2026-05-24\n\n### Added\n- Multi-component projects. `gs init` (no args) scaffolds the project\n  root; `gs init <name>` adds a component under `components/<name>/`.\n- `gs build [<name>]` \u2014 compiles every `components/<name>/bundle.js`.\n- `gs push` (no args) uploads only the components that changed.\n- `gs pull` (no args, or `*`) downloads every component. Locally\n  edited components are skipped; pass `--force` to overwrite.\n- Public `CHANGELOG.md`; `gs --version` prints recent entries.\n\n### Changed\n- A project folder ships to exactly one store. Only `gs init` accepts\n  `--store`; every other command reads the slug from `.gsrc`. The old\n  single-component layout is rejected with a migration hint.\n- `gs init` requires `--store <slug>` for a fresh root, and rejects\n  `--store` on an existing root.\n- `gs init` no longer writes `build.mjs` \u2014 scripts call `gs build`.\n\n## 0.0.10 \u2014 2026-05-23\n\n### Changed\n- The sign-in browser tab auto-closes once `gs login` finishes.\n\n## 0.0.9 \u2014 2026-05-23\n\n### Changed\n- Scaffolded manifests include a `displayName` so the admin UI has a\n  friendlier label.\n\n## 0.0.8 \u2014 2026-05-23\n\n### Changed\n- `gs push` and `gs publish` print a link to view the component.\n\n## 0.0.6 \u2014 2026-05-23\n\n### Changed\n- `gs --version` reads from the published package version.\n\n## 0.0.4 \u2014 2026-05-23\n\n### Changed\n- Scaffolded projects produce browser-ready bundles out of the box.\n\n## 0.0.3 \u2014 2026-05-23\n\n### Changed\n- Trimmed public README to the essentials.\n\n## 0.0.2 \u2014 2026-05-23\n\n### Fixed\n- Sign-in callback parameter handling.\n" : "";
+var VERSION = true ? "0.0.28" : "0.0.0-dev";
+var CHANGELOG = true ? "# Changelog\n\nAll notable changes to `@greatstore/cli` are recorded here. The format\nfollows [Keep a Changelog](https://keepachangelog.com/).\n\n## 0.0.28 \u2014 2026-06-12\n\n### Added\n- `gs configure` \u2014 view and edit the store configuration from the CLI:\n  display name, assistant name, sales guide, store link, extra origins,\n  Shopify login gate, theme, CSP host lists, and icon/logo uploads. Same\n  fields and behaviour as the dashboard's Configure panel.\n- `gs connectors` \u2014 manage the store's MCP connectors: list, add (with\n  a discovery probe before saving), remove, enable/disable, toggle the\n  Maker MCP, and health-check. Same behaviour as the dashboard's\n  Connectors panel.\n- `--store <slug>` on the new admin commands, so they work outside a\n  scaffolded component project (a `.gsrc` is still used when present).\n- The agent skill gains a store-administration reference: coding agents\n  can read the store's configuration and connectors to ground their\n  work, self-serve additive changes like origin allowlists and CSP\n  hosts (read-merge-write), and are told which changes need the\n  merchant's go-ahead first.\n\n### Changed\n- Component commands now live under `gs apps` (`gs apps push`,\n  `gs apps build`, \u2026), matching the dashboard's Apps panel. The old\n  top-level forms keep working as aliases, so existing scripts and\n  scaffolded projects are unaffected.\n- The skill's structured-content guide now teaches \"point, don't\n  paste\": name the SKU/product/collection and let GreatStore research\n  the catalog itself instead of inlining fetched specs; validate with\n  `gs connectors` that a connector exists for the data a prompt or\n  schema depends on (research can't exceed the wired-up connectors);\n  and never put shopper data in prompts \u2014 GreatStore already knows the\n  shopper, and identified shoppers get per-shopper cached responses.\n\n## 0.0.27 \u2014 2026-06-11\n\n### Changed\n- Skill code samples now carry an explicit reference-only disclaimer:\n  coding agents are told to re-express the logic in the host repo's\n  framework (React, Vue, Shopify Liquid, Svelte, \u2026) instead of\n  retrofitting the framework-free samples as-is.\n\n## 0.0.26 \u2014 2026-06-11\n\n### Added\n- The agent skill gains a \"GreatStore launchers\" recipe: a horizontally\n  scrollable row of AI-generated chips, each an engaging first-person\n  question about the current page that's sent to the assistant on tap.\n\n### Changed\n- Skill recipes are now one file each under `recipes/`, indexed from\n  SKILL.md by a table with description and use-case columns.\n\n## 0.0.25 \u2014 2026-06-11\n\n### Added\n- `gs skill` installs the GreatStore agent skill \u2014 a guide AI coding\n  agents use to build with GreatStore: AI content for your own UI, chat\n  entry points, page tools, custom in-chat components, push\n  notifications, and the store's MCP endpoints. Installs into\n  `./.claude/skills/`; use `--global` for `~/.claude/skills/`, or\n  `--dir <path>` for agents that read skills from somewhere else. Run\n  it again any time to update an installed copy.\n\n## 0.0.24 \u2014 2026-06-03\n\n### Changed\n- `gs init` in an existing project now fills in any scaffold files that\n  are missing (for example, the `AGENTS.md` design guide added in\n  0.0.23) and leaves your own files alone. Pass `--force` to refresh\n  every scaffold file to the latest version. Your pinned store\n  (`.gsrc`) is never rewritten either way.\n\n## 0.0.23 \u2014 2026-06-03\n\n### Added\n- `gs init` now scaffolds an `AGENTS.md` (with `CLAUDE.md` and\n  `GEMINI.md` symlinked to it) documenting the design rules every\n  component should follow \u2014 use `em` rather than `rem` for sizing, and\n  style from the provided brand CSS variables so components match the\n  store's theme. It doubles as guidance for AI coding agents.\n\n## 0.0.22 \u2014 2026-06-02\n\n### Added\n- `gs list` now shows a link to each component's page in the dashboard,\n  so you can jump straight to a component to preview or publish it. The\n  link is also included in `gs list --json`.\n\n## 0.0.21 \u2014 2026-05-31\n\n### Changed\n- The `gs init` component scaffold now shows how to write **async**\n  components that load data before they render \u2014 including validating\n  inputs up front and signalling a failure by throwing. The scaffolded\n  component no longer includes an `onError` prop; throw from an async\n  component to report a failure instead.\n\n## 0.0.20 \u2014 2026-05-29\n\n### Added\n- `gs pull`, `gs push`, and `gs publish` now accept several component\n  names at once (e.g. `gs publish header footer cart`). Each component\n  is reported on its own line and one failure no longer stops the rest.\n\n## 0.0.19 \u2014 2026-05-28\n\n### Fixed\n- `gs login` on Windows no longer opens a sign-in URL with parameters\n  stripped, which surfaced as a \"Missing redirect_uri or state\n  parameter\" page in the browser.\n\n## 0.0.18 \u2014 2026-05-28\n\n### Changed\n- Push and publish errors now name the specific reason \u2014 including\n  every failing field in `manifest.json` \u2014 instead of the previous\n  generic message.\n\n## 0.0.17 \u2014 2026-05-28\n\n### Added\n- Each command now prints a one-line upgrade notice when a newer\n  `@greatstore/cli` is available on npm.\n\n## 0.0.16 \u2014 2026-05-28\n\n### Changed\n- Simplified error messages.\n\n## 0.0.15 \u2014 2026-05-24\n\n### Added\n- Scaffolded `component.tsx` now declares the four injected lifecycle\n  props (`onSendMessage`, `onCallTool`, `onClose`, `onError`) on\n  `Props`. Use `onError(message)` to report expected failures (failed\n  fetch, host action rejected, invalid host state) so the AI can\n  recover on its next turn. Render-time crashes are reported for you.\n\n## 0.0.14 \u2014 2026-05-24\n\n### Changed\n- `gs build` output is now whitespace-minified \u2014 typically ~50% smaller.\n\n## 0.0.13 \u2014 2026-05-24\n\n### Changed\n- `gs build` prints the next-step hint (`gs push`, then `gs publish`).\n\n## 0.0.12 \u2014 2026-05-24\n\n### Fixed\n- `gs build` failing to load Vite in some setups.\n\n## 0.0.11 \u2014 2026-05-24\n\n### Added\n- Multi-component projects. `gs init` (no args) scaffolds the project\n  root; `gs init <name>` adds a component under `components/<name>/`.\n- `gs build [<name>]` \u2014 compiles every `components/<name>/bundle.js`.\n- `gs push` (no args) uploads only the components that changed.\n- `gs pull` (no args, or `*`) downloads every component. Locally\n  edited components are skipped; pass `--force` to overwrite.\n- Public `CHANGELOG.md`; `gs --version` prints recent entries.\n\n### Changed\n- A project folder ships to exactly one store. Only `gs init` accepts\n  `--store`; every other command reads the slug from `.gsrc`. The old\n  single-component layout is rejected with a migration hint.\n- `gs init` requires `--store <slug>` for a fresh root, and rejects\n  `--store` on an existing root.\n- `gs init` no longer writes `build.mjs` \u2014 scripts call `gs build`.\n\n## 0.0.10 \u2014 2026-05-23\n\n### Changed\n- The sign-in browser tab auto-closes once `gs login` finishes.\n\n## 0.0.9 \u2014 2026-05-23\n\n### Changed\n- Scaffolded manifests include a `displayName` so the admin UI has a\n  friendlier label.\n\n## 0.0.8 \u2014 2026-05-23\n\n### Changed\n- `gs push` and `gs publish` print a link to view the component.\n\n## 0.0.6 \u2014 2026-05-23\n\n### Changed\n- `gs --version` reads from the published package version.\n\n## 0.0.4 \u2014 2026-05-23\n\n### Changed\n- Scaffolded projects produce browser-ready bundles out of the box.\n\n## 0.0.3 \u2014 2026-05-23\n\n### Changed\n- Trimmed public README to the essentials.\n\n## 0.0.2 \u2014 2026-05-23\n\n### Fixed\n- Sign-in callback parameter handling.\n" : "";
 var HELP = `gs \u2014 GreatStore CLI (v${VERSION})
 
 Usage:
   gs <command> [args] [flags]
 
-Commands:
+Account:
   login                          Open browser, capture nav token, persist credentials.
   logout                         Wipe ~/.greatstore/credentials.json.
   whoami                         Print the identity stored locally.
-  init [<name>]                  Scaffold project root; add \`components/<name>/\` if name given.
-  build [<name>]                  Build component bundle(s) via the project's Vite. No args = all.
-  list                           List components in the current store.
-  pull [<name>...|*]             Download remote component(s) into \`components/<name>/\`. No args = all.
-  push [<name>...]               Upload changed components from \`components/\`. No args = all (skips unchanged).
-  publish <name>...              Promote the draft(s) (or --version N) to live.
-  unpublish <name>               Clear the live pointer.
-  delete <name>                  Soft-delete the component.
+
+Store administration:
+  configure                      Show the store configuration.
+  configure set --<field> <val>  Edit it (same fields as the admin Configure panel).
+  configure upload <kind> <file> Upload icon / logoLight / logoDark.
+  configure clear <kind>         Remove an uploaded asset.
+  connectors                     List the store's MCP connectors.
+  connectors add <name> --url \u2026  Add a connector (probed before saving; --force skips).
+  connectors remove <name|id>    Delete a connector.
+  connectors enable|disable <n>  Toggle a connector without deleting it.
+  connectors maker on|off        Toggle the Maker MCP.
+  connectors health [<name>]     Live-probe saved connectors.
+  apps <subcommand>              Author and ship custom in-chat apps (init, build,
+                                 list, pull, push, publish, unpublish, delete).
+                                 \`gs apps help\` lists them; each also works at the
+                                 top level (\`gs push\` == \`gs apps push\`).
+
+Agent tooling:
   skill                          Install the GreatStore agent skill for AI coding agents.
 
 Common flags:
-  --store <slug>                 \`init\` only \u2014 writes the slug into .gsrc. Other commands read .gsrc.
-  --json                         Machine-readable output for \`list\`.
-  --draft | --live | --version N Revision selector for \`pull\`.
-  -o, --out <dir>                Output directory for \`pull\` / \`init\`.
-  --manifest <path>              Path to manifest for \`push\`.
-  --bundle <path>                Path to bundle for \`push\`.
-  --force                        Overwrite for \`init\` / \`pull\`; skip confirmation for \`delete\`.
-  --yes                          Skip confirmation for \`delete\`.
+  --store <slug>                 Target store for admin commands (default: nearest .gsrc).
+                                 For \`apps init\` it writes the slug into .gsrc.
+  --json                         Machine-readable output for read commands.
+  --draft | --live | --version N Revision selector for \`apps pull\`.
+  -o, --out <dir>                Output directory for \`apps pull\` / \`apps init\`.
+  --manifest <path>              Path to manifest for \`apps push\`.
+  --bundle <path>                Path to bundle for \`apps push\`.
+  --force                        Overwrite for \`apps init\` / \`apps pull\`; skip confirmation for \`apps delete\`.
+  --yes                          Skip confirmation for \`apps delete\`.
   --global                       \`skill\` only \u2014 install to ~/.claude/skills instead of ./.claude/skills.
   --dir <path>                   \`skill\` only \u2014 install into a custom skills directory.
   -h, --help                     Show this help.
@@ -1685,6 +2231,16 @@ Environment:
   GS_NAV_BASE                    Override nav OAuth base.
   GS_BROWSER_CMD                 Override the browser-open command.
 `;
+var APPS_ALIASES = /* @__PURE__ */ new Set([
+  "init",
+  "build",
+  "list",
+  "pull",
+  "push",
+  "publish",
+  "unpublish",
+  "delete"
+]);
 async function main() {
   const argv = process.argv.slice(2);
   const parsed = parseArgs(argv);
@@ -1702,6 +2258,12 @@ async function main() {
     process.stdout.write(HELP);
     return 0;
   }
+  if (parsed.command !== null && APPS_ALIASES.has(parsed.command)) {
+    return appsCommand({
+      ...parsed,
+      positional: [parsed.command, ...parsed.positional]
+    });
+  }
   switch (parsed.command) {
     case "login":
       await loginCommand();
@@ -1711,33 +2273,17 @@ async function main() {
       return 0;
     case "whoami":
       return whoamiCommand();
-    case "init":
-      initCommand(parsed);
+    case "apps":
+      return appsCommand(parsed);
+    case "configure":
+      await configureCommand(parsed);
       return 0;
-    case "build":
-      await buildCommand(parsed);
+    case "connectors":
+      await connectorsCommand(parsed);
       return 0;
     case "skill":
       skillCommand(parsed);
       return 0;
-    case "list":
-      await listCommand(parsed);
-      return 0;
-    case "pull":
-      await pullCommand(parsed);
-      return 0;
-    case "push":
-      await pushCommand(parsed);
-      return 0;
-    case "publish":
-      await publishCommand(parsed);
-      return 0;
-    case "unpublish":
-      await unpublishCommand(parsed);
-      return 0;
-    case "delete":
-      await deleteCommand(parsed);
-      return 0;
     default:
       process.stderr.write(`Unknown command: ${parsed.command}