# CLAUDE.md — Routing rules for AI agents

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.

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.

---

## Before you start

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:

> "The onexthm MCP server is not loaded. Restart your AI client after
> verifying `.mcp.json` registers `@onexapis/theme-mcp`."

Do not silently fall back to writing files by hand.

---

## Routing rules — what tool to call when

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

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

---

## Forbidden behaviors

These break the editor and storefront. Never do them.

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

---

## Calling the tools — minimal examples

```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"
})

// 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>"
})

// 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>"
})

// Create a page
onexthm_create_page({
  projectDir: "<absolute path to this directory>",
  handle: "product-detail",
  path: "/products/[slug]",
  isDynamic: true,
  dynamicSegments: ["slug"]
})

// Validate after any write
onexthm_validate({ projectDir: "<absolute path to this directory>" })

// Auto-fix validation errors
onexthm_fix({ projectDir: "<absolute path to this directory>" })

// Build the theme
onexthm_build({ projectDir: "<absolute path to this directory>" })
```

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.

---

## After a tool call

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.

---

## When the answer isn't here

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:

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

`THEME_REFERENCE.md` is the canonical reference document for everything not
covered by these routing rules.
