epicmerch-mcp 1.3.19 → 1.3.21

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.
 ```