@onexapis/cli 1.1.39 → 1.1.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onexapis/cli",
-  "version": "1.1.39",
+  "version": "1.1.40",
   "description": "CLI tool for OneX theme development - scaffolds themes using @onexapis/core",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/templates/default/CLAUDE.md

@@ -2,6 +2,59 @@
 
 This file provides context to AI assistants (Claude, Cursor, Copilot) for developing OneX themes.
 
+## 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
+
+---
+
 ## 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.**
@@ -10,7 +63,7 @@ This file provides context to AI assistants (Claude, Cursor, Copilot) for develo
 
 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.
 
-You can use `onexthm_create_section` MCP tool or `onexthm create:section` CLI to scaffold, but if writing manually, every section MUST have:
+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`
@@ -1537,22 +1590,26 @@ This project has THREE MCP servers. Do NOT confuse them:
 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
-- `onexthm_generate_schema` — Generate schema from natural language description
-- `onexthm_from_figma` — **Convert Figma design to OneX section** (see Figma Integration below)
 
 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
-- `review_theme` — Review theme for issues
+- `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`
 
@@ -1590,10 +1647,11 @@ This is for managing microservices on the OneXEOS platform. Its tools are:
 | 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`                 |
-| Generate schema from description | `onexthm_generate_schema`            |
 | Read Figma design layers         | `figma:get_metadata`                 |
 | Get Figma design tokens          | `figma:get_variable_defs`            |
 | Deploy a backend service         | `onex_deploy` (platform MCP)         |
@@ -1659,6 +1717,44 @@ Auto Layout gap                 →   gap-N (Tailwind)
 
 Returns generated files: `{name}.schema.ts`, `{name}-default.tsx`, `index.ts`, plus registry entry.
 
+### `onexthm_from_html` Tool Parameters
+
+```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")
+}
+```
+
+Returns generated files: `{name}.schema.ts`, `{name}-default.tsx`, `index.ts`, plus registry entry.
+
+### How HTML Elements Map to OneX
+
+```
+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
+```
+
 ### Pixel → Tailwind Reference
 
 ```