@onexapis/cli 1.1.45 → 1.1.47

package/templates/default/CLAUDE.md

@@ -1,1764 +1,126 @@
-# CLAUDE.md — OneX Theme Development Guide
+# CLAUDE.md — Routing rules for AI agents
 
-This file provides context to AI assistants (Claude, Cursor, Copilot) for developing OneX themes.
+This is an **OneX theme project**. It ships with the `onexthm` MCP server,
+which provides tools that **write section files for you**. You must use those
+tools as your first move on every theme task.
 
-## MANDATORY WORKFLOW — USE MCP TOOLS FIRST
-
-**You MUST use the `onexthm` MCP tools as your PRIMARY workflow for all theme development tasks. Do NOT write section files manually when a tool can generate them.**
-
-### Required tool usage
-
-| Task                               | MUST use                              | Why                                                                 |
-| ---------------------------------- | ------------------------------------- | ------------------------------------------------------------------- |
-| Create a new section               | `onexthm_create_section`              | Guarantees correct file structure, schema, data attributes, imports |
-| Convert HTML/React code to section | `onexthm_from_html`                   | Parses HTML elements and maps to OneX components automatically      |
-| Convert Figma design to section    | `onexthm_from_figma` + `figma` tools  | Extracts layout, colors, typography from design                     |
-| Generate schema from description   | `onexthm_generate_schema`             | Infers category, fields, blocks, data requirements                  |
-| Validate theme                     | `onexthm_validate`                    | Catches missing data attributes, wrong imports, structural errors   |
-| Look up hooks                      | `onexthm_list_hooks`                  | Shows all 44 hooks with params, returns, and examples               |
-| Look up components                 | Read `onexthm://components` resource  | Shows all component types, fields, slots                            |
-| Look up field types                | Read `onexthm://field-types` resource | Shows all 25 field types with options                               |
-| Look up rules                      | Read `onexthm://rules` resource       | Shows DOs/DON'Ts and patterns                                       |
-
-### Workflow for creating sections
-
-1. **From a description**: Use `onexthm_generate_schema` or `onexthm_create_section`
-2. **From HTML/React code**: Use `onexthm_from_html` — it parses headings, paragraphs, buttons, images, lists, etc. and maps them to OneX components
-3. **From Figma design**: Use `figma:get_metadata` → `onexthm_from_figma`
-4. **Always validate after**: Use `onexthm_validate`
-5. **Then customize**: Edit the generated files to refine layout and styling
-
-### When you have HTML/React code to convert
-
-If the user provides HTML, JSX, or a React component, ALWAYS use `onexthm_from_html` first:
-
-```
-onexthm_from_html({
-  htmlCode: "<the HTML/JSX code>",
-  sectionName: "section-name",
-  category: "hero"  // optional
-})
-```
-
-This automatically:
-
-- Maps `<h1>`-`<h6>` → heading components
-- Maps `<p>`, `<span>` → paragraph components
-- Maps `<button>`, `<a class="btn">` → button components
-- Maps `<img>` → image components
-- Maps `<svg>`, icons → icon components
-- Maps `<ul>/<ol>` → list components
-- Maps `<hr>` → divider components
-- Detects repeating patterns → block definitions
-- Extracts Tailwind classes → layout settings
-- Generates schema + component + index files
+For deep reference (component types, hooks, animation tokens, color system,
+dark mode, locale, full architecture), read **`THEME_REFERENCE.md`** in this
+directory or call the relevant `onexthm_*` tool.
 
 ---
 
-## CRITICAL RULES — READ FIRST
-
-**IMPORTANT: When creating new sections, blocks, or modifying theme code, you MUST follow these rules. Violations will cause the editor and storefront to break.**
-
-### Creating New Sections
-
-Every section MUST use `ComponentRenderer` and `BlockRenderer` from `@onexapis/core` to render content. Sections define LAYOUT only — all content (text, images, buttons) is rendered through Blocks and Components.
-
-Use `onexthm_create_section` MCP tool or `onexthm create:section` CLI to scaffold. If writing manually, every section MUST have:
-
-1. **`"use client"` directive** at the top
-2. **Import from `@onexapis/core/renderers`** — use `ComponentRenderer` and `BlockRenderer`
-3. **Import from `@onexapis/core/utils`** — use `getSectionValues`, `toComponentInstance`, `filterEnabledComponents`
-4. **`data-section-id={section.id}`** attribute on the root element
-5. **`data-section-type={section.type}`** attribute on the root element
-6. **`data-block-id={block.id}`** and **`data-block-type={block.type}`** on every block wrapper
-7. **Handle `isEditing` prop** — show placeholders when empty, disable links
-8. **A matching `.schema.ts` file** with type, name, category, settings, defaults
-9. **An `index.ts`** that re-exports the component and schema
-10. **Registration in `sections-registry.ts`**
-
-### NEVER do these
-
-- **NEVER render text/buttons/icons directly** — always use `ComponentRenderer` from core
-- **NEVER use `<h1>`, `<p>`, `<button>` for content** — use `ComponentRenderer` which renders heading, paragraph, button components with proper editor integration
-- **NEVER hardcode content** — content comes from `section.components` and `section.blocks`, rendered via `ComponentRenderer`/`BlockRenderer`
-- **NEVER skip data attributes** — without `data-section-id`, `data-block-id`, the editor cannot select or edit sections
-- **NEVER use `useEffect` for data fetching** — use `useProducts()`, `useBlogs()` hooks
-- **NEVER import from `@onexapis/core/internal`**
-
-### Section Template (MUST follow exactly)
-
-```tsx
-"use client";
-
-import type { SectionComponentProps } from "@onexapis/core/types";
-import coreRenderers from "@onexapis/core/renderers";
-import coreUtils from "@onexapis/core/utils";
-
-const { ComponentRenderer, BlockRenderer } = coreRenderers;
-const { toComponentInstance, getSectionValues, filterEnabledComponents } =
-  coreUtils;
+## Before you start
 
-export function MySectionDefault({
-  section,
-  schema,
-  isEditing,
-}: SectionComponentProps) {
-  const { settings } = getSectionValues(section, schema);
-  const components = filterEnabledComponents(section.components || []);
-  const blocks = (section.blocks || []).filter((b) => b.enabled !== false);
+At the start of every session, confirm the `onexthm_*` tools are available
+in your tool list. If they are not, STOP and tell the user:
 
-  return (
-    <section
-      data-section-id={section.id}
-      data-section-type={section.type}
-      data-section-template="default"
-      className="py-16"
-      style={{ backgroundColor: String(settings.backgroundColor || "#FFFFFF") }}
-    >
-      <div className="container mx-auto px-4 max-w-6xl">
-        {/* MUST use ComponentRenderer for section-level components */}
-        {components.map((comp) => (
-          <ComponentRenderer
-            key={comp.id}
-            instance={toComponentInstance(comp)}
-            sectionId={section.id}
-            isEditing={isEditing}
-          />
-        ))}
+> "The onexthm MCP server is not loaded. Restart your AI client after
+> verifying `.mcp.json` registers `@onexapis/theme-mcp`."
 
-        {/* MUST use BlockRenderer for blocks */}
-        {blocks.map((block) => (
-          <div
-            key={block.id}
-            data-section-id={section.id}
-            data-block-id={block.id}
-            data-block-type={block.type}
-          >
-            <BlockRenderer
-              block={block}
-              sectionId={section.id}
-              isEditing={isEditing}
-            />
-          </div>
-        ))}
-
-        {/* MUST show empty state in editor */}
-        {blocks.length === 0 && isEditing && (
-          <div className="text-center py-12 border-2 border-dashed border-gray-300 rounded-lg">
-            <p className="text-gray-500">Add blocks to populate this section</p>
-          </div>
-        )}
-      </div>
-    </section>
-  );
-}
-
-export default MySectionDefault;
-```
-
-### How content rendering works
-
-- **Sections** define LAYOUT (grid, padding, background color)
-- **Components** (from core) render CONTENT (text, images, buttons)
-- A section component NEVER renders `<h1>Hello</h1>` directly — instead:
-
-  ```tsx
-  // WRONG ❌
-  <h1>{settings.title}</h1>;
-
-  // CORRECT ✅
-  const titleComp = components.find((c) => c.slot === "section-title");
-  {
-    titleComp && (
-      <ComponentRenderer
-        instance={toComponentInstance(titleComp)}
-        sectionId={section.id}
-        isEditing={isEditing}
-      />
-    );
-  }
-  ```
-
-- The editor manages component content — users edit text/images through the sidebar, not through section settings
+Do not silently fall back to writing files by hand.
 
 ---
 
-## System Overview
-
-A OneX theme is a collection of **sections** compiled into a browser-ready JS bundle. Themes are:
-
-1. Developed locally with `onexthm dev`
-2. Compiled with `onexthm build` (esbuild → ES module)
-3. Uploaded to S3 with `onexthm upload` (bundle.zip)
-4. Loaded by the storefront (customer-facing site) and editor (visual editor)
-
-Both storefront and editor render the same bundle — sections must look identical in both.
-
-## Architecture
-
-```
-Theme
-├── Sections      Top-level page blocks (hero, features, pricing, footer)
-│   ├── Blocks    Nested containers inside sections (feature-item, pricing-tier)
-│   └── Components  Atomic UI rendered by @onexapis/core (heading, paragraph, button, icon, badge, divider, image)
-└── Pages         Page configs that list which sections to show
-```
-
-**Key principle**: Sections define layout & structure. Components (from core) handle rendering text, images, buttons with inline styles. The section component orchestrates how core components are arranged.
-
-## File Structure
-
-```
-my-theme/
-├── theme.config.ts          # Colors, typography, spacing, breakpoints
-├── bundle-entry.ts          # Build entry point (DO NOT import React here)
-├── sections-registry.ts     # Lazy-loaded section imports
-├── theme.layout.ts          # Header/footer section configuration
-├── package.json             # @onexapis/core as dependency
-├── tsconfig.json            # ES2020 target, react-jsx
-├── esbuild.config.js        # Bundle → dist/bundle.mjs
-├── sections/
-│   └── hero/
-│       ├── hero-default.tsx     # React component (the visual)
-│       ├── hero.schema.ts       # Schema (settings, fields, defaults)
-│       └── index.ts             # Re-exports component + schema
-├── pages/
-│   └── home.ts              # Page config with section instances
-└── CLAUDE.md                # This file
-```
-
-## Section Component Pattern
-
-Every section component receives `SectionComponentProps` and uses core renderers:
-
-```tsx
-"use client";
-
-import type { SectionComponentProps } from "@onexapis/core/types";
-import coreRenderers from "@onexapis/core/renderers";
-import coreUtils from "@onexapis/core/utils";
-
-const { ComponentRenderer, BlockRenderer } = coreRenderers;
-const { toComponentInstance, getSectionValues, filterEnabledComponents } =
-  coreUtils;
-
-export function MySection({
-  section,
-  schema,
-  isEditing,
-  data,
-}: SectionComponentProps) {
-  const { settings } = getSectionValues(section, schema);
-  const { title, backgroundColor } = settings;
-
-  // Section-level components (title, subtitle, etc.)
-  const components = filterEnabledComponents(section.components || []);
-  const titleComp = components.find((c) => c.slot === "section-title");
-
-  // Nested blocks
-  const blocks = (section.blocks || []).filter((b) => b.enabled !== false);
-
-  return (
-    <section
-      className="py-16"
-      style={{ backgroundColor: String(backgroundColor || "#FFFFFF") }}
-      data-section-id={section.id}
-      data-section-type={section.type}
-    >
-      <div className="container mx-auto px-4 max-w-6xl">
-        {/* Render a core component (heading, paragraph, etc.) */}
-        {titleComp && (
-          <ComponentRenderer
-            instance={toComponentInstance(titleComp)}
-            sectionId={section.id}
-            isEditing={isEditing}
-          />
-        )}
-
-        {/* Render blocks (nested containers with their own components) */}
-        {blocks.map((block) => (
-          <div
-            key={block.id}
-            data-section-id={section.id}
-            data-block-id={block.id}
-            data-block-type={block.type}
-          >
-            <BlockRenderer
-              block={block}
-              sectionId={section.id}
-              isEditing={isEditing}
-            />
-          </div>
-        ))}
-
-        {/* Editor empty state */}
-        {blocks.length === 0 && isEditing && (
-          <div className="text-center py-12 border-2 border-dashed border-gray-300 rounded-lg">
-            <p className="text-gray-500">Add blocks to populate this section</p>
-          </div>
-        )}
-      </div>
-    </section>
-  );
-}
-
-export default MySection;
-```
-
-## Schema Definition Pattern
-
-Every section needs a schema that defines its settings, templates, and defaults:
-
-```tsx
-import type { SectionSchema } from "@onexapis/core/types";
-
-export const mySchema: SectionSchema = {
-  type: "my-section",
-  name: "My Section",
-  description: "A custom section",
-  icon: "layout",
-  category: "content", // header | hero | content | features | testimonials | cta | gallery | pricing | faq | team | contact | footer | products | blog | newsletter
-  templates: [
-    { id: "default", name: "Default", isDefault: true },
-    { id: "minimal", name: "Minimal" },
-  ],
-  settings: [
-    // Text fields
-    { id: "title", type: "text", label: "Title", default: "Hello World" },
-    { id: "subtitle", type: "textarea", label: "Subtitle" },
-
-    // Numbers
-    { id: "columns", type: "number", label: "Columns", default: 3 },
-    { id: "limit", type: "range", label: "Items", default: 8, min: 1, max: 20 },
-
-    // Selection
-    {
-      id: "layout",
-      type: "select",
-      label: "Layout",
-      default: "grid",
-      options: [
-        { value: "grid", label: "Grid" },
-        { value: "list", label: "List" },
-      ],
-    },
-
-    // Boolean
-    { id: "showTitle", type: "checkbox", label: "Show Title", default: true },
-
-    // Colors — use hex directly (standard approach)
-    {
-      id: "backgroundColor",
-      type: "color",
-      label: "Background",
-      default: "#FFFFFF",
-    },
-    {
-      id: "textColor",
-      type: "color_token",
-      label: "Text Color",
-      default: "#1F2937",
-    },
-
-    // Images
-    { id: "image", type: "image", label: "Background Image" },
-  ],
-  defaults: {
-    title: "Hello World",
-    columns: 3,
-    backgroundColor: "#FFFFFF",
-  },
-  // Declare if this section needs commerce data for SSR
-  dataRequirements: {
-    products: false,
-    blogs: false,
-    settings: false,
-  },
-};
-```
-
-## Available Field Types
-
-| Type                     | Description                                       | Example Use                   |
-| ------------------------ | ------------------------------------------------- | ----------------------------- |
-| `text`                   | Single-line text input                            | Title, label, button text     |
-| `textarea`               | Multi-line text                                   | Description, bio              |
-| `number`                 | Numeric input                                     | Columns, count, limit         |
-| `range`                  | Slider with min/max                               | Opacity, spacing, items count |
-| `checkbox` / `boolean`   | Toggle switch                                     | Show/hide elements            |
-| `select`                 | Dropdown selector                                 | Layout variant, size          |
-| `radio`                  | Radio button group                                | Alignment, position           |
-| `color`                  | Color picker (hex + system tokens)                | Any color                     |
-| `color_token`            | Color picker (tokens: Primary/Secondary + Custom) | Text color, icon color        |
-| `color_background`       | Solid color or gradient                           | Section background            |
-| `image` / `image_picker` | Image upload/selection                            | Hero image, avatar            |
-| `video_url`              | Video embed URL                                   | Background video              |
-| `font` / `font_picker`   | Font family selector                              | Section font override         |
-| `text_alignment`         | Left / center / right                             | Text alignment                |
-| `richtext`               | Rich text editor                                  | Content blocks, articles      |
-| `inline_richtext`        | Inline rich text                                  | Short formatted text          |
-| `html`                   | Raw HTML/code editor                              | Custom embeds, scripts        |
-| `url`                    | URL input                                         | Link href                     |
-| `array` / `repeater`     | List of repeating items                           | Feature list, social links    |
-
-## Available Hooks (44 hooks)
-
-All hooks import from `@onexapis/core/hooks`. Use `onexthm_list_hooks` MCP tool for full API details.
-
-```tsx
-import {
-  useProducts,
-  useCart,
-  useCheckout,
-  useDesignSystem,
-} from "@onexapis/core/hooks";
-```
-
-### Quick Reference
-
-| Category          | Hooks                                                                                                                                                                                              |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Commerce** (11) | `useProducts`, `useProductBySlug`, `useProductById`, `useProductCategories`, `useBlogs`, `useBlogBySlug`, `useBlogById`, `useBlogCategories`, `useSettings`, `useProductListing`, `useBlogListing` |
-| **State** (3)     | `useCart`, `useAuth`, `useOrders`                                                                                                                                                                  |
-| **Checkout** (8)  | `useCheckout`, `usePayment`, `useOrderLookup`, `useOrderStatus`, `useOrderSuccess`, `useOrderSummary`, `useFinance`, `saveBuyNowItem`                                                              |
-| **Products** (3)  | `useSearchProducts`, `useAddToCart`, `useProductDetail`                                                                                                                                            |
-| **Theme** (9)     | `useDesignSystem`, `usePageBackground`, `useCommerceData`, `useThemeMode`, `useLocale`, `useViewport`, `usePageData`, `useWebsiteSettings`, `useMotion`                                            |
-| **Utilities** (7) | `useDebounce`, `useMediaQuery`, `useIsMobile`, `useIsTablet`, `useIsDesktop`, `useContactForm`, `useCopyToClipboard`, `useFormatPrice`, `formatVndPrice`                                           |
-| **Animation** (1) | `useFlyToCart`                                                                                                                                                                                     |
-| **Server** (4)    | `fetchProducts`, `fetchBlogs`, `fetchSettings`, `prefetchSectionData`                                                                                                                              |
-
-### Most Used Patterns
-
-```tsx
-// Fetch products
-const { data, isLoading } = useProducts({ limit: 8 });
-const products = data?.data ?? [];
-
-// Cart
-const { items, addItem, itemCount, subtotal } = useCart();
-
-// Auth
-const { user, isAuthenticated, login, logout } = useAuth();
-
-// Checkout (full form)
-const checkout = useCheckout({ paymentRedirectUrl: "/payment" });
-// checkout.fullName, checkout.handleCheckout, checkout.errors
-
-// Product detail with buy now
-const detail = useProductDetail({ slug: routeParams.slug });
-// detail.product, detail.handleAddToCart, detail.handleBuyNow
-
-// Search with debounce
-const search = useSearchProducts({ debounceMs: 300 });
-// search.query, search.setQuery, search.results
-
-// Responsive
-const isMobile = useIsMobile();
-const isDesktop = useIsDesktop();
-
-// Price formatting
-const { formatPrice } = useFormatPrice();
-formatPrice(1250000); // "1.250.000đ"
-```
-
-### Orders & Payment Hooks
-
-These hooks cover the full order lifecycle: creating orders, looking up orders, processing payments, and displaying order history.
-
-#### `useOrders` — Order state management (Zustand)
-
-```tsx
-import { useOrders } from "@onexapis/core/hooks";
-
-const {
-  orders, // Order[] — list of orders
-  currentOrder, // Order | null — single order detail
-  isLoading,
-  error,
-  total,
-  totalPages,
-  currentPage,
-
-  // Actions
-  createOrder, // (data: CreateOrderData) => Promise<Order>
-  createPrivateOrder, // (data: CreateOrderData) => Promise<Order> — requires auth
-  fetchOrders, // (params?) => Promise<void> — public order list
-  fetchOrderHistory, // (params?) => Promise<void> — authenticated user's orders
-  fetchOrderById, // (orderId: string) => Promise<void>
-  fetchOrderByNumber, // (orderNumber: string) => Promise<void>
-  updateOrderStatus, // (orderId, status) => Promise<void>
-  cancelOrder, // (orderId) => Promise<void>
-  payOrder, // (orderId, paymentData?) => Promise<Order> — returns updated order
-  clearError,
-  clearCurrentOrder,
-} = useOrders();
-```
-
-**`payOrder` returns the updated `Order`** — always check `order.status` and `order.payment_status` before navigating to success. Do NOT blindly redirect after calling `payOrder`.
-
-#### `useOrderLookup` — Search/track order by number or ID
-
-```tsx
-import { useOrderLookup } from "@onexapis/core/hooks";
-
-// Basic — manual search via input
-const lookup = useOrderLookup();
-
-// With auto-fetch from URL route param (for dynamic pages like /order-lookup/[orderId])
-const routeParams = (data?.routeParams || {}) as Record<string, string>;
-const lookup = useOrderLookup({
-  initialOrderId: routeParams.orderId, // auto-fetches on mount
-});
-
-// lookup.orderNumber        — input value (string)
-// lookup.setOrderNumber     — update input
-// lookup.handleTrackOrder   — search (auto-detects UUID vs order number)
-// lookup.handleClear        — reset search
-// lookup.order              — Order | null (result)
-// lookup.isSearching        — boolean
-// lookup.errorMessage       — string | null
-// lookup.getStatusLabel     — (status: string) => Vietnamese label
-// lookup.formatCurrency     — (amount: number) => "1.250.000đ"
-```
-
-**Dynamic page setup** for `/order-lookup/[orderId]`:
-
-```typescript
-// pages/order-lookup.ts
-export const orderLookupPageConfig = {
-  handle: "order-lookup",
-  path: "/order-lookup/[orderId]",
-  isDynamic: true,
-  dynamicSegments: ["orderId"],
-  type: "custom",
-  // ...sections
-};
-```
-
-#### `usePayment` — QR code payment with bank transfer
-
-```tsx
-import { usePayment } from "@onexapis/core/hooks";
-
-const payment = usePayment({
-  successRedirectUrl: "/order-success", // default
-  checkoutRedirectUrl: "/checkout", // default — redirect if no order info
-  isEditing: false,
-});
-
-// payment.orderId, payment.orderNumber, payment.total
-// payment.qrCodeImage       — data URI for QR code
-// payment.qrNote            — transfer note (e.g. "DH4X7K2M")
-// payment.bankTransferData  — { accountNumber, accountName, bankName }
-// payment.isLoading, payment.isProcessing, payment.error
-// payment.handleConfirmPayment  — calls payOrder API, checks response, then redirects
-// payment.handleCancel          — clears order info, redirects to checkout
-```
-
-**`handleConfirmPayment` validates the API response:**
-
-- Checks `order.status` — blocks redirect if `failed`, `cancelled`, or `refunded`
-- Checks `order.payment_status` — blocks redirect if `failed`
-- Only navigates to success page when payment is valid
-- Shows error message from API on failure
-
-#### `useOrderSuccess` — Post-purchase success page
-
-```tsx
-import { useOrderSuccess } from "@onexapis/core/hooks";
-
-const success = useOrderSuccess();
-// success.orderId, success.orderNumber, success.displayOrderNumber
-// success.trackOrderUrl     — link to order lookup page
-// success.hasOrder          — boolean (false if no order in URL params)
-```
-
-#### `useOrderSummary` — Calculate order totals
-
-```tsx
-import { useOrderSummary, calculateOrderTotal } from "@onexapis/core/hooks";
-
-const summary = useOrderSummary({
-  vatRate: 0.1,
-  shippingFee: 30000,
-  discount: 0,
-  freeShippingThreshold: 500000,
-});
-// summary.subtotal, summary.discount, summary.shipping, summary.vat, summary.total
-// summary.formatPrice(amount)
-
-// Standalone helper (no hook needed)
-const total = calculateOrderTotal(items, { vatRate: 0.1, shippingFee: 30000 });
-```
-
-#### `useOrderStatus` — Status label translation
-
-```tsx
-import { useOrderStatus, getOrderStatusLabel } from "@onexapis/core/hooks";
-
-const { getLabel, getPaymentLabel } = useOrderStatus();
-getLabel("shipping"); // "Đang giao hàng"
-getLabel("completed"); // "Hoàn thành"
-getPaymentLabel("paid"); // "Đã thanh toán"
-
-// Or use the standalone function
-getOrderStatusLabel("pending"); // "Chờ xử lý"
-```
-
-#### `useOrderListPage` — Order history page
-
-```tsx
-import { useOrderListPage } from "@onexapis/core/hooks";
-
-const orderList = useOrderListPage({ autoFetch: true, collapsedItemCount: 2 });
-// orderList.orders          — Order[]
-// orderList.isLoading, orderList.error
-// orderList.toggleOrder     — expand/collapse order items
-// orderList.refresh         — re-fetch orders
-// orderList.getDisplayItems — get visible items (respects collapsed state)
-// orderList.hasMoreItems    — check if order has hidden items
-// orderList.formatCurrency, orderList.formatDate
-```
-
-#### Order Type Reference
-
-```typescript
-interface Order {
-  id: string;
-  order_number: string;
-  status: string; // pending | confirmed | processing | packing | shipping | completed | cancelled | failed | refunded
-  payment_status?: string; // paid | unpaid | failed
-  payment_method?: string;
-  total: number;
-  sub_total?: number;
-  tax?: number;
-  shipping_fee?: number;
-  discount?: number;
-  order_line_items?: OrderLineItem[];
-  shipping_address?: OrderAddress;
-  note?: string;
-  created_at: string;
-  updated_at?: string;
-}
-
-interface OrderLineItem {
-  name: string;
-  unit_price: number;
-  quantity: number;
-  product_id: string;
-  variant_name?: string;
-  image_url?: string;
-  sku?: string;
-  location?: { id: string; name: string };
-}
-```
-
-## Color System
-
-Colors in OneX themes work with **two approaches** (both are valid):
-
-### Approach 1: Direct hex colors (standard — used by simple, cool-store themes)
-
-```tsx
-// In schema
-{ id: "backgroundColor", type: "color", label: "Background", default: "#3B82F6" }
+## Routing rules — what tool to call when
 
-// In component
-<section style={{ backgroundColor: String(backgroundColor || "#FFFFFF") }}>
-```
-
-Components store and render hex colors directly (`#3B82F6`). This is simple and works everywhere.
-
-### Approach 2: Design system tokens (optional — for theme-aware colors)
-
-```tsx
-// In schema
-{ id: "textColor", type: "color_token", label: "Text Color", default: "token:primary" }
-
-// Resolves to CSS variable: var(--theme-color-primary)
-// Changes automatically when user updates Primary Color in theme settings
-```
-
-Token values: `token:primary`, `token:secondary`, `token:accent`, `token:background`, `token:foreground`, `token:muted`
-Custom values: `custom:#FF5733` or direct `#FF5733`
-
-## Data Attributes (Required for Editor)
-
-Sections and blocks MUST include `data-` attributes so the editor's visual inspector can identify and select them:
-
-```tsx
-// Section wrapper
-<section
-  data-section-id={section.id}           // REQUIRED
-  data-section-type={section.type}       // REQUIRED
-  data-section-template="default"        // Optional
-  data-section-name="My Section"         // Optional
->
-
-// Block wrapper
-<div
-  data-section-id={section.id}           // REQUIRED — parent section
-  data-block-id={block.id}              // REQUIRED
-  data-block-type={block.type}          // REQUIRED
->
-```
+| When the user says…                                                                                                                                                    | Call this tool                                                                      | Notes                                                                                                                                    |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| "add / create / scaffold a section" (hero, header, footer, pricing, FAQ, testimonials, gallery, CTA, features, contact, newsletter, product grid, blog list, anything) | **`onexthm_create_section`**                                                        | Pass `projectDir` (this directory). Writes 3 files + patches `sections-registry.ts` in one call.                                         |
+| "add / create a page" (home, about, product detail, blog detail, checkout, order lookup, custom)                                                                       | **`onexthm_create_page`**                                                           | Pass `projectDir`. Writes page config + patches `bundle-entry.ts`.                                                                       |
+| "convert / port / turn this HTML into a section", user pastes markup                                                                                                   | **`onexthm_from_html`**                                                             | Pass `projectDir` + the source markup.                                                                                                   |
+| "convert Figma to a section", user references a Figma design                                                                                                           | **`figma:get_metadata`** + **`figma:get_variable_defs`** → **`onexthm_from_figma`** | Call the figma tools first, then pass output to `onexthm_from_figma`.                                                                    |
+| "validate / lint / check my theme"                                                                                                                                     | **`onexthm_validate`**                                                              | Run automatically after every write.                                                                                                     |
+| "fix / auto-fix / repair errors"                                                                                                                                       | **`onexthm_fix`**                                                                   | Auto-fixes: missing "use client", unregistered sections, schema mismatches, invalid page refs. Call `onexthm_validate` after to confirm. |
+| "build / compile / bundle my theme"                                                                                                                                    | **`onexthm_build`**                                                                 | Returns structured errors with file:line. Run after code changes.                                                                        |
+| "what hooks can I use?"                                                                                                                                                | **`onexthm_list_hooks`**                                                            | Filter by category. 44 hooks across 8 categories.                                                                                        |
+| Anything else (architecture, animation, dark mode, locale, blocks, components)                                                                                         | Read `THEME_REFERENCE.md` first                                                     | Do not improvise.                                                                                                                        |
 
-Without these, the editor cannot select sections/blocks for editing.
+`projectDir` is **the directory containing `theme.config.ts` and `sections-registry.ts`**. In a fresh session opened in this folder, that's the current working directory.
 
-## Built-in Components
-
-34 built-in components from `@onexapis/core` that render inside sections via `ComponentRenderer`:
-
-| Component | Description | Key Settings |
-| --------- | ----------- | ------------ |
-
-**Text:** `heading` (H1-H6), `paragraph`, `quote`
-**Interactive:** `button` (default/outline/ghost/link), `link`, `input`, `textarea`, `checkbox`, `select`
-**Media:** `image`, `video` (youtube/vimeo/hosted), `icon` (Lucide icons), `gallery`
-**Layout:** `divider`, `spacer`, `container`, `grid`, `columns`, `card`
-**Display:** `badge`, `alert`, `progress`, `rating`, `timer`, `list`, `table`, `accordion`, `tabs`, `code`, `map`
-**Special:** `product-card`, `blog-card`, `social-links`, `hotline-contacts`, `company-info`
-**Decorative:** `torn-separator`
-
-Use `onexthm://components` MCP resource for full details (content/style fields, slots, examples).
-
-Components are rendered via `ComponentRenderer` — you don't import them directly.
-
-## Component Slots
-
-Components use `slot` to identify their role:
-
-```tsx
-const titleComp = components.find((c) => c.slot === "section-title");
-const ctaButton = components.find((c) => c.slot === "cta-button");
-```
-
-Common slots: `section-title`, `section-subtitle`, `description`, `cta-button`, `secondary-cta`, `badge`, `icon`, `image`, `block-title`, `block-description`, `feature-icon`
-
-## Block System
-
-Blocks are nested containers inside sections. They hold components and can nest other blocks.
-Use `onexthm://blocks` MCP resource for full block patterns (features, testimonials, pricing, FAQ, team).
-
-```tsx
-// Section → Blocks → Components
-<section>                               // Section: "features"
-  <div>                                 // Block: "features-container" (layout)
-    <div>                               // Block: "feature-item" (repeating card)
-      <ComponentRenderer ... />          // Component: icon
-      <ComponentRenderer ... />          // Component: heading
-      <ComponentRenderer ... />          // Component: paragraph
-    </div>
-    <div>                               // Block: "feature-item" (another card)
-      ...
-    </div>
-  </div>
-</section>
-```
-
-Use `BlockRenderer` to render blocks — it handles recursive nesting automatically.
-
-### Defining Blocks in Schema
-
-```tsx
-// In your-section.schema.ts
-export const mySchema: SectionSchema = {
-  type: "features",
-  // ...settings, defaults...
-  blocks: [
-    {
-      type: "feature-item",
-      name: "Feature Item",
-      limit: 6, // Max 6 blocks of this type
-      settings: [
-        {
-          id: "backgroundColor",
-          type: "color",
-          label: "Background",
-          default: "#FFFFFF",
-        },
-      ],
-      components: [
-        { type: "icon", slot: "feature-icon", label: "Icon" },
-        { type: "heading", slot: "block-title", label: "Title" },
-        { type: "paragraph", slot: "block-description", label: "Description" },
-      ],
-    },
-  ],
-};
-```
-
-### Rendering Blocks
-
-```tsx
-const blocks = (section.blocks || []).filter((b) => b.enabled !== false);
-
-{
-  blocks.map((block) => (
-    <div
-      key={block.id}
-      data-section-id={section.id} // REQUIRED
-      data-block-id={block.id} // REQUIRED
-      data-block-type={block.type} // REQUIRED
-      className="p-6 rounded-xl border"
-    >
-      <BlockRenderer
-        block={block}
-        sectionId={section.id}
-        isEditing={isEditing}
-      />
-    </div>
-  ));
-}
-
-{
-  blocks.length === 0 && isEditing && (
-    <div className="text-center py-12 border-2 border-dashed border-gray-300 rounded-lg">
-      <p className="text-gray-500">Add blocks to populate this section</p>
-    </div>
-  );
-}
-```
-
-## Animation System
-
-Sections, blocks, and components support animations via framer-motion:
-
-### Animation Types (22)
-
-`fadeIn`, `fadeInUp`, `fadeInDown`, `fadeInLeft`, `fadeInRight`, `slideInUp`, `slideInDown`, `slideInLeft`, `slideInRight`, `scaleIn`, `scaleInUp`, `rotate`, `rotateIn`, `blur`, `bounce`, `pulse`, `shake`, `flip`, `typing`, `counter`, `parallax`, `none`
-
-### Animation Triggers
-
-- `onLoad` — animate immediately on mount
-- `onScroll` — animate when section enters viewport (default, recommended)
-- `onHover` — animate on hover
-- `onClick` — animate on click
-
-### Adding Animation to Schema
-
-```tsx
-// In schema settings
-{ id: "animationType", type: "select", label: "Animation",
-  default: "none",
-  options: [
-    { value: "none", label: "None" },
-    { value: "fadeInUp", label: "Fade In Up" },
-    { value: "scaleIn", label: "Scale In" },
-  ]
-},
-{ id: "animationTrigger", type: "select", label: "Trigger",
-  default: "onScroll",
-  options: [
-    { value: "onScroll", label: "On Scroll" },
-    { value: "onLoad", label: "On Load" },
-  ]
-},
-```
-
-Animations are applied automatically by `SectionRenderer` and `BlockRenderer` via `AnimationWrapper`.
-
-### Motion Tokens
-
-Themes can customize animation feel via `MotionTokens`:
-
-- `duration`: instant(0.1s), quick(0.2s), moderate(0.4s), deliberate(0.6s), slow(0.8s)
-- `easing`: standard, entrance, exit, expressive (cubic-bezier)
-- `intensity`: 0 (no motion/accessibility) to 1 (full motion)
-- `staggerDelay`: delay between child animations (default 0.1s)
-
-Access via `useMotion()` hook from `@onexapis/core/hooks`.
-
-## Data Requirements (SSR)
-
-Sections can declare what data they need for server-side rendering:
-
-```tsx
-// In schema
-dataRequirements: {
-  products: true,   // Section needs product data
-  blogs: false,     // No blog data needed
-  settings: true,   // Needs website settings
-}
-```
-
-When `dataRequirements.products = true`:
-
-- Server pre-fetches products before rendering
-- Data is passed via `SectionComponentProps.data`
-- Use `useCommerceData(data)` to access it
-- Falls back to client-side `useProducts()` if not pre-fetched
-
-## Dynamic Pages (Product Detail, Blog Detail)
-
-Dynamic pages use URL parameters like `/products/[slug]` to render detail views.
-
-### Define a dynamic page in `pages/`
-
-```typescript
-// pages/product-detail.ts
-import type { PageConfig } from "@onexapis/core/types";
-
-export const productDetailPageConfig: Omit<
-  PageConfig,
-  "id" | "createdAt" | "updatedAt"
-> = {
-  title: "Product Detail",
-  handle: "product-detail",
-  path: "/products/[slug]", // Dynamic segment in brackets
-  isDynamic: true, // Flag as dynamic
-  dynamicSegments: ["slug"], // Parameter names
-  type: "product",
-  renderMode: "sections",
-  themeId: "my-theme",
-  editable: true,
-  published: true,
-  sections: [
-    {
-      id: "product-detail-1",
-      type: "my-product-detail",
-      template: "default",
-      order: 0,
-      enabled: true,
-      settings: {},
-      components: [],
-      blocks: [],
-    },
-  ],
-};
-export default productDetailPageConfig;
-```
+---
 
-Export in `bundle-entry.ts`:
+## Forbidden behaviors
 
-```typescript
-export { default as productDetailPageConfig } from "./pages/product-detail";
-```
+These break the editor and storefront. Never do them.
 
-### Access route params in sections
+1. **Never hand-write a section's `.tsx`, `.schema.ts`, or `index.ts`** when adding a new section. Call `onexthm_create_section`. The tool already produces correct file structure, schema shape, data attributes, imports, and registry entry. Hand-writing one-offs causes drift.
+2. **Never edit `sections-registry.ts` by hand** to add a new section. The tools patch it for you.
+3. **Never use raw `<h1>`, `<p>`, `<button>`** for _content_ inside a section. Content goes through `ComponentRenderer` from `@onexapis/core/renderers`. Section components define **layout only**.
+4. **Never skip `data-section-id`, `data-section-type`, `data-block-id`, `data-block-type`** on wrapper elements. Without them, the visual editor cannot select or edit the section.
+5. **Never use `useEffect` for data fetching, never hardcode API URLs, never import from `@onexapis/core/internal`**. Use the documented hooks (`useProducts`, `useBlogs`, `useCart`, `useAuth`, `useCheckout`).
 
-Sections receive `data.routeParams` with the extracted URL parameters:
+---
 
-```tsx
-export function ProductDetail({
-  section,
-  schema,
-  isEditing,
-  data,
-}: SectionComponentProps) {
-  const routeParams = (data?.routeParams || {}) as Record<string, string>;
-  const slug = routeParams.slug || ""; // "blue-shirt" from /products/blue-shirt
+## Calling the tools — minimal examples
 
-  const { data: product, isLoading } = useProductBySlug(slug, !!slug);
-  // ...
-}
-```
+```jsonc
+// Create a new section
+onexthm_create_section({
+  projectDir: "<absolute path to this directory>",
+  name: "pricing-table",
+  description: "Three-tier pricing table with featured tier"
+})
 
-### Locale-aware paths
+// Convert pasted HTML/JSX to a section
+onexthm_from_html({
+  projectDir: "<absolute path to this directory>",
+  sectionName: "hero-banner",
+  htmlCode: "<div>...the user's markup...</div>"
+})
 
-Use `localizedPaths` to define different URL slugs per locale:
+// Convert a Figma frame (after calling figma:get_metadata first)
+onexthm_from_figma({
+  projectDir: "<absolute path to this directory>",
+  sectionName: "feature-grid",
+  figmaMetadata: "<output of figma:get_metadata>",
+  figmaVariables: "<output of figma:get_variable_defs>"
+})
 
-```typescript
-export const productDetailPageConfig = {
+// Create a page
+onexthm_create_page({
+  projectDir: "<absolute path to this directory>",
   handle: "product-detail",
-  path: "/products/[slug]", // Default/fallback
+  path: "/products/[slug]",
   isDynamic: true,
-  dynamicSegments: ["slug"],
-  localizedPaths: {
-    // Locale-specific paths (typed by Locale enum)
-    vi: "/san-pham/[slug]", // /vi/san-pham/blue-shirt
-    en: "/products/[slug]", // /en/products/blue-shirt
-  },
-  type: "product",
-  // ...
-};
-```
-
-The `Locale` type (`"vi" | "en"`) is from `@onexapis/core/types` — gives autocomplete.
-
-Sections also receive `data.locale` to know the current locale:
-
-```tsx
-const locale = data?.locale as string; // "vi" or "en"
-```
-
-### Key conventions
-
-- `path` uses bracket syntax: `/products/[slug]`, `/blog/[slug]`
-- `localizedPaths` maps `Locale` → path for locale-specific URLs
-- `dynamicSegments` lists parameter names extracted from the path
-- `type: "product"` or `"blog"` indicates what kind of detail page
-- Sections access params via `data.routeParams.slug` (or whatever parameter name)
-- Sections access locale via `data.locale` or `useLocale()` hook
-- Use `useProductBySlug()` / `useBlogBySlug()` hooks to fetch detail data
-
-## Product & Blog Types
-
-### Product
-
-```tsx
-{
-  id, title, slug, category, categoryLabel,
-  image: { url, alt },
-  images: [{ url, alt }],
-  salePrice, originalPrice, discount,
-  inStock: boolean,
-  badge: "hot" | "new" | "sale" | null,
-  rating, reviewCount,
-  variants: [{ sku, options, prices }],
-  tags: string[],
-}
-```
-
-### Blog
-
-```tsx
-{
-  id, title, slug, description, excerpt,
-  content: string (HTML, detail only),
-  image, coverImage,
-  category, categoryLabel,
-  author: { name, avatar },
-  createdAt, publishedAt,
-  tags: string[],
-  locale,
-}
-```
-
-### WebsiteSettings
-
-```tsx
-{
-  social_connections: [{ name, icon, link, platform, enabled }],
-  hotline_connections: [{ name, type, value, enabled }],
-  company_info: { name, tagline, description, logo_url },
-  contact_email: { email, enabled },
-}
-```
-
-## Context Provider Hierarchy
-
-The rendering tree wraps sections in multiple context providers:
-
-```
-PageDataProvider (products, blogs, settings, company)
-  → MotionProvider (animation tokens)
-    → ViewportProvider (isEditing, viewportMode)
-      → LocaleProvider (locale, supportedLocales)
-        → ThemeModeProvider (light/dark mode)
-          → CartProvider (shopping cart)
-            → SectionListRenderer
-              → SectionRenderer (per section)
-                → AnimationWrapper
-                  → Your Section Component
-```
-
-All contexts are accessible via hooks from `@onexapis/core/hooks`.
-
-## Editor Integration
-
-When `isEditing = true` (section is rendered in the editor preview):
-
-```tsx
-export function MySection({ section, isEditing }: SectionComponentProps) {
-  return (
-    <section>
-      {/* Show empty state placeholder in editor */}
-      {items.length === 0 && isEditing && (
-        <div className="border-2 border-dashed border-gray-300 p-8 text-center text-gray-500">
-          Add items to this section
-        </div>
-      )}
-
-      {/* Disable navigation in editor */}
-      {isEditing ? (
-        <span className="cursor-default">{linkText}</span>
-      ) : (
-        <a href={url}>{linkText}</a>
-      )}
-    </section>
-  );
-}
-```
-
-## Page Background System
-
-Every page has a background that comes from the theme by default, overridable per-page. This is a **page-level** feature (not section-level) — it wraps all sections on the page.
-
-### How it works
-
-Background is resolved with priority:
-
-1. **Per-page override** (`PageConfig.background`) — set via editor or page config
-2. **Theme default** (`ThemeDesignSystem.pageBackground`) — set in `theme.layout.ts`
-3. **Fallback** — solid white `#FFFFFF`
-
-### Setting the theme default
-
-In `theme.layout.ts`, add `pageBackground` inside `designSystem`:
-
-```typescript
-export const layoutConfig: ThemeLayoutConfig = {
-  // ...headerSections, footerSections...
-  designSystem: {
-    colors: {
-      primaryColor: "#3B82F6",
-      secondaryColor: "#8B5CF6",
-      colorMode: "light",
-    },
-    typography: { headingFont: "system-ui", bodyFont: "system-ui" },
-    layout: { spacing: "comfortable" },
-    pageBackground: {
-      type: "solid", // "solid" | "gradient" | "image" | "pattern" | "none"
-      color: "#FFFFFF", // Base background color
-    },
-  },
-};
-```
-
-### Background types
-
-| Type       | Fields                                                                  | Example                                                                       |
-| ---------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `solid`    | `color`                                                                 | `{ type: "solid", color: "#FFF8F0" }`                                         |
-| `gradient` | `gradient`, `color` (fallback)                                          | `{ type: "gradient", gradient: "linear-gradient(135deg, #667eea, #764ba2)" }` |
-| `image`    | `image`, `imageSize`, `imagePosition`, `imageFixed`, `color` (fallback) | `{ type: "image", image: "/bg.jpg", imageSize: "cover", imageFixed: true }`   |
-| `pattern`  | `pattern`, `color`, `opacity`, `overlayColor`                           | `{ type: "pattern", pattern: "dots", color: "#FAFAFA", opacity: 0.05 }`       |
-| `none`     | —                                                                       | `{ type: "none" }` (transparent, no wrapper)                                  |
-
-### Built-in CSS patterns
-
-These work out of the box with `type: "pattern"`:
-
-- `dots` — dot grid
-- `grid` — line grid
-- `diagonal-lines` — 45-degree stripes
-- `cross-dots` — offset dot grid
-- `noise` — fractal noise texture
-
-### Custom animated patterns
-
-Themes can provide custom pattern renderers (e.g., SVG-based animated backgrounds). Export the component from `bundle-entry.ts`:
-
-```typescript
-// In bundle-entry.ts
-export { SenBackground } from "./assets/sen-background";
-```
-
-The storefront will pick up exported `*Background` components and match them to pattern names. For example, `SenBackground` maps to `pattern: "sen"`.
-
-Custom pattern components receive these props:
-
-```typescript
-interface PatternProps {
-  opacity?: number; // Pattern opacity (default: 0.05)
-  color?: string; // Overlay color
-  className?: string; // Additional CSS classes
-}
-```
-
-### Per-page override
-
-In a page config (e.g., `pages/about.ts`), set `background`:
-
-```typescript
-export const aboutPageConfig = {
-  title: "About",
-  handle: "about",
-  // ...other config...
-  background: {
-    type: "gradient",
-    gradient: "linear-gradient(180deg, #EEF2FF 0%, #FFFFFF 50%)",
-  },
-};
-```
-
-### Accessing in sections via hook
-
-Use `usePageBackground()` to read the resolved background in section components:
-
-```tsx
-import { usePageBackground } from "@onexapis/core/hooks";
-
-export function MySection({ section }: SectionComponentProps) {
-  const { config, styles, hasPattern, pattern, patternOpacity } =
-    usePageBackground();
-  // config.type — "solid" | "gradient" | "image" | "pattern" | "none"
-  // config.color — base color
-  // styles — React.CSSProperties derived from config
-  // hasPattern — boolean, true if type === "pattern" && pattern is set
-  // pattern — pattern name (e.g., "sen", "dots")
-  // patternOpacity — number (0-1)
-}
-```
-
-### PageBackgroundConfig type reference
-
-```typescript
-interface PageBackgroundConfig {
-  type: "solid" | "gradient" | "image" | "pattern" | "none";
-  color?: string; // Base background color (hex/CSS)
-  gradient?: string; // CSS gradient value
-  image?: string; // Background image URL
-  imageSize?: "cover" | "contain" | "auto";
-  imagePosition?: string; // CSS background-position (default: "center")
-  imageFixed?: boolean; // Fixed background attachment
-  pattern?: string; // Pattern identifier
-  opacity?: number; // Pattern/overlay opacity (0-1, default: 0.05)
-  overlayColor?: string; // Pattern overlay color
-  className?: string; // Additional CSS classes
-}
-```
-
-### CSS variables
-
-The storefront injects these CSS variables when a page background is configured:
-
-- `--page-bg-color` — base color
-- `--page-bg-gradient` — gradient value
-- `--page-bg-pattern` — pattern name
-- `--page-bg-pattern-opacity` — opacity value
-- `--page-bg-overlay-color` — overlay color
-
-Use these in custom CSS if needed: `background-color: var(--page-bg-color);`
-
-## Dark/Light Mode
-
-Themes support light, dark, and system color modes via `useThemeMode()`:
-
-```tsx
-import { useThemeMode } from "@onexapis/core/hooks";
-
-export function MySection({ section }: SectionComponentProps) {
-  const { mode, isDark } = useThemeMode();
-  // mode: "light" | "dark" | "system"
-  // isDark: boolean (resolved — accounts for system preference)
-
-  return (
-    <section
-      style={{
-        backgroundColor: isDark ? "#1F2937" : "#FFFFFF",
-        color: isDark ? "#F9FAFB" : "#111827",
-      }}
-    >
-      {/* Content adapts to color mode */}
-    </section>
-  );
-}
-```
-
-### How dark mode works
-
-- The `ThemeModeProvider` at the app root sets a `dark` class on the HTML element
-- Tailwind's `dark:` variants work automatically: `className="bg-white dark:bg-gray-900"`
-- `useThemeMode()` gives you the current mode for JS-driven styling
-- The design system's `colorMode` field determines the default mode
-- Users can toggle via the editor's theme settings
-
-### Best practices
-
-- Use Tailwind's `dark:` variant for simple color swaps: `text-gray-900 dark:text-white`
-- Use `useThemeMode()` for complex conditional logic
-- Test sections in both modes — don't assume light mode only
-- CSS variables (`--background`, `--foreground`) auto-switch with dark mode
-
-## Locale / i18n
-
-Themes support multiple languages via `useLocale()`:
-
-```tsx
-import { useLocale } from "@onexapis/core/hooks";
-
-export function MySection({ section }: SectionComponentProps) {
-  const { locale, defaultLocale, supportedLocales } = useLocale();
-  // locale: "vi" | "en" | ...
-  // defaultLocale: "vi"
-  // supportedLocales: ["vi", "en"]
-
-  return (
-    <section>{locale === "vi" ? <h1>Xin chào</h1> : <h1>Hello</h1>}</section>
-  );
-}
-```
-
-### How i18n works
-
-- The default locale is `"vi"` (Vietnamese)
-- Supported locales: `["vi", "en"]`
-- Page content is stored per-locale in the database
-- The API supports `?locale=en` query parameter to get translated content
-- Translation overrides are stored as diffs from the base (default locale) page
-- The `LocaleProvider` at the app root provides the current locale via context
-
-### Best practices
-
-- Section components usually DON'T need i18n logic — the content comes from the editor (already translated)
-- The `ComponentRenderer` renders text from `component.content.text` which is locale-specific
-- Only use `useLocale()` if you need locale-aware formatting (dates, numbers, currency)
-- Use `toLocaleString()` for numbers: `price.toLocaleString("vi-VN")`
-- Use `Intl.DateTimeFormat` for dates: `new Intl.DateTimeFormat(locale).format(date)`
-
-## Section Registry
-
-Every section must be registered in `sections-registry.ts` with lazy imports:
-
-```tsx
-export const sectionsRegistry = {
-  hero: () => import("./sections/hero"),
-  features: () => import("./sections/features"),
-  pricing: () => import("./sections/pricing"),
-  // Add new sections here
-};
-```
-
-The build system uses this registry to code-split sections into the bundle.
-
-## Rules
-
-### DO
-
-- Use `ComponentRenderer` / `BlockRenderer` from `@onexapis/core/renderers` for nested content
-- Use `getSectionValues(section, schema)` to extract typed settings
-- Use `filterEnabledComponents()` to skip disabled components
-- Use `toComponentInstance()` to convert raw component data for ComponentRenderer
-- Include `data-section-id`, `data-block-id` attributes on wrapper elements
-- Handle the `isEditing` prop (show placeholders, disable navigation links)
-- Use `"use client"` directive at the top of section components
-- Use Tailwind CSS classes for layout (included in the build)
-- Declare `dataRequirements` in schema if section needs products/blogs/settings
-
-### DON'T
-
-- Don't import from `@onexapis/core/internal` — it's a private API
-- Don't use `document` or `window` without checking `typeof window !== "undefined"`
-- Don't hardcode API URLs — use hooks (`useProducts`, `useBlogs`)
-- Don't use `useEffect` for data fetching — use React Query hooks instead
-- Don't mutate `section.settings` directly — use the `onSettingsChange` callback
-- Don't use `require()` — themes are ES modules
-- Don't import React explicitly — it's auto-injected by the JSX transform
-
-## CLI Commands
-
-```bash
-onexthm init my-theme              # Scaffold new theme project
-onexthm create:section hero        # Create section (component + schema + index)
-onexthm create:block card          # Create block
-onexthm create:component badge     # Create component
-onexthm list                       # List all sections/blocks/components
-onexthm validate                   # Validate theme structure
-onexthm dev                        # Start dev server with live preview
-onexthm build                      # Compile theme for production
-onexthm upload --theme my-theme    # Upload bundle.zip to S3
-onexthm clone simple               # Clone an existing theme from S3
-onexthm download -t simple         # Download compiled theme
-onexthm config                     # Configure AWS/API credentials
-```
-
-## Example: Product Grid Section
-
-```tsx
-"use client";
-
-import type { SectionComponentProps } from "@onexapis/core/types";
-import { useProducts, useCart } from "@onexapis/core/hooks";
-import coreUtils from "@onexapis/core/utils";
-
-const { getSectionValues } = coreUtils;
-
-export function ProductGrid({
-  section,
-  schema,
-  isEditing,
-}: SectionComponentProps) {
-  const { settings } = getSectionValues(section, schema);
-  const limit = Number(settings.limit) || 8;
-  const columns = Number(settings.columns) || 3;
-
-  const { data, isLoading } = useProducts({ limit });
-  const { addItem } = useCart();
-  const products = data?.data ?? [];
-
-  if (isLoading) {
-    return (
-      <section
-        data-section-id={section.id}
-        data-section-type="product-grid"
-        className="py-16"
-      >
-        <div className="container mx-auto px-4">
-          <div className="animate-pulse grid grid-cols-3 gap-4">
-            {Array.from({ length: limit }).map((_, i) => (
-              <div key={i} className="h-64 bg-gray-200 rounded-lg" />
-            ))}
-          </div>
-        </div>
-      </section>
-    );
-  }
-
-  const colClass =
-    columns === 2
-      ? "md:grid-cols-2"
-      : columns === 4
-        ? "md:grid-cols-4"
-        : "md:grid-cols-3";
-
-  return (
-    <section
-      data-section-id={section.id}
-      data-section-type="product-grid"
-      className="py-16"
-      style={{ backgroundColor: String(settings.backgroundColor || "#FFFFFF") }}
-    >
-      <div className="container mx-auto px-4 max-w-6xl">
-        <div className={`grid grid-cols-1 ${colClass} gap-6`}>
-          {products.map((product) => (
-            <div
-              key={product.id}
-              className="border rounded-lg p-4 hover:shadow-md transition-shadow"
-            >
-              {product.image?.url && (
-                <img
-                  src={product.image.url}
-                  alt={product.name}
-                  className="w-full h-48 object-cover rounded mb-3"
-                />
-              )}
-              <h3 className="font-semibold text-lg">{product.name}</h3>
-              <p className="text-gray-600 mt-1">
-                {product.price?.toLocaleString()}đ
-              </p>
-              {!isEditing && (
-                <button
-                  onClick={() => addItem(product, 1)}
-                  className="mt-3 w-full py-2 bg-blue-600 text-white rounded hover:bg-blue-700 transition-colors"
-                >
-                  Add to Cart
-                </button>
-              )}
-            </div>
-          ))}
-        </div>
-      </div>
-    </section>
-  );
-}
-
-export default ProductGrid;
-```
-
-## Cart & Fly-to-Cart Animation
-
-The cart system uses `useCart()` for state and a flexible fly-to-cart animation triggered by `data-fly-to-cart-target`.
-
-### Cart State
-
-```tsx
-import { useCart } from "@onexapis/core/hooks";
-
-const {
-  items,
-  addItem,
-  removeItem,
-  updateQuantity,
-  clearCart,
-  itemCount,
-  subtotal,
-} = useCart();
-
-// Add to cart
-addItem({
-  productId: product.id,
-  name: product.title,
-  image: product.image,
-  price: product.salePrice,
-  slug: product.slug,
-});
-```
-
-### Fly-to-Cart Animation
-
-When a user clicks "Add to Cart", the product thumbnail flies from the button to the cart icon in the header.
-
-**Step 1: Mark any element as the cart target** (in header section):
-
-```tsx
-// Option A: Use any element — just add the data attribute
-<div data-fly-to-cart-target className="my-cart-icon">
-  <ShoppingCartIcon />
-  <span>{itemCount}</span>
-</div>;
-
-// Option B: Use CartIcon convenience component (auto-adds data-fly-to-cart-target)
-import { CartIcon } from "@onexapis/core/components";
-<CartIcon count={itemCount} onClick={() => openCartDrawer()} />;
-```
-
-**Step 2: ProductCard triggers animation automatically** — just pass `onAddToCart`:
-
-```tsx
-<ProductCard
-  product={product}
-  onAddToCart={(p) =>
-    addItem({
-      productId: p.id,
-      name: p.title,
-      image: p.image,
-      price: p.salePrice,
-    })
-  }
-/>
-```
-
-**Step 3: Custom trigger** (for buttons that aren't ProductCard):
-
-```tsx
-import { useFlyToCart } from "@onexapis/core/hooks";
-
-const { flyToCart } = useFlyToCart();
-
-<button onClick={(e) => {
-  flyToCart(e.currentTarget, product.image); // animation
-  addItem({ ... }); // cart logic
-}}>
-  Buy Now
-</button>
-```
-
-### How it works
-
-- `data-fly-to-cart-target` on any element → animation lands there (detected via `querySelector`)
-- `FlyToCartProvider` renders a portal with the flying thumbnail (CSS transition)
-- No refs or context wiring needed — just add the data attribute
-- Without `data-fly-to-cart-target` → cart still works, no animation
-
-## Server-Side APIs
-
-Server-side data fetching is available from `@onexapis/core/server`. Use in Next.js server components, server actions, or API routes.
-
-```tsx
-import {
-  fetchProducts,
-  fetchBlogs,
-  fetchSettings,
-  fetchCompany,
-  fetchTheme,
-  fetchPage,
-  prefetchSectionData,
-} from "@onexapis/core/server";
-
-// Fetch products (server-side with ISR caching)
-const { data: products, pagination } = await fetchProducts(companyId, {
-  limit: 12,
-});
-
-// Fetch website settings
-const settings = await fetchSettings(companyId);
-
-// Smart prefetch — scans sections for dataRequirements, fetches in parallel
-const data = await prefetchSectionData({
-  companyId,
-  sections: allSections,
-  dataRequirements: manifest.dataRequirements,
-});
-// data.products, data.blogs, data.settings
-```
-
-### Advanced: Custom server client
-
-```tsx
-import { CommerceServerClient, noopCacheAdapter } from "@onexapis/core/server";
-
-const client = new CommerceServerClient({
-  apiUrl: "https://api.example.com",
-  companyId: "xxx",
-  cacheAdapter: noopCacheAdapter, // For non-Next.js environments
-});
-
-const products = await client.getProducts({ limit: 8 });
-const blog = await client.getBlogBySlug("my-post");
-```
-
-Environment variables auto-detected: `NEXT_PUBLIC_COMMERCE_API_URL`, `NEXT_PUBLIC_API_URL`.
-
-## MCP Servers
-
-This project has THREE MCP servers. Do NOT confuse them:
-
-### `onexthm` MCP (Theme Development) — USE THIS
-
-Registered in `.mcp.json` in this project. Provides theme-specific tools:
-
-- `onexthm_create_section` — Generate section files (component + schema + index) from structured input
-- `onexthm_from_html` — **Convert HTML/React/JSX code to OneX section** (parses elements, maps to components, detects blocks)
-- `onexthm_from_figma` — **Convert Figma design to OneX section** (see Figma Integration below)
-- `onexthm_generate_schema` — Generate schema from natural language description
-- `onexthm_validate` — Validate theme structure (7 checks: entry file, config, sections, blocks, code quality, registry)
-- `onexthm_list_hooks` — List available hooks with usage examples
-
-Resources (auto-loaded context):
-
-- `onexthm://rules` — Theme development rules (DOs/DON'Ts)
-- `onexthm://field-types` — All available field types and categories
-- `onexthm://hooks` — Hooks reference with examples
-- `onexthm://components` — All component types with fields, slots, examples
-- `onexthm://blocks` — Block system patterns and data attributes
-
-Prompts (guided workflows):
-
-- `create_section` — Guided section creation workflow
-- `html_to_section` — Convert HTML/React code to OneX section
-- `figma_to_section` — Full Figma-to-OneX conversion pipeline
-- `review_theme` — Review theme for issues
-
-### `figma` MCP (Figma Design) — USE WITH `onexthm`
-
-Registered in `.mcp.json`. Reads Figma designs for design-to-code conversion:
-
-- `get_metadata` — Layer hierarchy (IDs, names, types, positions, sizes)
-- `get_design_context` — React + Tailwind code suggestion for selected layers
-- `get_variable_defs` — Design tokens (colors, typography, spacing variables)
-- `get_screenshot` — Visual screenshot of selected elements
-- `search_design_system` — Search components, variables, styles from libraries
-
-**Setup**: Requires Figma API key in `.mcp.json`:
-
-```json
-{
-  "figma": {
-    "command": "npx",
-    "args": ["-y", "figma-developer-mcp", "--figma-api-key=YOUR_KEY", "--stdio"]
-  }
-}
-```
-
-Get your key: Figma → Settings → Account → Personal access tokens.
-
-### `onex-platform` MCP (Backend Services) — DO NOT USE FOR THEMES
-
-This is for managing microservices on the OneXEOS platform. Its tools are:
-
-- `onex_invoke`, `onex_status`, `onex_deploy`, `onex_logs`, `onex_test`
-- These manage backend services (auth, product, order, etc.)
-- **Do NOT use these for theme development** — they have nothing to do with sections, schemas, or theme components
-
-### When to use which
-
-| Task                             | MCP to use                           |
-| -------------------------------- | ------------------------------------ |
-| Create a new section             | `onexthm_create_section`             |
-| Convert HTML/React to section    | `onexthm_from_html`                  |
-| Convert Figma design to section  | `onexthm_from_figma` + `figma` tools |
-| Generate schema from description | `onexthm_generate_schema`            |
-| Validate theme structure         | `onexthm_validate`                   |
-| Look up available hooks          | `onexthm_list_hooks`                 |
-| Read Figma design layers         | `figma:get_metadata`                 |
-| Get Figma design tokens          | `figma:get_variable_defs`            |
-| Deploy a backend service         | `onex_deploy` (platform MCP)         |
-| Check service health             | `onex_status` (platform MCP)         |
-
-## Figma → OneX Conversion
-
-Convert Figma designs directly to OneX theme sections using the combined Figma + OneX MCP pipeline.
-
-### Quick Start
-
-Use the `figma_to_section` prompt for a guided workflow:
-
-```
-"Convert the selected Figma frame to a section called 'hero'"
-```
-
-Or manually orchestrate the steps:
+  dynamicSegments: ["slug"]
+})
 
-```
-1. figma:get_metadata        → Get layer hierarchy
-2. figma:get_variable_defs   → Get design tokens
-3. figma:get_design_context  → Get React+Tailwind code
-4. onexthm:onexthm_from_figma → Convert to OneX section files
-5. Write files to sections/ directory
-6. onexthm:onexthm_validate  → Validate
-7. Register in sections-registry.ts
-```
+// Validate after any write
+onexthm_validate({ projectDir: "<absolute path to this directory>" })
 
-### How Figma Layers Map to OneX
+// Auto-fix validation errors
+onexthm_fix({ projectDir: "<absolute path to this directory>" })
 
-```
-Figma Layer                     →   OneX Concept
-────────────────────────────────────────────────
-Top-level Frame                 →   Section
-Nested Frame/Group              →   Block
-TEXT (large >=24px, bold >=600) →   heading (h1-h6)
-TEXT (body <24px)               →   paragraph
-Button instance                 →   button component
-Image node                      →   image component
-Icon instance                   →   icon component
-Badge/Label                     →   badge component
-Repeating children (same shape) →   Block definition
-Background color fill           →   backgroundColor setting
-Background image fill           →   backgroundImage setting
-Auto Layout horizontal          →   flex flex-row (Tailwind)
-Auto Layout vertical            →   flex flex-col (Tailwind)
-Auto Layout gap                 →   gap-N (Tailwind)
+// Build the theme
+onexthm_build({ projectDir: "<absolute path to this directory>" })
 ```
 
-### `onexthm_from_figma` Tool Parameters
+All tools default to writing files on disk. Pass `dryRun: true` if the user
+explicitly asks to preview without writing. Pass `force: true` to overwrite
+existing files.
 
-```typescript
-{
-  figmaMetadata: string,    // Required: XML/JSON from figma:get_metadata
-  figmaVariables?: string,  // Optional: JSON from figma:get_variable_defs
-  figmaCode?: string,       // Optional: code from figma:get_design_context (fallback)
-  sectionName: string,      // Required: kebab-case name (e.g., "hero")
-  category?: string,        // Optional: section category
-  themePrefix?: string,     // Optional: type prefix (e.g., "my-simple")
-}
-```
-
-Returns generated files: `{name}.schema.ts`, `{name}-default.tsx`, `index.ts`, plus registry entry.
+---
 
-### `onexthm_from_html` Tool Parameters
+## After a tool call
 
-```typescript
-{
-  htmlCode: string,       // Required: Raw HTML or React/JSX code
-  sectionName: string,    // Required: kebab-case name (e.g., "hero-banner")
-  category?: string,      // Optional: section category
-  themePrefix?: string,   // Optional: type prefix (e.g., "my-simple")
-}
-```
+1. Read the tool's response — it lists what was written and warns about anything skipped.
+2. Run `onexthm_validate` if the tool didn't already.
+3. Show the user the new file paths so they know where to edit further.
+4. Only edit the generated files **after** they exist on disk — never re-generate by hand.
 
-Returns generated files: `{name}.schema.ts`, `{name}-default.tsx`, `index.ts`, plus registry entry.
+---
 
-### How HTML Elements Map to OneX
+## When the answer isn't here
 
-```
-HTML Element                        →   OneX Component
-────────────────────────────────────────────────────
-<h1>-<h6>                          →   heading (with tag h1-h6)
-<p>, <span>                        →   paragraph
-<button>, <a class="btn/cta">      →   button
-<a>                                →   link
-<img>                              →   image
-<svg>, icon components             →   icon
-<ul>/<ol>                          →   list
-<hr>                               →   divider
-<blockquote>                       →   quote
-<input>, <textarea>, <select>      →   input/textarea/select
-<video>                            →   video
-<table>                            →   table
-<div>, <section>, <article>        →   layout containers (recurse)
-Repeating sibling structures       →   block definitions
-Tailwind flex/grid classes         →   layout settings
-Tailwind bg-* classes              →   backgroundColor setting
-Tailwind text-* classes            →   fontSize/textAlign
-React <Button>, <Card>, etc.       →   resolved to HTML equivalents
-```
+If the user's question is about hooks, components, blocks, animation, dark
+mode, locale, dynamic pages, payments, the cart, or any deep API question,
+either:
 
-### Pixel → Tailwind Reference
+- Read `THEME_REFERENCE.md` (lives next to this file), or
+- Call `onexthm_list_hooks` for hook signatures, or
+- Read the `onexthm://components`, `onexthm://blocks`, `onexthm://field-types`,
+  `onexthm://hooks`, or `onexthm://rules` MCP resources.
 
-```
-Font Size:  12→xs  14→sm  16→base  18→lg  20→xl  24→2xl  30→3xl  36→4xl  48→5xl  60→6xl
-Spacing:    4→1  8→2  12→3  16→4  20→5  24→6  32→8  40→10  48→12  64→16  80→20  96→24
-Weight:     100-400→normal  500→medium  600→semibold  700+→bold
-```
+`THEME_REFERENCE.md` is the canonical reference document for everything not
+covered by these routing rules.