epicmerch-mcp 1.3.20 → 1.3.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "epicmerch-mcp",
-  "version": "1.3.20",
+  "version": "1.3.21",
   "description": "MCP server for EpicMerch — integrates e-commerce into Claude and ChatGPT",
   "type": "module",
   "main": "src/index.js",

package/skills/epicmerch-storefront.md

@@ -1,608 +1,123 @@
 ---
 name: epicmerch-storefront
-description: EpicMerch storefront scaffold — SDK + Login + ProductCard + ProductList + Cart + Checkout + OrderHistory + .env with auto-generated API key. The "do everything" route under /epicmerch, and also the home for single-slice integration (auth-only, products-only, or orders-only).
+description: EpicMerch storefront scaffold — skeleton from the deterministic store_scaffold_full tool (SDK + Login + ProductCard + ProductList + Cart + Checkout + OrderHistory + .env), then a themed style pass and optional custom pages. The "do everything" route under /epicmerch, and the home for single-slice integration (auth-only, products-only, orders-only). Fast by design: the boilerplate is emitted by a tool (zero hand-writing), so generation is minutes, not an hour.
 ---
 
-# EpicMerch Full Storefront Scaffold
+# EpicMerch Storefront Scaffold (tiered)
 
-You are integrating EpicMerch into this project. EpicMerch is a complete e-commerce backend that handles auth, inventory, orders, and payments. Follow every step below in order without asking for confirmation unless a step explicitly says to ask.
+Build the storefront in tiers, fast: lay down the **standard skeleton from the
+`store_scaffold_full` tool** (instant — do NOT hand-write those files), apply a
+**theme delta**, and only LLM-generate genuinely custom pages (in parallel).
 
-## Scope — full storefront, or just one slice
+**Idempotency rule (throughout):** before writing any file, check if it already
+exists. If it does, SKIP it and tell the user "X already exists — keeping it".
+Never overwrite a merchant's existing file.
 
-This skill scaffolds the **full** storefront by default. It also absorbs the former `/epicmerch-auth`, `/epicmerch-products`, and `/epicmerch-orders` skills — if the merchant asked for only one slice, run just that subset. **Steps 0–3 always apply** (survey, detect framework, install SDK, write `src/lib/epicmerch.js`); then:
+## Phase 0 — Survey the project
 
-- **"add login / OTP / sign-in"** → also Step 4 (Login.jsx).
-- **"add a product catalog / product list / search"** → also Step 5 (+5b) (ProductCard + ProductList, including the keep-existing-card adapter path).
-- **"add a cart / checkout / order history"** → also Step 6 (Cart + Checkout + OrderHistory).
-- **"set up everything" / unsure** → the whole checklist.
+- Read `package.json`. Determine the framework + env prefix:
+  - `react` or `vite` in deps → framework `react`, env prefix `VITE_`
+  - `next` in deps → framework `react`, env prefix `NEXT_PUBLIC_`
+  - `vue` in deps → framework `react`, env prefix `VITE_`; tell the user "Vue isn't natively supported — installing React templates."
+  - none / no `package.json` → tell the user "No frontend project detected here — run me from inside a React/Vite/Next project." STOP.
+- List which scaffold targets already exist (so Phase 1 can skip them):
+  `src/lib/epicmerch.js`, `src/components/{Login,ProductCard,ProductList,Cart,Checkout,OrderHistory}.jsx`, `.env`, `.env.example`.
+- Briefly tell the user which exist (will be kept) vs which will be created.
 
-Step 7 (API key + `.env`) and Step 8 (next steps) run in every mode. The components and contracts are identical across modes — only which files you write changes.
+## Phase 1 — Skeleton (instant, via the scaffold tool)
 
-**Idempotency rule (apply throughout):** Before writing any file in the scaffold steps below, check if it already exists. If it does, SKIP that file and tell the user "X already exists — keeping it". Never overwrite existing files. The merchant may already have a polished version of any of these components; preserving their work is more important than completing the scaffold.
+Do NOT hand-write the standard components — that is the slow path. Call the tool:
 
-## Checklist
-
-- [ ] **Step 0: Survey the project**
-
-List which of the scaffold target files already exist in this project:
-- `src/lib/epicmerch.js`
-- `src/components/Login.jsx`
-- `src/components/ProductCard.jsx`
-- `src/components/ProductList.jsx`
-- `src/components/Cart.jsx`
-- `src/components/Checkout.jsx`
-- `src/components/OrderHistory.jsx`
-- `.env.example`
-- `.env`
-
-Briefly tell the user which already exist (those will be skipped) and which will be created. Then proceed.
-
-- [ ] **Step 1: Detect framework**
-
-Read `package.json`. Determine the framework:
-- If `"react"` or `"vite"` in dependencies → framework = `react`, envPrefix = `VITE_`
-- If `"next"` in dependencies → framework = `react`, envPrefix = `NEXT_PUBLIC_`
-- If `"vue"` in dependencies → framework = `react`, envPrefix = `VITE_`; tell the user: "Vue is not yet natively supported — installing React templates instead."
-- Otherwise → framework = `react`, envPrefix = `VITE_`
-
-Tell the user: "Detected [framework]. Installing EpicMerch SDK..."
-
-- [ ] **Step 2: Install the SDK**
-
-Check `package.json` first. If `"epicmerch"` is already in `dependencies`, skip the install and tell the user "epicmerch SDK already installed". Otherwise:
-
-Run: `npm install epicmerch`
-
-- [ ] **Step 3: Create SDK initializer**
-
-**If `src/lib/epicmerch.js` already exists, skip this step entirely** and tell the user "src/lib/epicmerch.js already exists — keeping it". Otherwise, write `src/lib/epicmerch.js` using the `envPrefix` detected in Step 1 to substitute the env var names:
-
-- For `VITE_` prefix (Vite / React):
-```js
-import EpicMerch from 'epicmerch';
-
-export const store = new EpicMerch({
-  apiKey: import.meta.env.VITE_API_KEY,
-  ...(import.meta.env.VITE_API_URL && { baseUrl: import.meta.env.VITE_API_URL }),
-});
-
-// Restore the customer session on page load. Without this, OTP login
-// appears to "work" (token gets saved to localStorage) but the SDK
-// stays unauthenticated until something calls setCustomerToken — so
-// the merchant logs in, the page reloads, and they're logged out again.
-if (typeof window !== 'undefined') {
-  try {
-    const saved = localStorage.getItem('customerInfo');
-    if (saved) {
-      const parsed = JSON.parse(saved);
-      if (parsed?.token) store.setCustomerToken(parsed.token);
-    }
-  } catch (_) { /* localStorage unavailable — silent fallback */ }
-}
-```
-
-- For `NEXT_PUBLIC_` prefix (Next.js):
-```js
-import EpicMerch from 'epicmerch';
-
-export const store = new EpicMerch({
-  apiKey: process.env.NEXT_PUBLIC_API_KEY,
-  ...(process.env.NEXT_PUBLIC_API_URL && { baseUrl: process.env.NEXT_PUBLIC_API_URL }),
-});
-
-// Restore customer session on page load (same as Vite — without this,
-// OTP login looks like it works but doesn't survive a page reload).
-// Guard the localStorage call so server-rendered pages don't crash.
-if (typeof window !== 'undefined') {
-  try {
-    const saved = localStorage.getItem('customerInfo');
-    if (saved) {
-      const parsed = JSON.parse(saved);
-      if (parsed?.token) store.setCustomerToken(parsed.token);
-    }
-  } catch (_) { /* localStorage unavailable */ }
-}
-```
-
-- [ ] **Step 4: Scaffold auth**
-
-**If `src/components/Login.jsx` already exists, skip this step** and tell the user "Login.jsx already exists — keeping it". Otherwise write `src/components/Login.jsx`:
-
-```jsx
-import { useState } from 'react';
-import { store } from '../lib/epicmerch';
-
-export default function Login({ onLogin }) {
-  const [phone, setPhone] = useState('');
-  const [otp, setOtp] = useState('');
-  const [step, setStep] = useState('phone');
-  const [error, setError] = useState('');
-
-  const sendOtp = async () => {
-    setError('');
-    try {
-      await store.auth.sendOtp(phone, 'phone');
-      setStep('otp');
-    } catch (e) {
-      // e.g. invalid number, or OTP_RATE_LIMIT_EXCEEDED (5/hour).
-      setError(e?.message || 'Could not send OTP. Check the number and try again.');
-    }
-  };
-
-  const verify = async () => {
-    setError('');
-    try {
-      const result = await store.auth.verifyOtp(phone, otp, {});
-      if (result.token) {
-        // SDK already sets the token internally during verifyOtp; mirror to
-        // localStorage so src/lib/epicmerch.js can restore on next page load.
-        store.setCustomerToken(result.token);
-        localStorage.setItem('customerInfo', JSON.stringify(result));
-        onLogin(result);
-      }
-    } catch (e) {
-      // e.g. "Invalid OTP" / "OTP expired" — let them retry.
-      setError(e?.message || 'Invalid or expired OTP. Try again.');
-      setOtp('');
-    }
-  };
-
-  return (
-    <div>
-      {step === 'phone' ? (
-        <>
-          <input
-            type="tel"
-            value={phone}
-            onChange={e => setPhone(e.target.value)}
-            placeholder="+919876543210"
-            autoComplete="tel"
-          />
-          <button onClick={sendOtp}>Send OTP</button>
-        </>
-      ) : (
-        <>
-          {/* EpicMerch OTPs are 4 digits. inputMode='numeric' pops the
-              numeric keypad on mobile; autoComplete='one-time-code' lets
-              iOS auto-fill from SMS without leaving the page. */}
-          <input
-            type="tel"
-            inputMode="numeric"
-            maxLength={4}
-            autoComplete="one-time-code"
-            value={otp}
-            onChange={e => setOtp(e.target.value.replace(/\D/g, '').slice(0, 4))}
-            placeholder="4-digit OTP"
-            autoFocus
-          />
-          <button onClick={verify} disabled={otp.length !== 4}>Verify</button>
-        </>
-      )}
-      {error && <p style={{ color: 'crimson' }}>{error}</p>}
-    </div>
-  );
-}
-```
-
-- [ ] **Step 5: Scaffold product catalog**
-
-For each of the two files in this step, check existence individually. If a file already exists, skip writing it and tell the user "X already exists — keeping it". Otherwise write it.
-
-**Special case — `ProductCard.jsx` already exists:** don't just skip it. The merchant has a card UI that's probably showing placeholder data. KEEP their card, but make sure it gets fed REAL products: (1) read the existing card to note the field names it expects (`name`/`title`, `price`/`cost`, `image`/`images[0]`/`thumbnail`, single `product` prop vs destructured); (2) when you write/keep `ProductList.jsx` below, have it call `store.products.list()` and map each API product onto the shape the existing card expects (an adapter — see the ProductList note below). Tell the user "ProductCard.jsx already exists — keeping your design and wiring it to live product data."
-
-Write `src/components/ProductCard.jsx`:
-
-```jsx
-import { useState } from 'react';
-
-export default function ProductCard({ product, onAddToCart }) {
-  // ProductVariant rows are { variant: String, stock: Int } — note the field
-  // is named `variant`, NOT `size`. The "variant" string is whatever the
-  // merchant configured (typically a size like 'S'/'M'/'L', but could be
-  // a color or material). Only show in-stock options — out-of-stock orders
-  // are rejected with "INSUFFICIENT_STOCK: <variant>: need N, have 0".
-  const availableVariants = (product.variants || []).filter(v => v.stock > 0);
-  const [variant, setVariant] = useState(availableVariants[0]?.variant);
-
-  // Products on sale return both `price` (original) and `salePrice` (current).
-  // Always display the current price the customer will actually pay.
-  const price = product.salePrice ?? product.price;
-  const image = product.images?.[0] || product.image;
-  const hasVariants = availableVariants.length > 0;
-
-  return (
-    <div className="product-card">
-      <img src={image} alt={product.name} />
-      <h3>{product.name}</h3>
-      <p>₹{price}</p>
-      {hasVariants && (
-        <div className="variant-picker">
-          {availableVariants.map(v => (
-            <button
-              key={v.variant}
-              type="button"
-              onClick={() => setVariant(v.variant)}
-              className={variant === v.variant ? 'selected' : ''}
-            >
-              {v.variant}
-            </button>
-          ))}
-        </div>
-      )}
-      <button
-        onClick={() => onAddToCart(product._id, variant)}
-        disabled={hasVariants && !variant}
-      >
-        Add to Cart
-      </button>
-    </div>
-  );
-}
-```
-
-Write `src/components/ProductList.jsx`:
-
-```jsx
-import { useEffect, useState } from 'react';
-import { store } from '../lib/epicmerch';
-import ProductCard from './ProductCard';
-
-export default function ProductList() {
-  const [products, setProducts] = useState([]);
-  const [categories, setCategories] = useState([]);
-  const [category, setCategory] = useState(undefined);
-  const [query, setQuery] = useState('');
-  // products.list/search return { products, page, pages, total } — track
-  // page + pages for "Load more" so a catalog (or result set) larger than
-  // `limit` isn't silently truncated to the first page.
-  const [page, setPage] = useState(1);
-  const [pages, setPages] = useState(1);
-
-  useEffect(() => { store.categories.list().then(setCategories); }, []);
-
-  useEffect(() => {
-    const req = query.trim()
-      ? store.products.search(query, { page, limit: 12 })
-      : store.products.list({ type: category, page, limit: 12 });
-    req.then(d => {
-      setPages(d.pages ?? 1);
-      // Page 1 replaces (new filter); later pages append (Load more).
-      setProducts(prev => (page === 1 ? (d.products ?? d) : [...prev, ...(d.products ?? d)]));
-    });
-  }, [query, category, page]);
-
-  // Reset to page 1 whenever the filter changes.
-  const changeQuery = (q) => { setPage(1); setQuery(q); };
-  const changeCategory = (c) => { setPage(1); setQuery(''); setCategory(c === 'All' ? undefined : c); };
-
-  // `variant` is the size STRING (e.g. 'L'), per the SDK signature
-  // store.cart.add(productId, qty, variant). Products without variants
-  // pass undefined and the SDK accepts that.
-  const addToCart = (productId, variant) => store.cart.add(productId, 1, variant);
-
-  return (
-    <div>
-      <input
-        placeholder="Search products..."
-        value={query}
-        onChange={e => changeQuery(e.target.value)}
-      />
-      <div>
-        {categories.map(c => (
-          <button key={c} onClick={() => changeCategory(c)}>{c}</button>
-        ))}
-      </div>
-      <div className="product-grid">
-        {products.map(p => <ProductCard key={p._id} product={p} onAddToCart={addToCart} />)}
-      </div>
-      {page < pages && (
-        <button onClick={() => setPage(p => p + 1)}>Load more</button>
-      )}
-    </div>
-  );
-}
-```
-
-**If you KEPT an existing `ProductCard` (it already existed):** the API returns each product as `{ _id, name, price, salePrice, image, images, variants, ... }`. If the merchant's card reads different field names, don't change the card — adapt the data in the `.map()` so live products populate their existing design:
-
-```jsx
-// e.g. existing card expects { title, cost, thumbnail }:
-{products.map(p => (
-  <ProductCard
-    key={p._id}
-    product={{ ...p, title: p.name, cost: p.salePrice ?? p.price, thumbnail: p.images?.[0] || p.image }}
-    onAddToCart={addToCart}
-  />
-))}
-```
-
-Match the adapter keys to whatever the existing card actually reads (you noted that when you decided to keep it). The cards keep the merchant's look but show **real products fetched via `store.products.list()`**.
-
-- [ ] **Step 5b: Wire up an existing search bar (only if `ProductList.jsx` was skipped)**
-
-If you wrote a fresh `ProductList.jsx` in Step 5, skip this step — the canonical scaffold already has search wired.
-
-If `ProductList.jsx` was SKIPPED because it already existed, the merchant has their own UI. They may have a search bar somewhere — in a `Navbar`, a `Header`, a dedicated `SearchBar.jsx`, a search page, etc. — that isn't currently calling EpicMerch's search API. Detect and offer to wire it up.
-
-**Detection.** Look through `src/` for files containing any of these signals (case-insensitive):
-- `<input` whose `placeholder` mentions `search`
-- A state variable named `query`, `search`, `searchTerm`, `searchQuery`, or `keyword`
-- A handler named `onSearch`, `handleSearch`, `onQueryChange`, or similar
-
-For each match, check whether the file already calls `store.products.search(`. If yes, it's wired — skip silently.
-
-**For each unwired match:** show the merchant the file path and the snippet you found, then say:
-
-> "I noticed a search input in `<path>` that doesn't call EpicMerch's search yet. The one-line wire-up is:
->
-> ```js
-> import { store } from '../lib/epicmerch';  // add at top if missing
->
-> // inside the search handler / useEffect:
-> store.products.search(query).then(d => setProducts(d.products ?? d));
-> ```
->
-> Want me to apply this to your component? (yes / no — I'll leave it alone if no.)"
-
-**WAIT for an explicit yes before editing.** If the merchant declines, move on without changing the file.
-
-If you find no search bar anywhere in `src/`, skip this step silently — don't tell the merchant "no search bar found", just continue to Step 6.
-
-- [ ] **Step 6: Scaffold cart + orders**
-
-For each of the three files in this step (Cart.jsx, Checkout.jsx, OrderHistory.jsx), check existence individually. If a file already exists, skip writing it and tell the user "X already exists — keeping it". Otherwise write it.
-
-Write `src/components/Cart.jsx`:
-
-```jsx
-import { useEffect, useState } from 'react';
-import { store } from '../lib/epicmerch';
-
-export default function Cart({ onCheckout }) {
-  // store.cart.get() returns { cart: [...] } — JUST one field. The SDK
-  // README mentions cartCount/cartTotal but those aren't actually sent by
-  // the server; compute them locally. Each line item is shaped
-  // { product: { _id, name, price, originalPrice, salePrice, image, type },
-  // qty, variant }. Note `product.price` on cart items is ALREADY the
-  // effective price (sale if on sale, else regular).
-  const [cart, setCart] = useState({ cart: [] });
-
-  useEffect(() => { store.cart.get().then(setCart); }, []);
-
-  const remove = async (productId, variant) => {
-    await store.cart.remove(productId, variant);
-    // Optimistic local update — match on BOTH productId AND variant so we
-    // don't accidentally remove a different size of the same product.
-    setCart(c => ({
-      ...c,
-      cart: (c.cart || []).filter(
-        i => !(i.product._id === productId && i.variant === variant),
-      ),
-    }));
-  };
-
-  const items = cart.cart || [];
-  const total = items.reduce((sum, i) => {
-    const price = i.product.salePrice ?? i.product.price;
-    return sum + price * i.qty;
-  }, 0);
-
-  return (
-    <div>
-      {items.map((item, idx) => {
-        const price = item.product.salePrice ?? item.product.price;
-        return (
-          <div key={`${item.product._id}-${item.variant || 'novariant'}-${idx}`}>
-            <span>
-              {item.product.name} x{item.qty}
-              {item.variant ? ` (${item.variant})` : ''}
-            </span>
-            <span>₹{price * item.qty}</span>
-            <button onClick={() => remove(item.product._id, item.variant)}>Remove</button>
-          </div>
-        );
-      })}
-      <p>Total: ₹{total}</p>
-      <button onClick={onCheckout}>Checkout</button>
-    </div>
-  );
-}
-```
-
-Write `src/components/Checkout.jsx`:
-
-```jsx
-import { useState } from 'react';
-import { store } from '../lib/epicmerch';
-
-// Razorpay's checkout.js is heavy — load it lazily on the first Place Order
-// click instead of blocking initial page render.
-const loadRazorpay = () =>
-  new Promise((resolve) => {
-    if (window.Razorpay) return resolve(true);
-    const script = document.createElement('script');
-    script.src = 'https://checkout.razorpay.com/v1/checkout.js';
-    script.onload = () => resolve(true);
-    script.onerror = () => resolve(false);
-    document.body.appendChild(script);
-  });
-
-export default function Checkout({ cart, onSuccess }) {
-  const [address, setAddress] = useState({ street: '', city: '', postalCode: '', country: 'India' });
-  const [error, setError] = useState('');
-
-  const placeOrder = async () => {
-    setError('');
-    await loadRazorpay();
-
-    // Map cart line items to the orderItems shape the API expects.
-    // Critical fields per the SDK contract:
-    //   - `productId` — the product _id (same field name as cart.add,
-    //                   magic-checkout-init, analytics.track; consistent
-    //                   across every endpoint). Server still accepts the
-    //                   legacy `product` field but `productId` is canonical.
-    //   - `name`, `image` — required, the server doesn't re-fetch them
-    //   - `variant` — the size STRING, must match what was added to cart
-    //                  or the variant lookup returns undefined and you'll
-    //                  see "INSUFFICIENT_STOCK: undefined: need 1, have 0"
-    const items = cart.cart || [];
-    const orderItems = items.map(i => ({
-      productId: i.product._id,
-      name:      i.product.name,
-      image:     i.product.images?.[0] || i.product.image,
-      qty:       i.qty,
-      price:     i.product.salePrice ?? i.product.price,
-      variant:   i.variant,
-    }));
-    const total = orderItems.reduce((s, i) => s + i.price * i.qty, 0);
-
-    // ONE call to /customer/orders is enough — the server creates the
-    // EpicMerch order AND the Razorpay order in a single transaction and
-    // returns both back. Do NOT separately call store.payment.getConfig()
-    // or store.payment.createOrder() — orderResult already includes
-    // razorpayKeyId, razorpayOrderId, amount, currency, merchantName.
-    // Calling them again creates an orphan second Razorpay order AND can
-    // trigger an idempotency-key collision against /customer/orders.
-    let orderResult;
-    try {
-      orderResult = await store.orders.create({
-        orderItems,
-        shippingAddress: address,
-        paymentMethod: 'Razorpay',
-        totalPrice: total,
-      });
-    } catch (e) {
-      // The API returns a structured error and the SDK throws it:
-      // INSUFFICIENT_STOCK ("Halden 3-Seat Sofa: need 1, have 0"),
-      // INVALID_ORDER_ITEM, PAYMENT_NOT_CONFIGURED, etc. Surface the message.
-      setError(e?.message || 'Could not place the order. Please try again.');
-      return;
-    }
-
-    // COD / fully-discounted orders return NO Razorpay session
-    // (razorpayOrderId is null) — the order is already placed, nothing to pay.
-    if (!orderResult.razorpayOrderId) {
-      await store.cart.clear();
-      onSuccess(orderResult.orderId);
-      return;
-    }
-
-    const rzp = new window.Razorpay({
-      key:      orderResult.razorpayKeyId,
-      order_id: orderResult.razorpayOrderId,
-      amount:   orderResult.amount,        // already in paise
-      currency: orderResult.currency,
-      name:     orderResult.merchantName,
-      handler: async (response) => {
-        await store.payment.verify({ ...response, orderId: orderResult.orderId });
-        await store.cart.clear();
-        onSuccess(orderResult.orderId);
-      },
-    });
-    rzp.open();
-  };
-
-  return (
-    <div>
-      <input placeholder="Street" onChange={e => setAddress(a => ({ ...a, street: e.target.value }))} />
-      <input placeholder="City" onChange={e => setAddress(a => ({ ...a, city: e.target.value }))} />
-      <input placeholder="Postal Code" onChange={e => setAddress(a => ({ ...a, postalCode: e.target.value }))} />
-      {error && <p style={{ color: 'crimson' }}>{error}</p>}
-      <button onClick={placeOrder}>Place Order</button>
-    </div>
-  );
-}
 ```
-
-**If the merchant has a top-level `App.jsx` (or similar) that maintains a `refreshCartCount` or `handleAddToCart`, also update it:** `cart.get()` returns `{ cart: [...] }`, so `refreshCartCount` should read `c?.cart?.length` (NOT `c?.items?.length` and NOT `c?.cartCount` — that field doesn't come back from the server, despite what the SDK README says); and `handleAddToCart` should accept a `variant` arg and forward it: `store.cart.add(productId, 1, variant)`. Bonus: `store.cart.add` itself returns `{ message, cartCount }`, so you can update the badge from THAT response without a separate `cart.get()` round-trip.
-
-Do NOT add any Razorpay script tag to `index.html` — the script loads dynamically only when the user clicks Place Order.
-
-Write `src/components/OrderHistory.jsx`:
-
-```jsx
-import { useEffect, useState } from 'react';
-import { store } from '../lib/epicmerch';
-
-export default function OrderHistory() {
-  const [orders, setOrders] = useState([]);
-
-  useEffect(() => { store.orders.list().then(setOrders); }, []);
-
-  return (
-    <div>
-      <h2>Your Orders</h2>
-      {orders.map(order => (
-        <div key={order._id}>
-          <span>Order #{order._id.slice(-6)}</span>
-          <span> — ₹{order.totalPrice}</span>
-          <span> — {order.status}</span>
-        </div>
-      ))}
-    </div>
-  );
-}
+store_scaffold_full({ framework: "react" })
 ```
 
-- [ ] **Step 7: Generate API key via MCP + write `.env`**
-
-This step has two parts: write `.env.example` (the template), then generate a real API key and write a working `.env`.
-
-**Part A — `.env.example`:** If `.env.example` already exists, skip writing it and tell the user ".env.example already exists — keeping it". Otherwise write `.env.example`:
+It returns `content[0].text` = a JSON string of `[{ path, content }]` for 8 files:
+`src/lib/epicmerch.js`, `src/components/Login.jsx`, `ProductCard.jsx`,
+`ProductList.jsx`, `Cart.jsx`, `Checkout.jsx`, `OrderHistory.jsx`, `.env.example`.
 
-```
-VITE_API_KEY=your_epicmerch_api_key_here
-# VITE_API_URL is OPTIONAL — only set it for local development.
-# Production: leave it unset; the SDK defaults to https://api.epicmerch.in/api
-# Local dev: VITE_API_URL=http://localhost:5002/api
-```
+Parse it and **write each file whose path does NOT already exist** (Phase 0
+skip-existing rule). Report `✓ wrote <n> files (kept <m> existing)`.
 
-Check `.gitignore` — if `.env` is not listed, append `.env` to `.gitignore` before any `.env` file is written.
+These files are contract-tested (cart.cart shape, `productId`, `v.variant`,
+session-restore, COD guard, pagination) — they are correct by construction, which
+is why we use the tool instead of writing them by hand.
 
-**Part B — generate a real API key + write `.env`:**
+> If the merchant only wants ONE slice (auth-only / products-only / orders-only),
+> call the narrower tool instead: `store_scaffold_auth`, `store_scaffold_products`,
+> or `store_scaffold_orders` (same `{framework}` arg, same `[{path,content}]`
+> return). Phases 0, 2, 3, 5 still apply.
 
-First, read `.env` if it exists. If it already contains a `VITE_API_KEY=` line whose value is NOT the placeholder string `your_epicmerch_api_key_here` (i.e. there's already a real key), skip Part B entirely and tell the user "Existing API key in .env — keeping it".
+## Phase 2 — API key + `.env`
 
-Otherwise, the merchant is authenticated via the EpicMerch MCP (this skill assumes the MCP is connected — that's how it was invoked). Generate a key by calling the MCP tool:
+`store_scaffold_full` emits `.env.example`; now create the real `.env`:
 
-```
-merchant_generate_api_key({ name: "Storefront" })
-```
+1. If `.env` already has a real `VITE_API_KEY` (not the `your_epicmerch_api_key_here`
+   placeholder), keep it — tell the user "Existing API key in .env — keeping it."
+2. Otherwise call `merchant_generate_api_key({ name: "Storefront" })`, take the
+   returned key, and write `.env`:
+   - Production (default): just `VITE_API_KEY=<key>` (the SDK defaults to
+     `https://api.epicmerch.in/api`).
+   - Local dev (only if the merchant is clearly on a local server): also add
+     `VITE_API_URL=http://localhost:5001/api`.
+   - For Next.js, use `NEXT_PUBLIC_API_KEY` / `NEXT_PUBLIC_API_URL`.
+3. Ensure `.env` is gitignored — if `.gitignore` lacks `.env`, append it BEFORE
+   writing `.env`.
+4. Fallback: if `merchant_generate_api_key` is unavailable, tell the user to grab a
+   key from `https://epicmerch.in/dashboard → API Keys` and add it to `.env`. Do NOT
+   abort — continue to Phase 3.
 
-The response will include the new key. Extract it (the field is typically `key` or `apiKey` — check the response shape). Then write/update `.env`.
+## Phase 3 — Theme delta (the only standard-tier LLM work)
 
-**Production (default).** Write only the key — the SDK already knows the prod URL:
+Ask ONE vibe question:
 
-```
-VITE_API_KEY=<the generated key from the MCP response>
-```
+> "Quick — what's the vibe of your store?
+> 1) Editorial Funk (bold typography, big imagery, asymmetric layouts)
+> 2) Minimal Mono (clean, monochrome, lots of whitespace)
+> 3) Vibrant Pop (colourful, rounded corners, playful)
+> 4) Skip — functional unstyled scaffolds, I'll polish later"
 
-**Local development.** Only if the merchant is clearly running against a local EpicMerch server (e.g. they explicitly said so, or their existing `.env` already had a `localhost` URL, or the MCP was wired with `EPICMERCH_API_URL=http://localhost:...`), ALSO write the override:
+- Options 1–3: do a BOUNDED Tailwind pass — add 5–10 well-chosen utility classes
+  per scaffolded component (typography, spacing, colour) matching the vibe. This is
+  a class edit, NOT a rewrite — do not regenerate the components.
+- Option 4: skip the pass.
+- Either way, confirm `src/lib/epicmerch.js` contains the **session-restore block**
+  (`localStorage.getItem('customerInfo') → setCustomerToken`). The tool includes it
+  by default; if a pre-existing file was kept and lacks it, add it manually — without
+  it, OTP login silently doesn't survive a page reload (the #1 storefront bug).
+- Recap `✓ Storefront scaffolded + styled (<vibe>)` or `✓ ... (unstyled)`.
 
-```
-VITE_API_KEY=<the generated key from the MCP response>
-VITE_API_URL=http://localhost:5002/api
-```
+## Phase 4 — Custom pages (opt-in, parallel)
 
-When in doubt, default to the production form (no `VITE_API_URL` line). Don't ask the merchant — guess from context.
+Ask: *"Want any custom pages beyond the standard store (e.g. an About page, a
+lookbook, a size guide, a blog)? Name them, or say 'no' to finish."*
 
-**Fallback if MCP isn't available:** If the `merchant_generate_api_key` tool fails or isn't connected, tell the user: "MCP tool unavailable. Generate a key manually at https://epicmerch.in/dashboard → API Keys and add it to .env." Do NOT fail the whole flow — continue to Step 8.
+- "no" → skip to Phase 5.
+- Otherwise build a manifest: one entry per custom file (path + a one-line spec).
+  Then generate them — **in parallel if your client supports subagents** (e.g.
+  Claude Code's Task/Agent tool: dispatch one agent per file in a single batch);
+  otherwise generate them **sequentially** (still far faster than the old flow,
+  since the whole skeleton was free). Each generation gets: the SDK usage (import
+  `store` from `src/lib/epicmerch.js`; products via `store.products.list()`; the
+  cart/checkout contracts), the chosen vibe, and that one file's spec.
+- After the custom files exist, do ONE small assembly pass: wire routes/nav so the
+  new pages are reachable. Preserve existing routing.
 
-- [ ] **Step 8: Tell the user what to do next**
+## Phase 5 — Verify (the Definition-of-Done gate)
 
-Print a summary using the actual state of the project:
+Run `/epicmerch-verify` (Deep mode) — the full product→cart→order pipeline against
+the live API; on pass it stamps server-side verification. Do not tell the merchant
+"your store is set up" until this is green. If it fails, route to `/epicmerch-debug`,
+fix, and re-run.
 
-- List the files you CREATED in this run (skip the ones that were already present).
-- If you skipped any, briefly mention them as "kept as-is".
-- If Step 5b wired up a search bar in an existing component, mention which file you edited and that it now calls `store.products.search()`.
-- If the API key was generated automatically, mention that ".env now has a working VITE_API_KEY — your storefront should load real product data on next refresh."
-- Then output the next-steps block exactly:
+## Wrap-up
 
-```
-Next steps:
-1. (API key auto-generated and saved to .env — if not, get one at https://epicmerch.in/dashboard → API Keys)
-2. Restart your dev server (npm run dev) to pick up the .env changes
-3. Import the new components into your App.jsx where you need them
+Print what was created (skeleton files written vs kept, theme applied, any custom
+pages, verify result), then:
 
-Need help with payments, analytics, or notifications? Ask me!
+```
+Next:
+1. Restart your dev server (npm run dev) to pick up .env.
+2. Import the components where you need them.
+Need payments, analytics, or a Buy Now button? Just ask.
 ```

package/skills/epicmerch.md

@@ -1,239 +1,242 @@
----
-name: epicmerch
-description: EpicMerch umbrella — guided 6-step onboarding wizard for new merchants, driven by a deterministic state machine (merchant_onboarding_state) that re-derives progress from live state and CANNOT report "complete" until a real end-to-end order test (/epicmerch-verify Deep mode) has stamped verification server-side. Also an intent router for merchants who already know what they want (scaffold a storefront, set up payments, add a Buy Now button, manage a store, migrate from Shopify, verify the store). Verification is the non-negotiable, structurally-enforced definition of done.
----
-
-# EpicMerch — the umbrella
-
-The **one entry point** for everything EpicMerch. Merchants don't need to memorise 10+ slash commands; they say what they want (or say nothing) and you figure out the right flow.
-
-## Mode detection
-
-Two modes. Pick one based on what the merchant said:
-
-| What the merchant said when invoking `/epicmerch` | Mode |
-|---|---|
-| Nothing specific. Just `/epicmerch` with no extra words. | **Wizard mode** (Step A below) |
-| "help me start", "I'm new", "set up everything", "what's next", "where do I begin" | **Wizard mode** |
-| "set up Razorpay", "add a Buy Now button", "migrate Shopify", "scaffold a storefront", "show me my products" — anything with a clear specific intent | **Intent mode** (Step B below) |
-
-If ambiguous, ask ONE disambiguating question: *"Want me to walk you through a full setup wizard, or is there one specific thing you want to do?"*
-
----
-
-## DEFINITION OF DONE — read this before you finish (applies to BOTH modes)
-
-**`/epicmerch` is not complete until a live end-to-end test has run and passed.**
-
-This holds no matter how the build happened — the wizard's scaffold step, an intent-mode `/epicmerch-storefront`, OR a fully custom build you designed through brainstorming (e.g. a themed multi-page store). However you got here, the LAST thing you do before telling the merchant "your store is set up" is run **`/epicmerch-verify` (Deep mode)** — the full product→cart→order pipeline; it automatically falls back to Smoke mode if the server's test-login isn't configured.
-
-Common trap: a design-heavy request ("build me a saree store") pulls you into scope/theme/spec brainstorming and a custom build, and the flow ends at "looks good!" without ever testing against the live API. **Don't let that happen.** After the storefront files are written and the `.env` has a real API key, run the e2e/verify gate. A store that was never tested against the live API is not done — that's exactly how the cart-shape / productId / out-of-stock bugs reached real merchants.
-
-If you realize you're wrapping up `/epicmerch` and haven't run the test → run it now.
-
-In **Wizard mode** this is enforced for you: `merchant_onboarding_state` will not return `complete` until `/epicmerch-verify` (Deep mode) has stamped verification server-side, so you structurally can't wrap up early. In **Intent mode** and custom/brainstormed builds there's no such gate — that's where this reminder matters most.
-
----
-
-## Step A — Wizard mode (the harness loop)
-
-Wizard mode is a **deterministic loop driven by the `merchant_onboarding_state` tool** — not prose you interpret. The tool re-derives what's done, what's next, and whether you're complete from **live server state on every call**, and it enforces the gate: you **cannot** reach `complete` until a real `/epicmerch-verify` (Deep mode) run has stamped verification server-side. That is what makes `/epicmerch` un-breakable — the control flow lives in code + a hard gate, so "done but never verified" is structurally unreachable. You bring the creative work (the conversation, the product shape, the styling); the tool owns order, idempotency, and the gate.
-
-Open with one sentence:
-
-> "I'll set up your EpicMerch store. I'll check what's already done, do the next thing, and finish with a live end-to-end test — that test is the only thing that marks the setup complete."
-
-### The loop
-
-Repeat until the tool returns `complete: true`:
-
-1. Check the local project: does `src/lib/epicmerch.js` exist? (`true`/`false` → `storefrontPresent`).
-2. Call `merchant_onboarding_state({ storefrontPresent })`.
-3. If `complete === true` → print the **wrap-up recap** (below) and STOP. You're done.
-4. Else → read `nextStep` and perform **that one step's action** (see *Step actions* below). The `steps[nextStep].action` string is a short reminder; the full expansion is below. Do exactly ONE step, recap it in one line (`✓ <what happened>`), then go back to 1.
-
-**Rules that keep the harness honest:**
-- Never skip ahead, never decide completion yourself, never print "your store is set up" before the tool returns `complete: true`.
-- The loop is inherently idempotent — every turn re-reads live state, so re-running after a partial setup just resumes where you left off.
-- If you catch yourself about to wrap up without `complete`, call the tool again — it will name the real gap.
-
-### Step actions (the expansion of each `nextStep`)
-
-#### `account` — authenticate
-The tool couldn't read your settings (not connected / 401). Tell the merchant:
-
-> "Your CLI isn't connected. Run `npx epicmerch-mcp setup` (or `npx epicmerch-mcp login` if MCP is already installed), then ask me again."
-
-STOP the loop. Resume (re-call the tool) once they confirm they're connected.
-
-#### `apiKey` — generate a storefront key
-
-> "You don't have an API key yet. I'll generate one called 'Storefront' — that's what the SDK uses to talk to your store."
-
-Call `merchant_generate_api_key({ name: 'Storefront' })`. Recap `✓ API key generated.` and re-loop.
-
-#### `payment` — configure a processor
-Ask **one** question:
-
-> "Where do most of your customers buy from?
-> 1) India (Razorpay — recommended)
-> 2) Outside India (Stripe)"
-
-- "India" / "1" → run `/epicmerch-payments` (it takes the Razorpay path)
-- "outside" / "global" / "2" → run `/epicmerch-payments` (it takes the Stripe path)
-
-`/epicmerch-payments` configures the chosen processor **and** the checkout type — the tool's `payment` step needs both before it counts as done. Re-loop; the tool confirms `payment.done`.
-
-#### `products` — fill the catalog
-The catalog is empty (the tool counts an empty catalog as not-done, so this step keeps surfacing until at least one product exists). Ask:
-
-> "Your catalog is empty. Want me to:
-> 1) Migrate your existing Shopify store
-> 2) Add your first product right now
-> 3) Add a quick sample product so we can finish, and you replace it later"
-
-- "Shopify" / "1" → run `/epicmerch-migrate`
-- "first product" / "2" → walk through it with `merchant_create_product`. **Do NOT just ask for name + price** — products that ship without variants and images break the storefront UX (empty size picker, broken image). Collect the FULL shape in ONE round of questions:
-  - **Name + Category** (`name`, `type`)
-  - **Description** (`description`)
-  - **Pricing** — list price (`price`), plus on-sale fields if applicable (`salePrice`, `discountPercent`). *"If this product is on sale, tell me the sale price and discount %. Otherwise say 'no sale'."*
-  - **Variants** (`variants`) — array of `{ variant: 'S', stock: 5 }` entries. *"What sizes / colors / options does this come in, and how many of each in stock? If just one option, say 'no variants'."* When passed, the server derives total stock from `sum(variant.stock)` and ignores the top-level `stock`.
-  - **Images** (`images`) — array of gallery URLs. Optionally `image` for an explicit primary; if omitted the server uses `images[0]`.
-  Pass everything to `merchant_create_product` in ONE call — never create-then-update.
-- "sample" / "3" → create one reasonable sample product (full shape, a couple of variants, a placeholder image) so the loop can progress. Tell the merchant it's a placeholder they can edit or delete later.
-
-There is no hard "skip" here: `complete` requires a non-empty catalog. If the merchant truly wants to stop, be honest that onboarding stays incomplete until a product exists.
-
-#### `storefront` — scaffold into the project
-`storefrontPresent` is false. First check the project: does `package.json` exist with React / Vite / Next in dependencies?
-
-- **Not a frontend project / no `package.json`**: tell the merchant *"No frontend project detected here. Run `/epicmerch` from inside a React/Vite/Next project to scaffold the storefront."* `storefrontPresent` stays false, so the loop keeps flagging `storefront` — be honest that `complete` needs the storefront scaffolded (they can finish from a project later; a chat-only setup won't reach `complete`).
-- **Project detected, no SDK file**: do the two-part sub-flow:
-
-**4a — Visual style (before scaffolding).** Ask ONE question so the components match their vibe:
-
-> "Quick — what's the vibe of your store?
-> 1) Editorial Funk (bold typography, big imagery, asymmetric layouts)
-> 2) Minimal Mono (clean, monochrome, lots of whitespace)
-> 3) Vibrant Pop (colourful, rounded corners, playful)
-> 4) Skip — functional unstyled scaffolds, I'll polish later"
-
-Remember the answer as `visualStyle`.
-
-**4b — Scaffold + style.** Run `/epicmerch-storefront`. After it finishes:
-- If `visualStyle` ≠ skip, do a quick styling pass: 5-10 well-chosen Tailwind utility classes per component (typography, spacing, colour) matching `visualStyle`. Don't overdo it.
-- Confirm `src/lib/epicmerch.js` contains the **session-restore block** (the `localStorage.getItem('customerInfo') → setCustomerToken` snippet). Without it, OTP login appears to work but doesn't survive a page reload — the #1 silent storefront bug. The 1.3.4+ scaffold includes it by default; add it manually if missing.
-- Recap `✓ Storefront scaffolded + styled (<visualStyle>)` (or `unstyled`).
-
-**Optional add-on (not gated):** once the storefront exists, you may offer a 1-click Buy Now button — *"Want a 1-click 'Buy Now' button? Razorpay's Magic Checkout lets customers buy without a cart screen."* → `/epicmerch-magic-checkout` (it verifies Razorpay first). This is optional and does NOT affect `complete`; the merchant can add it anytime by saying *"add a Buy Now button"*. Then re-loop.
-
-#### `verified` — the gate (the ONLY step that flips `complete`)
-This is the un-fakeable half of the harness. Run **`/epicmerch-verify` (Deep mode)** automatically:
-
-> "Last step — a live end-to-end test to confirm everything actually works."
-
-It gets a customer session, creates a throwaway test product, adds it to a cart, creates a real order (exercising stock reservation + Razorpay order creation, no charge), verifies every response shape, then cleans up (cancels the order, deletes the product). This proves the WHOLE pipeline, not just read paths. It gets its customer token via the server's env-gated test phone (`store_auth_send_otp` + `store_auth_verify_otp` against `E2E_TEST_PHONE`), so it needs no SMS and no manual login.
-
-- **On pass:** `/epicmerch-verify` (Deep mode) calls **`merchant_mark_verified`**, which stamps `lastVerifiedAt` server-side. That is the ONLY thing that flips the tool's `verified` step to done. Re-loop — `merchant_onboarding_state` will now return `complete: true`.
-- **On any failure:** do NOT stamp verified. Route to `/epicmerch-debug` automatically — its four-check playbook (OTP not persisting, products not loading, INSUFFICIENT_STOCK on checkout, cart 401) fixes it without further merchant intervention. Then re-run `/epicmerch-verify` (Deep mode).
-- **If the e2e token step fails** because the server lacks `E2E_TEST_PHONE`/`E2E_TEST_OTP` (you'll see a normal SMS channel instead of `e2e-test`, or a 401 on verify), fall back to `/epicmerch-verify` (read-path + payload checks, no token). **Important:** the fallback does NOT stamp `lastVerifiedAt`, so the `verified` step stays not-done and the tool will NOT report `complete`. Be honest: *"Ran the read-path + payload checks. To mark the store verified end-to-end (and finish onboarding), your EpicMerch operator needs to set `E2E_TEST_PHONE`/`E2E_TEST_OTP` on the server so the automated order test can run."*
-
-### Wizard wrap-up
-
-Print this one-block recap **only when `merchant_onboarding_state` has returned `complete: true`** (i.e. the `verified` step is done — never before):
-
-```
-━━━ Your store is set up ━━━
-  ✓ Account connected as <email>
-  ✓ API key: <name>
-  ✓ Payments: <Razorpay/Stripe>
-  ✓ Catalog: <N> products
-  ✓ Storefront: scaffolded into <project>   (or "skipped — no project")
-  ✗ Buy Now button: skipped                  (or ✓ if they added it)
-  ✓ End-to-end test: product → cart → order → cleanup all passed
-       (verified live — lastVerifiedAt stamped server-side)
-
-Next: restart your dev server (`npm run dev`) to pick up `.env`. Your
-store works end-to-end. Ask me about analytics, notifications, or
-abandoned-cart messages whenever you're ready.
-```
-
----
-
-## Step B — Intent mode (router)
-
-The merchant said something specific. Match against the table below, pick the closest, hand off. If multiple match, ask ONE disambiguating question.
-
-| The merchant says … | Route to |
-|---|---|
-| "set up EpicMerch", "scaffold a storefront", "build me a store", "integrate ecommerce" (and the project has no `src/lib/epicmerch.js`) | `/epicmerch-storefront` |
-| "add login / OTP / sign in" | `/epicmerch-storefront` (auth slice) |
-| "add a product catalog", "show products on my site", "product list with search" | `/epicmerch-storefront` (products slice) |
-| "add a cart", "build checkout", "order history page", "multi-product checkout" | `/epicmerch-storefront` (orders slice) |
-| "add Buy Now button", "1-click checkout", "impulse buy", "Razorpay Magic Checkout" | `/epicmerch-magic-checkout` |
-| "set up payments", "accept cards", "configure checkout", "set up Razorpay", "set up Stripe", "India / international payments" | `/epicmerch-payments` |
-| "connect my store to Claude / Cursor / Codex", "log in to EpicMerch", "install the MCP" | `/epicmerch-setup` |
-| "show me my store / products / orders / sales", "manage my store from chat" | `/epicmerch-merchant` |
-| "migrate from Shopify", "import my Shopify catalog" | `/epicmerch-migrate` |
-| "my login isn't sticking", "products aren't loading", "checkout fails", "insufficient stock undefined", "something's broken" | `/epicmerch-debug` |
-| "test everything", "does checkout actually work", "full end-to-end test", "run a real order test" | `/epicmerch-verify` (Deep mode) |
-
-### Hand-off (or inline)
-
-**In Claude Code / Claude Desktop / Cursor / VS Code Claude extension:**
-
-Tell the merchant which slash command you're invoking, then proceed:
-
-> "Sounds like you want X — running `/epicmerch-Y` now."
-
-The slash-command file is loaded from `~/.claude/commands/epicmerch-Y.md`; follow its steps.
-
-**In Codex CLI (or any client without slash commands):**
-
-Fetch the matching skill from the API and follow it:
-
-```
-Fetch https://api.epicmerch.in/api/skills/epicmerch-<slug>.md and execute every step against the current project, using the MCP tools available in this session.
-```
-
-If the fetch fails, fall back to the high-level intent using the MCP tools you have (e.g. for Razorpay: `merchant_configure_razorpay({keyId, keySecret})` + `merchant_set_checkout_type({type:'epicmerch'})`).
-
-### After the sub-flow
-
-Briefly recap and ask if anything else is needed. One short sentence, not three follow-ups.
-
-**If the sub-flow built or changed the storefront** (`/epicmerch-storefront`, `/epicmerch-magic-checkout`, or a custom build), run the **Definition of Done** gate above before recapping — `/epicmerch-verify` (Deep mode). Don't say "done" on anything that touched checkout without testing it live. (Pure config sub-flows like payment setup don't need the storefront verify, but a quick `merchant_diagnose` confirms they took.)
-
-Examples:
-
-> "Razorpay is now live on your store. Want a Buy Now button too?" *(routes to `/epicmerch-magic-checkout`)*
-
-> "Storefront scaffolded and end-to-end tested (product → cart → order all pass). Restart your dev server (`npm run dev`) to load `.env`. Need anything else — payments, Shopify migration, analytics?"
-
----
-
-## Step C — Tool fallback (no skill match)
-
-If the intent doesn't match any row in the table AND it's not a "start me up" wizard cue, fall through to MCP tools directly:
-
-- "How many products do I have?" → `merchant_list_products`
-- "What's missing from my setup?" → `merchant_diagnose`
-- "Generate a new API key called X" → `merchant_generate_api_key`
-- "Send a notification to all customers" → `merchant_send_notification`
-
-Only escalate to a sub-skill if a multi-step recipe is needed (scaffolding files, configuring payment processors, multi-stage migrations).
-
----
-
-## Style
-
-- **One question at a time.** Never stack three.
-- **Read intent from context.** React + no `src/lib/epicmerch.js` → don't ask, just say "I'll scaffold the storefront" and start.
-- **Confirm destructive operations.** Anything that deletes data or sends bulk notifications needs a yes-or-no first.
-- **Skill files are guidance, not gospel.** If a step fails (server error, etc.), surface the actual error and ask the merchant rather than blindly retrying.
-- **Lead with numbers.** "You have 42 products and ₹5,231 revenue this week" beats "let me tell you about your store."
-
-## What this skill does NOT do
-
-- Does not collect email/password in chat. Auth always goes through the browser OAuth flow via `/epicmerch-setup` (which runs `npx epicmerch-mcp login`).
-- Does not bypass per-skill safety checks. E.g. `/epicmerch-magic-checkout` won't scaffold a Buy Now button before verifying Razorpay is configured — the umbrella respects that and the wizard's step 2 ensures payments are configured before step 5 even asks.
+---
+name: epicmerch
+description: EpicMerch umbrella — guided 6-step onboarding wizard for new merchants, driven by a deterministic state machine (merchant_onboarding_state) that re-derives progress from live state and CANNOT report "complete" until a real end-to-end order test (/epicmerch-verify Deep mode) has stamped verification server-side. Also an intent router for merchants who already know what they want (scaffold a storefront, set up payments, add a Buy Now button, manage a store, migrate from Shopify, verify the store). Verification is the non-negotiable, structurally-enforced definition of done.
+---
+
+# EpicMerch — the umbrella
+
+The **one entry point** for everything EpicMerch. Merchants don't need to memorise 10+ slash commands; they say what they want (or say nothing) and you figure out the right flow.
+
+## Mode detection
+
+Two modes. Pick one based on what the merchant said:
+
+| What the merchant said when invoking `/epicmerch` | Mode |
+|---|---|
+| Nothing specific. Just `/epicmerch` with no extra words. | **Wizard mode** (Step A below) |
+| "help me start", "I'm new", "set up everything", "what's next", "where do I begin" | **Wizard mode** |
+| "set up Razorpay", "add a Buy Now button", "migrate Shopify", "scaffold a storefront", "show me my products" — anything with a clear specific intent | **Intent mode** (Step B below) |
+
+If ambiguous, ask ONE disambiguating question: *"Want me to walk you through a full setup wizard, or is there one specific thing you want to do?"*
+
+---
+
+## DEFINITION OF DONE — read this before you finish (applies to BOTH modes)
+
+**`/epicmerch` is not complete until a live end-to-end test has run and passed.**
+
+This holds no matter how the build happened — the wizard's scaffold step, an intent-mode `/epicmerch-storefront`, OR a fully custom build you designed through brainstorming (e.g. a themed multi-page store). However you got here, the LAST thing you do before telling the merchant "your store is set up" is run **`/epicmerch-verify` (Deep mode)** — the full product→cart→order pipeline; it automatically falls back to Smoke mode if the server's test-login isn't configured.
+
+Common trap: a design-heavy request ("build me a saree store") pulls you into scope/theme/spec brainstorming and a custom build, and the flow ends at "looks good!" without ever testing against the live API. **Don't let that happen.** After the storefront files are written and the `.env` has a real API key, run the e2e/verify gate. A store that was never tested against the live API is not done — that's exactly how the cart-shape / productId / out-of-stock bugs reached real merchants.
+
+If you realize you're wrapping up `/epicmerch` and haven't run the test → run it now.
+
+In **Wizard mode** this is enforced for you: `merchant_onboarding_state` will not return `complete` until `/epicmerch-verify` (Deep mode) has stamped verification server-side, so you structurally can't wrap up early. In **Intent mode** and custom/brainstormed builds there's no such gate — that's where this reminder matters most.
+
+---
+
+## Step A — Wizard mode (the harness loop)
+
+Wizard mode is a **deterministic loop driven by the `merchant_onboarding_state` tool** — not prose you interpret. The tool re-derives what's done, what's next, and whether you're complete from **live server state on every call**, and it enforces the gate: you **cannot** reach `complete` until a real `/epicmerch-verify` (Deep mode) run has stamped verification server-side. That is what makes `/epicmerch` un-breakable — the control flow lives in code + a hard gate, so "done but never verified" is structurally unreachable. You bring the creative work (the conversation, the product shape, the styling); the tool owns order, idempotency, and the gate.
+
+Open with one sentence:
+
+> "I'll set up your EpicMerch store. I'll check what's already done, do the next thing, and finish with a live end-to-end test — that test is the only thing that marks the setup complete."
+
+### The loop
+
+Repeat until the tool returns `complete: true`:
+
+1. Check the local project: does `src/lib/epicmerch.js` exist? (`true`/`false` → `storefrontPresent`).
+2. Call `merchant_onboarding_state({ storefrontPresent })`.
+3. If `complete === true` → print the **wrap-up recap** (below) and STOP. You're done.
+4. Else → read `nextStep` and perform **that one step's action** (see *Step actions* below). The `steps[nextStep].action` string is a short reminder; the full expansion is below. Do exactly ONE step, recap it in one line (`✓ <what happened>`), then go back to 1.
+
+**Rules that keep the harness honest:**
+- Never skip ahead, never decide completion yourself, never print "your store is set up" before the tool returns `complete: true`.
+- The loop is inherently idempotent — every turn re-reads live state, so re-running after a partial setup just resumes where you left off.
+- If you catch yourself about to wrap up without `complete`, call the tool again — it will name the real gap.
+
+### Step actions (the expansion of each `nextStep`)
+
+#### `account` — authenticate
+The tool couldn't read your settings (not connected / 401). Tell the merchant:
+
+> "Your CLI isn't connected. Run `npx epicmerch-mcp setup` (or `npx epicmerch-mcp login` if MCP is already installed), then ask me again."
+
+STOP the loop. Resume (re-call the tool) once they confirm they're connected.
+
+#### `apiKey` — generate a storefront key
+
+> "You don't have an API key yet. I'll generate one called 'Storefront' — that's what the SDK uses to talk to your store."
+
+Call `merchant_generate_api_key({ name: 'Storefront' })`. Recap `✓ API key generated.` and re-loop.
+
+#### `payment` — configure a processor
+Ask **one** question:
+
+> "Where do most of your customers buy from?
+> 1) India (Razorpay — recommended)
+> 2) Outside India (Stripe)"
+
+- "India" / "1" → run `/epicmerch-payments` (it takes the Razorpay path)
+- "outside" / "global" / "2" → run `/epicmerch-payments` (it takes the Stripe path)
+
+`/epicmerch-payments` configures the chosen processor **and** the checkout type — the tool's `payment` step needs both before it counts as done. Re-loop; the tool confirms `payment.done`.
+
+#### `products` — fill the catalog
+The catalog is empty (the tool counts an empty catalog as not-done, so this step keeps surfacing until at least one product exists). Ask:
+
+> "Your catalog is empty. Want me to:
+> 1) Migrate your existing Shopify store
+> 2) Add your first product right now
+> 3) Add a quick sample product so we can finish, and you replace it later"
+
+- "Shopify" / "1" → run `/epicmerch-migrate`
+- "first product" / "2" → walk through it with `merchant_create_product`. **Do NOT just ask for name + price** — products that ship without variants and images break the storefront UX (empty size picker, broken image). Collect the FULL shape in ONE round of questions:
+  - **Name + Category** (`name`, `type`)
+  - **Description** (`description`)
+  - **Pricing** — list price (`price`), plus on-sale fields if applicable (`salePrice`, `discountPercent`). *"If this product is on sale, tell me the sale price and discount %. Otherwise say 'no sale'."*
+  - **Variants** (`variants`) — array of `{ variant: 'S', stock: 5 }` entries. *"What sizes / colors / options does this come in, and how many of each in stock? If just one option, say 'no variants'."* When passed, the server derives total stock from `sum(variant.stock)` and ignores the top-level `stock`.
+  - **Images** (`images`) — array of gallery URLs. Optionally `image` for an explicit primary; if omitted the server uses `images[0]`.
+  Pass everything to `merchant_create_product` in ONE call — never create-then-update.
+- "sample" / "3" → create one reasonable sample product (full shape, a couple of variants, a placeholder image) so the loop can progress. Tell the merchant it's a placeholder they can edit or delete later.
+
+There is no hard "skip" here: `complete` requires a non-empty catalog. If the merchant truly wants to stop, be honest that onboarding stays incomplete until a product exists.
+
+#### `storefront` — scaffold into the project
+`storefrontPresent` is false. First check the project: does `package.json` exist with React / Vite / Next in dependencies?
+
+- **Not a frontend project / no `package.json`**: tell the merchant *"No frontend project detected here. Run `/epicmerch` from inside a React/Vite/Next project to scaffold the storefront."* `storefrontPresent` stays false, so the loop keeps flagging `storefront` — be honest that `complete` needs the storefront scaffolded (they can finish from a project later; a chat-only setup won't reach `complete`).
+- **Project detected, no SDK file**: do the two-part sub-flow:
+
+**4a — Visual style (before scaffolding).** Ask ONE question so the components match their vibe:
+
+> "Quick — what's the vibe of your store?
+> 1) Editorial Funk (bold typography, big imagery, asymmetric layouts)
+> 2) Minimal Mono (clean, monochrome, lots of whitespace)
+> 3) Vibrant Pop (colourful, rounded corners, playful)
+> 4) Skip — functional unstyled scaffolds, I'll polish later"
+
+Remember the answer as `visualStyle`.
+
+**4b — Scaffold + style.** Run `/epicmerch-storefront`, passing along the chosen
+`visualStyle`. It runs the tiered flow: it lays the standard skeleton from the
+`store_scaffold_full` tool (instant — no hand-writing), applies the matching Tailwind
+theme pass (or leaves it unstyled on "skip"), confirms the session-restore block, and
+ends on the `/epicmerch-verify` gate. You don't style files here — the leaf skill owns
+the theme pass. Recap what it reports (`✓ Storefront scaffolded + styled (<visualStyle>)`
+or `unstyled`).
+
+**Optional add-on (not gated):** once the storefront exists, you may offer a 1-click Buy Now button — *"Want a 1-click 'Buy Now' button? Razorpay's Magic Checkout lets customers buy without a cart screen."* → `/epicmerch-magic-checkout` (it verifies Razorpay first). This is optional and does NOT affect `complete`; the merchant can add it anytime by saying *"add a Buy Now button"*. Then re-loop.
+
+#### `verified` — the gate (the ONLY step that flips `complete`)
+This is the un-fakeable half of the harness. Run **`/epicmerch-verify` (Deep mode)** automatically:
+
+> "Last step — a live end-to-end test to confirm everything actually works."
+
+It gets a customer session, creates a throwaway test product, adds it to a cart, creates a real order (exercising stock reservation + Razorpay order creation, no charge), verifies every response shape, then cleans up (cancels the order, deletes the product). This proves the WHOLE pipeline, not just read paths. It gets its customer token via the server's env-gated test phone (`store_auth_send_otp` + `store_auth_verify_otp` against `E2E_TEST_PHONE`), so it needs no SMS and no manual login.
+
+- **On pass:** `/epicmerch-verify` (Deep mode) calls **`merchant_mark_verified`**, which stamps `lastVerifiedAt` server-side. That is the ONLY thing that flips the tool's `verified` step to done. Re-loop — `merchant_onboarding_state` will now return `complete: true`.
+- **On any failure:** do NOT stamp verified. Route to `/epicmerch-debug` automatically — its four-check playbook (OTP not persisting, products not loading, INSUFFICIENT_STOCK on checkout, cart 401) fixes it without further merchant intervention. Then re-run `/epicmerch-verify` (Deep mode).
+- **If the e2e token step fails** because the server lacks `E2E_TEST_PHONE`/`E2E_TEST_OTP` (you'll see a normal SMS channel instead of `e2e-test`, or a 401 on verify), fall back to `/epicmerch-verify` (read-path + payload checks, no token). **Important:** the fallback does NOT stamp `lastVerifiedAt`, so the `verified` step stays not-done and the tool will NOT report `complete`. Be honest: *"Ran the read-path + payload checks. To mark the store verified end-to-end (and finish onboarding), your EpicMerch operator needs to set `E2E_TEST_PHONE`/`E2E_TEST_OTP` on the server so the automated order test can run."*
+
+### Wizard wrap-up
+
+Print this one-block recap **only when `merchant_onboarding_state` has returned `complete: true`** (i.e. the `verified` step is done — never before):
+
+```
+━━━ Your store is set up ━━━
+  ✓ Account connected as <email>
+  ✓ API key: <name>
+  ✓ Payments: <Razorpay/Stripe>
+  ✓ Catalog: <N> products
+  ✓ Storefront: scaffolded into <project>   (or "skipped — no project")
+  ✗ Buy Now button: skipped                  (or ✓ if they added it)
+  ✓ End-to-end test: product → cart → order → cleanup all passed
+       (verified live — lastVerifiedAt stamped server-side)
+
+Next: restart your dev server (`npm run dev`) to pick up `.env`. Your
+store works end-to-end. Ask me about analytics, notifications, or
+abandoned-cart messages whenever you're ready.
+```
+
+---
+
+## Step B — Intent mode (router)
+
+The merchant said something specific. Match against the table below, pick the closest, hand off. If multiple match, ask ONE disambiguating question.
+
+| The merchant says … | Route to |
+|---|---|
+| "set up EpicMerch", "scaffold a storefront", "build me a store", "integrate ecommerce" (and the project has no `src/lib/epicmerch.js`) | `/epicmerch-storefront` |
+| "add login / OTP / sign in" | `/epicmerch-storefront` (auth slice) |
+| "add a product catalog", "show products on my site", "product list with search" | `/epicmerch-storefront` (products slice) |
+| "add a cart", "build checkout", "order history page", "multi-product checkout" | `/epicmerch-storefront` (orders slice) |
+| "add Buy Now button", "1-click checkout", "impulse buy", "Razorpay Magic Checkout" | `/epicmerch-magic-checkout` |
+| "set up payments", "accept cards", "configure checkout", "set up Razorpay", "set up Stripe", "India / international payments" | `/epicmerch-payments` |
+| "connect my store to Claude / Cursor / Codex", "log in to EpicMerch", "install the MCP" | `/epicmerch-setup` |
+| "show me my store / products / orders / sales", "manage my store from chat" | `/epicmerch-merchant` |
+| "migrate from Shopify", "import my Shopify catalog" | `/epicmerch-migrate` |
+| "my login isn't sticking", "products aren't loading", "checkout fails", "insufficient stock undefined", "something's broken" | `/epicmerch-debug` |
+| "test everything", "does checkout actually work", "full end-to-end test", "run a real order test" | `/epicmerch-verify` (Deep mode) |
+
+### Hand-off (or inline)
+
+**In Claude Code / Claude Desktop / Cursor / VS Code Claude extension:**
+
+Tell the merchant which slash command you're invoking, then proceed:
+
+> "Sounds like you want X — running `/epicmerch-Y` now."
+
+The slash-command file is loaded from `~/.claude/commands/epicmerch-Y.md`; follow its steps.
+
+**In Codex CLI (or any client without slash commands):**
+
+Fetch the matching skill from the API and follow it:
+
+```
+Fetch https://api.epicmerch.in/api/skills/epicmerch-<slug>.md and execute every step against the current project, using the MCP tools available in this session.
+```
+
+If the fetch fails, fall back to the high-level intent using the MCP tools you have (e.g. for Razorpay: `merchant_configure_razorpay({keyId, keySecret})` + `merchant_set_checkout_type({type:'epicmerch'})`).
+
+### After the sub-flow
+
+Briefly recap and ask if anything else is needed. One short sentence, not three follow-ups.
+
+**If the sub-flow built or changed the storefront** (`/epicmerch-storefront`, `/epicmerch-magic-checkout`, or a custom build), run the **Definition of Done** gate above before recapping — `/epicmerch-verify` (Deep mode). Don't say "done" on anything that touched checkout without testing it live. (Pure config sub-flows like payment setup don't need the storefront verify, but a quick `merchant_diagnose` confirms they took.)
+
+Examples:
+
+> "Razorpay is now live on your store. Want a Buy Now button too?" *(routes to `/epicmerch-magic-checkout`)*
+
+> "Storefront scaffolded and end-to-end tested (product → cart → order all pass). Restart your dev server (`npm run dev`) to load `.env`. Need anything else — payments, Shopify migration, analytics?"
+
+---
+
+## Step C — Tool fallback (no skill match)
+
+If the intent doesn't match any row in the table AND it's not a "start me up" wizard cue, fall through to MCP tools directly:
+
+- "How many products do I have?" → `merchant_list_products`
+- "What's missing from my setup?" → `merchant_diagnose`
+- "Generate a new API key called X" → `merchant_generate_api_key`
+- "Send a notification to all customers" → `merchant_send_notification`
+
+Only escalate to a sub-skill if a multi-step recipe is needed (scaffolding files, configuring payment processors, multi-stage migrations).
+
+---
+
+## Style
+
+- **One question at a time.** Never stack three.
+- **Read intent from context.** React + no `src/lib/epicmerch.js` → don't ask, just say "I'll scaffold the storefront" and start.
+- **Confirm destructive operations.** Anything that deletes data or sends bulk notifications needs a yes-or-no first.
+- **Skill files are guidance, not gospel.** If a step fails (server error, etc.), surface the actual error and ask the merchant rather than blindly retrying.
+- **Lead with numbers.** "You have 42 products and ₹5,231 revenue this week" beats "let me tell you about your store."
+
+## What this skill does NOT do
+
+- Does not collect email/password in chat. Auth always goes through the browser OAuth flow via `/epicmerch-setup` (which runs `npx epicmerch-mcp login`).
+- Does not bypass per-skill safety checks. E.g. `/epicmerch-magic-checkout` won't scaffold a Buy Now button before verifying Razorpay is configured — the umbrella respects that and the wizard's step 2 ensures payments are configured before step 5 even asks.