@sellhapi/mcp 0.0.0-stage → 0.1.1

package/dist/resources/build-rules.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * BuildGuard rules — extracted from buildGuard.service.ts.
+ * Code that violates these rules will be rejected by push_code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILD_RULES = void 0;
+exports.BUILD_RULES = `
+# SellHapi BuildGuard Rules
+
+Your code MUST pass all these rules or push_code will reject it with specific violation details.
+
+## APPROVED IMPORTS (only these are allowed)
+
+Exact matches:
+  @sellhapi/studio-runtime
+  react
+  react-dom
+  react-dom/client
+  react/jsx-runtime
+  react/jsx-dev-runtime
+  framer-motion
+  clsx
+  date-fns
+  zod
+  lucide-react
+
+Subpath imports allowed:
+  date-fns/*
+  react-dom/*
+  react/*
+
+Relative imports (./ and ../) are always allowed between project files.
+
+EVERYTHING ELSE IS BLOCKED — no axios, no tailwindcss, no lodash, no node builtins.
+
+## HARD VIOLATIONS (build fails)
+
+1. DISALLOWED IMPORTS
+   Any import not in the approved list above.
+   Violation: "Import from X is not allowed."
+
+2. DYNAMIC REQUIRE
+   require() with non-string argument or unapproved package.
+   Violation: "Dynamic require() is not allowed."
+
+3. DYNAMIC IMPORT
+   import() expressions (as opposed to static import statements).
+   Violation: "Dynamic import() is not allowed in generated storefront code."
+
+4. CODE INJECTION
+   eval(), new Function(), Function() — all blocked.
+   Violation: "eval()/Function() is not allowed — code injection risk."
+
+5. RAW NETWORK ACCESS
+   fetch(), new XMLHttpRequest(), new WebSocket() — all blocked.
+   Violation: "Direct fetch() calls are not allowed. Use hooks from @sellhapi/studio-runtime instead."
+   All data must flow through runtime hooks.
+
+6. DANGEROUS GLOBALS
+   Blocked property access:
+   - process.env
+   - document.cookie, document.write(), document.writeln(), document.domain, document.execCommand()
+   - window.fetch, window.eval, window.Function
+   - window.XMLHttpRequest, window.WebSocket
+   - window.localStorage, window.sessionStorage, window.indexedDB
+   - navigator.sendBeacon
+   - Standalone: localStorage, sessionStorage, indexedDB
+   Violation: "X is not allowed in storefront code."
+
+7. SUBSCRIPT ACCESS ON GLOBALS
+   window["fetch"], globalThis["eval"], self["XMLHttpRequest"] — all blocked.
+   Violation: "Subscript access on 'window' is not allowed."
+
+8. DANGEROUS JSX
+   dangerouslySetInnerHTML — blocked.
+   Violation: "dangerouslySetInnerHTML is not allowed — XSS vector."
+
+9. MISSING CART DRAWER
+   If any file uses useCart or addItem, <CartDrawer /> MUST be rendered somewhere.
+   Violation: "useCart/addItem is used but <CartDrawer /> is not rendered anywhere."
+
+## SOFT WARNINGS (build passes, but flagged)
+
+1. product.images[N].url — WRONG. images is string[], each element IS the URL.
+   Fix: use images[N] directly or product.imageUrl for primary.
+
+2. addItem() without type field — CartItem.type is required.
+   Fix: add type: 'physical' | 'digital' to every addItem() call.
+
+3. campaign.raised / campaign.goalAmount — WRONG field names.
+   Fix: use campaign.raisedAmountKobo / campaign.goalAmountKobo (divide by 100 for display).
+
+4. ticketType.soldCount — WRONG. Use ticketType.sold.
+
+## REQUIRED: data-region ATTRIBUTES
+
+Every section that renders live data MUST have a data-region attribute on its outermost container element.
+This is required for Studio's region selector, Layers panel, and entity injection to work.
+
+Required attributes:
+  data-region="<slug>"    — unique kebab-case identifier, e.g. "hero", "products", "appointments"
+  data-label="<name>"     — human-readable label shown in Studio UI, e.g. "Products Section"
+  data-scope="content"    — always "content" for data-driven sections
+
+Example:
+  <section data-region="products" data-label="Products" data-scope="content">
+    {/* useProducts() renders here */}
+  </section>
+
+  <section data-region="appointments" data-label="Consultations" data-scope="content">
+    {/* useServices() renders here */}
+  </section>
+
+ALSO add data-region to static layout sections (hero, footer, nav) — these don't need data hooks but must still be selectable:
+  <section data-region="hero" data-label="Hero" data-scope="layout">
+  <header data-region="navigation" data-label="Navigation" data-scope="navigation">
+  <footer data-region="footer" data-label="Footer" data-scope="layout">
+
+If you use ANY data hook (useProducts, useServices, useEvents, etc.) without ANY data-region attributes, the build will warn you.
+
+## FILE STRUCTURE
+
+Required: App.tsx (or App.jsx) as entry point.
+Recommended structure:
+  App.tsx              — main component with routing
+  components/          — reusable UI components
+  pages/               — route-level pages (ProductPage, EventPage, etc.)
+  styles/              — optional shared styles
+
+## BUNDLE SIZE LIMITS
+
+Hard limit: 4 MB (build fails above this)
+Warning: 3.5 MB (runtime baseline is ~2.1 MB — aim to keep user code under 1.4 MB)
+
+## STYLING
+
+Use inline styles (React style objects) — this is the convention.
+CSS modules work but are not typical.
+Tailwind is NOT available (not in approved imports).
+framer-motion is available for animations.
+
+## KEY PATTERNS
+
+1. All data comes from hooks. NEVER hardcode product names, prices, or content.
+2. Show loading states: if (loading) return <div>Loading...</div>
+3. Show empty states: if (data.length === 0) return <div>No items yet</div>
+4. Format prices: (priceKobo / 100).toLocaleString() for Naira display
+5. Use useHashRouter() for multi-page navigation
+6. Commerce actions return { paymentLink } — redirect: window.location.href = result.paymentLink
+`;

package/dist/resources/capability-patterns.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Per-capability UX patterns, anti-patterns, and data shape rules.
+ *
+ * Previously a hand-maintained static string — now fetched live from sell_api
+ * which serializes STUDIO_PROMPT_REGISTRY on every request. Zero drift.
+ *
+ * FALLBACK_PATTERNS is used when the API call fails (e.g. network error,
+ * server cold-starting). It reflects the last known good state and should
+ * be updated whenever the registry diverges significantly.
+ */
+/**
+ * Fetch live capability patterns from sell_api.
+ * Falls back to FALLBACK_PATTERNS on any error — never throws.
+ */
+export declare function buildCapabilityPatterns(): Promise<string>;

package/dist/resources/capability-patterns.js

@@ -0,0 +1,339 @@
+"use strict";
+/**
+ * Per-capability UX patterns, anti-patterns, and data shape rules.
+ *
+ * Previously a hand-maintained static string — now fetched live from sell_api
+ * which serializes STUDIO_PROMPT_REGISTRY on every request. Zero drift.
+ *
+ * FALLBACK_PATTERNS is used when the API call fails (e.g. network error,
+ * server cold-starting). It reflects the last known good state and should
+ * be updated whenever the registry diverges significantly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCapabilityPatterns = buildCapabilityPatterns;
+const client_js_1 = require("../client.js");
+/**
+ * Fetch live capability patterns from sell_api.
+ * Falls back to FALLBACK_PATTERNS on any error — never throws.
+ */
+async function buildCapabilityPatterns() {
+    try {
+        const data = await (0, client_js_1.get)("/api/mcp/capability-patterns");
+        if (data?.patterns)
+            return data.patterns;
+        return FALLBACK_PATTERNS;
+    }
+    catch {
+        return FALLBACK_PATTERNS;
+    }
+}
+/** Last-known-good static fallback. Used when the API is unreachable. */
+const FALLBACK_PATTERNS = `
+# SellHapi Capability Patterns
+
+## PHYSICAL PRODUCTS
+
+Route: #/products (list) + product quick-view modal on card click
+Hooks: useProducts(options?), useProduct(id), useCart(), useCartCheckout()
+
+useProducts default limit is 6. Always pass an explicit limit:
+  - Homepage preview: useProducts({ limit: 4 }) — show a teaser, not the full catalog
+  - Full products page: useProducts({ limit: 200 }) — load the full catalog
+
+MANDATORY: Product list is on a dedicated #/products page (not homepage).
+
+MANDATORY: Homepage product section is a TEASER — visually distinct from the full products page.
+  It is an editorial/marketing section: large dominant images, 2-col or 4-col cards, product name + price only.
+  End it with a "Shop All Products →" button/link that navigates to #/products.
+  Do NOT reuse the same component as the /products page grid — different layout, different visual weight.
+  Example structure:
+    <section> {/* homepage teaser */}
+      <h2>Our Collection</h2>
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(4, 1fr)', gap: 24 }}>
+        {products.slice(0, 4).map(p => <HomepageProductCard key={p.id} product={p} />)}
+      </div>
+      <button onClick={() => navigate('#/products')}>Shop All Products →</button>
+    </section>
+
+MANDATORY: Product detail opens in a MODAL overlay on card click — never navigate to a separate page for product detail.
+  Modal shows: images (filtered for non-video), name, price, compareAtPriceKobo strikethrough, discountBadge,
+    variant selector (chip/pill buttons per option group), quantity stepper with stock cap,
+    "Add to Cart" button, policies section (return/shipping), reviews section.
+  After addItem(): MUST call openCart() to show the cart drawer.
+
+PAGINATION on #/products page (load more pattern):
+  const [limit, setLimit] = React.useState(12);
+  const { data: products } = useProducts({ limit });
+  // Show "Load More" only when the returned count equals the current limit (more may exist)
+  {products?.length === limit && (
+    <button onClick={() => setLimit(l => l + 12)}>Load More</button>
+  )}
+
+Price fields:
+  - priceKobo: main price (divide by 100 for display). BIGINT from API — always wrap in Number(): Number(product.priceKobo)
+  - originalPriceKobo: pre-discount / strikethrough price (number | undefined). Show as strikethrough when originalPriceKobo > priceKobo.
+  - discountBadge: pre-formatted sale label e.g. "20% Off" (string | null). Show as a badge overlay on the card and in the modal header. When present, originalPriceKobo is also set — use it as the strikethrough price.
+  - priceRange: { minKobo, maxKobo } — present when variants have different prices. Display as "₦X – ₦Y". Show instead of a single price when minKobo !== maxKobo.
+
+Variant shape (CRITICAL — no top-level size/color fields):
+  Each variant has: { id, options: Array<{ field: string; value: string }>, priceKobo?, stock? }
+  options is a generic attribute list — e.g. [{field:"Color",value:"Red"},{field:"Size",value:"XL"}]
+  Render variant groups by grouping on options[*].field and showing chip/pill buttons per group.
+
+  Correct variant label helper:
+    function variantLabel(v) { return v.options?.map(o => o.value).join(' / ') || 'Standard'; }
+
+  Correct variant selector pattern:
+    // Group options by field
+    const fields = [...new Set(variants.flatMap(v => v.options.map(o => o.field)))];
+    // For each field, show a row of pill buttons
+    fields.map(field => (
+      <div key={field}>
+        <span>{field}</span>
+        {[...new Set(variants.flatMap(v => v.options.filter(o => o.field === field).map(o => o.value)))].map(val => (
+          <button key={val} onClick={() => setSelected(field, val)}
+            style={{ fontWeight: isSelected(field, val) ? 'bold' : 'normal' }}>{val}</button>
+        ))}
+      </div>
+    ))
+
+Stock rules:
+  - stock: null = no stock tracking — treat as unlimited (never show "Out of Stock")
+  - stock: 0 = tracked and out of stock — show "Out of Stock", disable Add to Cart
+  - stock > 0 = tracked, cap quantity stepper at this value
+  - inStock: boolean — convenience field for grid card sold-out badge
+  Qty stepper: const maxStock = selected?.stock != null ? Number(selected.stock) : (product?.stock != null ? Number(product.stock) : Infinity);
+  Disable '+' when qty >= maxStock.
+
+Image filtering + URL encoding:
+  Some image URLs contain spaces — always encode before use in <img src>.
+  function imageList(imgs) {
+    return (imgs ?? [])
+      .filter(u => !/\.(mp4|webm|mov)$/i.test(u))
+      .map(u => u.includes(' ') ? u.split('/').map(encodeURIComponent).join('/') : u);
+  }
+  Use imageList(product.images) everywhere — never pass the raw images array to <img src>.
+
+Anti-patterns:
+  - NEVER hardcode product data — always use useProducts()
+  - NEVER access product.images[0].url — images is string[], use images[0] directly
+  - NEVER call addItem() without type: 'physical' or type: 'digital'
+  - NEVER use product.price or product.priceNaira — use product.priceKobo
+  - NEVER use v.name / v.size / v.color for variant labels — iterate v.options array
+  - NEVER use local state as substitute for openCart() — cart drawer won't appear without it
+  - NEVER show all products on the homepage — use a 4-item teaser + "Shop All Products →" CTA
+  - NEVER call useProducts() without an explicit limit — default is 6, silently truncates catalog
+
+---
+
+## DIGITAL PRODUCTS
+
+Route: #/digital/:id → pages/DigitalProductPage.tsx
+Hooks: useDigitalProducts(), useDigitalProduct(id), useProductCheckout() or useCart()
+
+List page: product cards with imageUrl, name, priceKobo/100, description snippet.
+Detail page: full product info + "Buy Now" (useProductCheckout) or "Add to Cart" (useCart).
+
+Anti-patterns:
+  - Same as physical products (images is string[], priceKobo not price, etc.)
+  - NEVER use useProductCheckout() for multi-product stores — use cart pattern instead
+
+---
+
+## SERVICES
+
+Route: #/services/:id → pages/ServicePage.tsx
+Hooks: useServiceListings(), useServiceListing(id), useCheckoutService(), useInitiateEngagement()
+
+List page: service cards with coverImage, title, category, priceKobo/100.
+Detail page: full service info, add-ons, sub-services, customer form, checkout button.
+
+---
+
+## APPOINTMENTS
+
+Hooks: useServices(), useAvailableDates({ serviceId, month }), useAvailability({ serviceId, from, to }), useBookAppointment()
+
+Flow:
+  1. Show services list (useServices) — each card shows name, duration, price
+  2. Customer picks a service → show month calendar (useAvailableDates gives available YYYY-MM-DD dates)
+  3. Customer picks a date → show time slots: useAvailability({ serviceId, from: date, to: date })
+     NOTE: to must be the SAME date as from — the hook internally extends it to end-of-day
+  4. Customer picks a slot — render slot.startTime formatted for display
+  5. Show booking form (name, email, phone)
+  6. Submit: useBookAppointment().book({ serviceId, dateTime: slot.startTime, customerName, customerEmail, customerPhone })
+     Returns { paymentLink } — redirect with window.location.href = result.paymentLink
+
+Price display:
+  service.priceKobo is a BIGINT from the API — Sequelize returns it as a STRING.
+  ALWAYS wrap in Number(): Number(service.priceKobo) before any arithmetic or comparison.
+  Display: ₦{(Number(service.priceKobo) / 100).toLocaleString()}
+
+Slot filtering: DO NOT filter slots by status. useAvailability returns only bookable slots — pass them all through.
+
+Anti-patterns:
+  - NEVER call initiate() for appointments — always use book(). useBookAppointment returns { book, initiate (alias), loading, error }
+  - NEVER pass slotId — pass dateTime: slot.startTime (ISO datetime string from useAvailability result)
+  - NEVER use slot.durationMinutes — it doesn't exist on AvailabilitySlot
+  - NEVER hardcode service names/prices — always use useServices()
+  - NEVER skip the date→slot two-step — must pick date first, then load slots for that date
+  - NEVER filter slots with slot.status === 'available' — drops all slots; let the hook decide
+
+---
+
+## EVENTS
+
+Route: #/events/:id → pages/EventPage.tsx
+Hooks: useEvents(), useEvent(id), usePurchaseTickets(), useCreateRSVP()
+
+List page: event cards with name, startsAt, endsAt, location, imageUrl.
+  Date display: use event.startsAt (ISO string) — NOT event.date (does not exist).
+  Format: new Date(event.startsAt).toLocaleDateString('en-NG', { weekday: 'short', day: 'numeric', month: 'short', year: 'numeric' })
+  If endsAt differs from startsAt date, show a range: "Fri, 5 Sep – Sun, 7 Sep 2025"
+Detail page: event info + ticket type selection + customer form + purchase button.
+
+Anti-patterns:
+  - NEVER use event.date — the fields are startsAt and endsAt (ISO strings)
+  - NEVER use ticketType.soldCount — use ticketType.sold
+  - NEVER hardcode event data — always use useEvents()
+  - Ticket availability: ticketType.available (number | null)
+
+---
+
+## DONATIONS
+
+Route: #/campaigns/:id → pages/CampaignPage.tsx
+Hooks: useDonationCampaigns(), useDonationCampaign(id), useDonate()
+
+List page: campaign cards with name, imageUrl, progress bar (raisedAmountKobo / goalAmountKobo).
+Detail page: campaign info + amount input + customer form + donate button.
+
+Anti-patterns:
+  - NEVER use campaign.raised or campaign.raisedAmount — use campaign.raisedAmountKobo
+  - NEVER use campaign.goalAmount — use campaign.goalAmountKobo (can be null)
+  - Progress bar: (raisedAmountKobo / goalAmountKobo) * 100 — guard for null goalAmountKobo
+
+---
+
+## MEMBERSHIPS
+
+Route: #/membership/:tierId → pages/MembershipPage.tsx
+Hooks: useMemberships(), useSubscribeMembership()
+
+List page: tier cards with name, priceKobo/100, billingPeriod label, benefits list.
+  billingPeriod labels: "monthly" → "/month", "yearly" → "/year", "one_time" → no label.
+  benefits: (tier.benefits ?? []).map(...) — can be null.
+Detail page: tier info + benefits checklist + customer form + subscribe button.
+
+Anti-patterns:
+  - NEVER use tier.price or tier.amount — use tier.priceKobo
+  - NEVER use tier.features or tier.perks — use tier.benefits (string[] | null)
+  - NEVER display "annual" — the SDK uses "yearly"
+  - NEVER assume tier.imageUrl exists — it is string | null, conditionally render
+
+---
+
+## CONTENT & CMS
+
+Hooks: useContentImages(), useContentVideos(), useContentTestimonials(), useContentFaqs(),
+       useContentStats(), useContentFeatures(), useContentTeamMembers(), useContentForm(formId), useSubmitForm(formId)
+
+NOTE: The team hook is useContentTeamMembers() — NOT useContentTeam() (does not exist).
+
+All content hooks return FetchState<ContentItem[]>.
+Forms: render fields dynamically from form.fields array — never hardcode form structure.
+
+---
+
+## LISTINGS
+
+Route: #/listing/:slugOrId
+Hooks: useListings(), useListingDetail(slug), useListingFilters()
+
+Action hooks depend on listing type:
+  - Payment listings: useListingPayment(id).checkout(customer)
+  - Enquiry listings: useListingEnquiry(id).submit({ name, email, message })
+  - Application listings: useListingApplication(id).submit({ name, email, coverNote })
+  - Reserve listings: useListingReserve(id).reserve()
+  - Download listings: useListingDownload(id).download()
+
+---
+
+## CUSTOMER ACCOUNTS
+
+Hooks: useCustomerAuth()
+
+Auth flow: signUp(name, email, password) / signIn(email, password) / signOut()
+Check: isLoggedIn (NOT isAuthenticated)
+Protected routes: if (!isLoggedIn) show sign-in form.
+Account dashboard: useMyOrders(), useMyAppointments(), useMyPurchases(), useMyMembership(), useMyProfile()
+
+---
+
+## CART DRAWER THEMING
+
+CartDrawer reads CSS custom properties from document.documentElement to match the site design.
+You MUST set these in a useEffect in App.tsx (or a top-level layout component) so the drawer
+inherits the correct colors and font instead of falling back to defaults.
+
+Required pattern in App.tsx:
+  useEffect(() => {
+    const root = document.documentElement;
+    root.style.setProperty('--sh-drawer-bg',           '#ffffff');   // drawer background
+    root.style.setProperty('--sh-drawer-overlay',      'rgba(0,0,0,0.5)');
+    root.style.setProperty('--sh-drawer-text',         '#111111');   // primary text
+    root.style.setProperty('--sh-drawer-muted',        '#666666');   // secondary/muted text
+    root.style.setProperty('--sh-drawer-border',       '#e5e5e5');   // dividers
+    root.style.setProperty('--sh-drawer-input-border', '#d1d5db');   // input field borders
+    root.style.setProperty('--sh-drawer-accent',       '#000000');   // button/CTA background
+    root.style.setProperty('--sh-drawer-accent-text',  '#ffffff');   // button/CTA text
+    root.style.setProperty('--sh-drawer-font',         'inherit');   // font-family
+  }, []);
+
+Replace the values above with colors that match the site's palette (e.g. brand primary for accent).
+
+Anti-patterns:
+  - NEVER skip this useEffect — CartDrawer will render with mismatched default colors
+  - NEVER apply these properties to a scoped container — they MUST go on document.documentElement
+
+---
+
+## UNIVERSAL RULES
+
+1. Price display: always (priceKobo / 100).toLocaleString() — prefix with ₦
+2. Empty states: always handle empty arrays gracefully — never show blank sections
+3. Loading states: always show a loading indicator while data is being fetched
+4. Images: always handle null imageUrl — show placeholder or hide the image element
+5. Hash routing: use useHashRouter() for navigation between pages
+6. Commerce results: all initiate/checkout functions return { paymentLink } — redirect with window.location.href
+7. Cart pattern: addItem() → openCart() → CartDrawer shows → customer proceeds to checkout
+
+## LAYOUT ALIGNMENT — MANDATORY
+
+Every section on every page MUST share the same horizontal container. Nav, hero, product grids,
+content sections, and footer must all align to the same left and right edges.
+
+MANDATORY pattern — one shared container constant:
+  const CONTAINER: React.CSSProperties = {
+    maxWidth: 1200,
+    margin: '0 auto',
+    padding: '0 24px',
+  };
+  // Apply to every section wrapper and the nav inner wrapper:
+  <nav><div style={CONTAINER}>...</div></nav>
+  <section><div style={CONTAINER}>...</div></section>
+  <footer><div style={CONTAINER}>...</div></footer>
+
+Rules:
+  - Nav inner content MUST use the same CONTAINER — nav edges must align with content edges
+  - Full-bleed backgrounds (hero color, section color) live on the outer element; content is always inside CONTAINER
+  - NEVER give different sections different maxWidth or padding values
+  - NEVER use margin: '0 48px' on one section and padding: '0 24px' on another
+  - NEVER let a section push wider or narrower than the nav content width
+  - Grid gaps, card padding, and inner spacing are fine to vary — only the outer container must be consistent
+
+Anti-patterns:
+  - Nav at full width while sections have a max-width container → WRONG
+  - Hero section edge-to-edge but product section indented → WRONG
+  - Different sections using different padding (e.g. 16px vs 40px left/right) → WRONG
+`;

package/dist/resources/design-direction-schema.d.ts

@@ -0,0 +1,11 @@
+/**
+ * DesignDirection schema resource.
+ *
+ * Exposes the exact DesignDirection TypeScript interface + field documentation
+ * so AI clients can generate a valid direction JSON themselves (zero SellHapi
+ * Claude cost) and submit it via the apply_design_direction tool.
+ *
+ * Mirrors the interface in generate2.controller.ts. Keep in sync when that
+ * interface changes.
+ */
+export declare const DESIGN_DIRECTION_SCHEMA = "\n# SellHapi Design Direction Schema\n\nUse this schema to generate a `DesignDirection` JSON object and submit it via\n`apply_design_direction`. This path costs SellHapi nothing \u2014 your own LLM does\nthe work. Only fall back to `set_design_direction` if you cannot generate\nstructured JSON reliably.\n\n---\n\n## Top-level object\n\n```typescript\n{\n  businessType:    string;           // REQUIRED. e.g. \"fashion\", \"bakery\", \"photography\"\n  capabilityIds:   string[];         // REQUIRED. Active capability IDs. See /api/mcp/capabilities.\n  capabilitySlots?: CapabilitySlot[]; // Optional. Richer slot-per-purpose model (see below).\n  pages:           Page[];           // REQUIRED. Non-empty. One entry per storefront page.\n  visualDirection: VisualDirection;  // REQUIRED. All visual tokens.\n  businessContext: BusinessContext;  // REQUIRED. Business identity.\n  storefrontConfig?: StorefrontConfig; // Optional. Only for storefront-mode projects.\n  displayModes?: DisplayModes;       // Optional. Product display preferences.\n}\n```\n\n---\n\n## Page\n\nEach page the storefront will have. Minimum 1, typically 3\u20136.\n\n```typescript\n{\n  slug:     string;    // URL-safe identifier. e.g. \"home\", \"products\", \"about\", \"contact\"\n  title:    string;    // Display name. e.g. \"Home\", \"Shop\", \"About Us\"\n  sections: string[];  // Section labels in order. e.g. [\"hero\", \"product-grid\", \"testimonials\", \"newsletter\"]\n}\n```\n\n**Section label conventions:**\n- Use lowercase kebab-case\n- Should describe content purpose: \"hero\", \"featured-products\", \"services-list\", \"booking-cta\",\n  \"testimonials\", \"faq\", \"team\", \"newsletter\", \"about-story\", \"contact-form\", \"events-grid\"\n- Capability-specific sections should reference the capability:\n  \"appointment-booking\", \"donation-campaigns\", \"membership-tiers\", \"events-list\"\n\n**Common page structures:**\n\nPhysical products store:\n```\nhome:     [\"hero\", \"featured-products\", \"collections\", \"testimonials\", \"newsletter\"]\nproducts: [\"filter-bar\", \"product-grid\", \"pagination\"]\nabout:    [\"brand-story\", \"values\", \"team\"]\ncontact:  [\"contact-form\", \"location-map\"]\n```\n\nService business:\n```\nhome:     [\"hero\", \"services-overview\", \"how-it-works\", \"testimonials\", \"booking-cta\"]\nservices: [\"services-list\", \"pricing\"]\nabout:    [\"our-story\", \"team\", \"credentials\"]\ncontact:  [\"contact-form\", \"faq\"]\n```\n\n---\n\n## VisualDirection\n\nAll fields except the optional ones are required.\n\n```typescript\n{\n  // Descriptive aesthetic \u2014 free text. e.g. \"Minimal luxury\", \"Vibrant street market\"\n  style:           string;\n\n  primaryColor:    string;   // Main brand color \u2014 hex. e.g. \"#1a1a2e\"\n  accentColor:     string;   // CTA / highlight color \u2014 hex. e.g. \"#e94560\"\n  backgroundColor: string;   // Page background \u2014 hex. Can be dark, cream, off-white.\n  surfaceColor:    string;   // Card / panel background \u2014 hex.\n  textColor:       string;   // Primary text color \u2014 hex.\n\n  headingFont:     string;   // Google Fonts name for headings. e.g. \"Playfair Display\", \"Space Grotesk\"\n  bodyFont:        string;   // Google Fonts name for body copy. e.g. \"Inter\", \"DM Sans\"\n  fontStyle:       string;   // Description. e.g. \"editorial serif headings with clean sans body\"\n\n  // Enum values \u2014 use exactly as written:\n  cardStyle:    \"flat\" | \"soft-shadow\" | \"bordered\" | \"glassmorphism\";\n  buttonStyle:  \"pill\" | \"rounded\" | \"sharp\" | \"outline-first\";\n  visualEffect: \"flat\" | \"subtle-gradient\" | \"glassmorphism\" | \"textured\";\n\n  mood: string;  // e.g. \"sophisticated and aspirational\", \"warm and approachable\"\n\n  // Optional \u2014 include when you have reference site analysis or strong design intent:\n  layoutPattern?:          string;  // e.g. \"full-bleed hero, 3-col card grid, alternating split sections\"\n  spacingRhythm?:          string;  // e.g. \"generous whitespace, section padding 80\u2013120px\"\n  typographyScale?:        string;  // e.g. \"oversized display ~72px, 17px body, tight heading tracking\"\n  componentNotes?:         string;  // e.g. \"rounded cards with drop shadow, pill category tags\"\n  distinctiveElements?:    string;  // e.g. \"full-bleed photography, sticky glassmorphic nav\"\n}\n```\n\n**Color guidance:**\n- All color fields must be valid hex strings (#rrggbb or #rgb)\n- Ensure sufficient contrast: textColor vs backgroundColor \u2265 4.5:1 (WCAG AA)\n- primaryColor and accentColor should be visually distinct\n- surfaceColor is usually a slightly lighter/darker variant of backgroundColor\n\n**Font guidance:**\n- Use Google Fonts names exactly as they appear on fonts.google.com\n- Pairing examples: \"Playfair Display\" + \"Inter\", \"Space Grotesk\" + \"DM Sans\",\n  \"Syne\" + \"Outfit\", \"Cormorant Garamond\" + \"Jost\"\n\n---\n\n## BusinessContext\n\n```typescript\n{\n  name:               string;    // REQUIRED. Business name. e.g. \"Adire Lagos\"\n  tagline:            string;    // One-line value prop. e.g. \"Authentic Nigerian fashion for the bold\"\n  targetAudience:     string;    // e.g. \"Nigerian professionals aged 25\u201340 who value craftsmanship\"\n  uniqueSellingPoints: string[]; // 2\u20134 bullets. e.g. [\"Handcrafted in Lagos\", \"Free delivery over \u20A615,000\"]\n}\n```\n\n---\n\n## CapabilitySlot (optional, more expressive than capabilityIds alone)\n\n```typescript\n{\n  purpose:      string;    // Human-readable job. e.g. \"Let customers book sessions\"\n  capability:   string;    // Selected capability ID. e.g. \"appointments\"\n  alternatives: string[];  // Valid swaps for this slot. Always include the selected capability.\n}\n```\n\n---\n\n## StorefrontConfig (optional)\n\n```typescript\n{\n  storeType: \"fashion\" | \"beauty\" | \"food\" | \"electronics\" | \"general\";\n  vendorOverrides: string[];  // Free-text additions. e.g. [\"Feature collections on homepage\"]\n}\n```\n\n---\n\n## DisplayModes (optional \u2014 only for stores with physical_products)\n\n```typescript\n{\n  productGrid:  boolean;  // Main product grid (useProducts)\n  collections:  boolean;  // Product collections (useProductCollections)\n  sections:     boolean;  // Category sections (useSections)\n  bundles:      boolean;  // Bundles & deals (useStorefrontBundles)\n}\n```\n\n---\n\n## Full example \u2014 Lagos fashion store\n\n```json\n{\n  \"businessType\": \"fashion\",\n  \"capabilityIds\": [\"physical_products\", \"content\", \"customer_accounts\"],\n  \"pages\": [\n    {\n      \"slug\": \"home\",\n      \"title\": \"Home\",\n      \"sections\": [\"hero\", \"featured-products\", \"collections\", \"brand-story\", \"testimonials\", \"newsletter\"]\n    },\n    {\n      \"slug\": \"shop\",\n      \"title\": \"Shop\",\n      \"sections\": [\"filter-bar\", \"product-grid\"]\n    },\n    {\n      \"slug\": \"about\",\n      \"title\": \"About\",\n      \"sections\": [\"brand-story\", \"values\", \"team\"]\n    },\n    {\n      \"slug\": \"contact\",\n      \"title\": \"Contact\",\n      \"sections\": [\"contact-form\", \"faq\"]\n    }\n  ],\n  \"visualDirection\": {\n    \"style\": \"Minimal luxury\",\n    \"primaryColor\": \"#1a1a2e\",\n    \"accentColor\": \"#c9a84c\",\n    \"backgroundColor\": \"#fafaf8\",\n    \"surfaceColor\": \"#ffffff\",\n    \"textColor\": \"#1a1a2e\",\n    \"headingFont\": \"Cormorant Garamond\",\n    \"bodyFont\": \"Inter\",\n    \"fontStyle\": \"editorial serif headings with clean sans body\",\n    \"cardStyle\": \"soft-shadow\",\n    \"buttonStyle\": \"sharp\",\n    \"visualEffect\": \"flat\",\n    \"mood\": \"sophisticated and aspirational\",\n    \"layoutPattern\": \"full-bleed hero, 2-col editorial split, 3-col product grid\",\n    \"spacingRhythm\": \"generous whitespace, 100\u2013120px section padding\",\n    \"typographyScale\": \"oversized display 72px, 16px body, tight tracking on headings\"\n  },\n  \"businessContext\": {\n    \"name\": \"Adire Lagos\",\n    \"tagline\": \"Authentic Nigerian fashion for the bold\",\n    \"targetAudience\": \"Nigerian professionals aged 25\u201340 who value craftsmanship\",\n    \"uniqueSellingPoints\": [\n      \"Handcrafted adire fabric from Abeokuta\",\n      \"Free delivery over \u20A615,000\",\n      \"30-day returns\"\n    ]\n  },\n  \"storefrontConfig\": {\n    \"storeType\": \"fashion\",\n    \"vendorOverrides\": []\n  }\n}\n```\n\n---\n\n## Submission\n\nOnce you have generated the direction JSON and the user has reviewed it:\n\n```\napply_design_direction(projectId, direction)\n```\n\nThe server validates the shape, filters any unrecognised capabilityIds, and stores\nthe direction on the project. Status advances to \"directing\".\n";