> ## Documentation Index
> Fetch the complete documentation index at: https://developer.leaderos.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Developing Themes with AI

> Have Claude Code, Cursor and similar tools build and customize your LeaderOS theme.

The Headless API is designed to **work with AI from the start**. If you give an AI assistant the right context, you can build or customize the whole theme by chatting.

## Four sources of context for the AI

| Source | What it provides | Where |
| - | - | - |
| `AGENTS.md` / `CLAUDE.md` | Project rules, architecture, patterns, prohibitions | Template root |
| MCP server | Live endpoint search, schema reading, sample calls | `.mcp.json` ([MCP](https://developer.leaderos.net/headless/en/mcp.md)) |
| `llms-full.txt` | Plain-text reference of the whole API | `https://your-site.com/headless/llms-full.txt` |
| OpenAPI | Machine-readable definition | `https://your-site.com/headless/openapi.json` |

## Method 1: Ready template + Claude Code / Cursor (recommended)

**1. Create the template**

```bash theme={null}
npm create leaderos-theme@latest my-theme
cd my-theme && npm install
```

The template ships with `AGENTS.md`, `CLAUDE.md` and `.mcp.json`; no extra setup is needed.

**2. Start the assistant in the project folder**

```bash theme={null}
claude        # Claude Code
```

or open the folder in Cursor / Windsurf. The assistant reads `AGENTS.md` automatically and connects the MCP server from `.mcp.json` (it may ask for approval the first time).

**3. Run the dev server**

Watch the result live with `npm run dev`.

**4. Write your request**

Use one of the sample prompts below.

### Sample prompts

> [accordion] Changing the design
>
> > "Turn the whole site into a dark purple/neon gaming theme. Redesign the hero section on the home page and make product cards image-focused. Keep data and functionality the same."

> [accordion] A new page
>
> > "Add a new `/ranking` page that shows the leaderboards. First check the site config and confirm the leaderboards module is on; if not, return 404."

> [accordion] Customizing the store
>
> > "On the store home page, move categories to a left sidebar and show the discount rate as a badge on product cards."

> [accordion] Debugging
>
> > "After logging in, the account page returns EMAIL\_NOT\_VERIFIED. Why? Add the right redirect."

## Method 2: An existing or empty project

If you do not use the template, give the assistant:

1. Add the MCP server: `claude mcp add leaderos -e LEADEROS_URL=... -e LEADEROS_PUBLIC_KEY=... -- npx -y @leaderos/headless-mcp`
2. Point it to the API reference in your first message:

> "Read this reference: [https://your-site.com/headless/llms-full.txt](https://your-site.com/headless/llms-full.txt). We will build a Next.js store with this API. Use @leaderos/headless-sdk."

## Method 3: Chat tools (ChatGPT, Claude.ai, Gemini)

If you cannot use MCP, paste the content of `llms-full.txt` into the chat or upload the file, then describe the page you want. This is enough for small components and single pages; for managing a whole project, Method 1 is far more efficient.

## What does `AGENTS.md` say?

The template's `AGENTS.md` holds the rules the AI must follow, for example:

* Branch on error codes (`error.code`), not messages.
* Use `requireAuth()` on every page that needs a login.
* Do not show a feature whose module is off (`isModuleActive` / `useModule`).
* Never keep the token in client state or `localStorage`.
* Show the `*Formatted` fields for money values.
* **Never remove or hide** the `<PoweredBy />` component.

Append your own rules (color palette, component library, code style) to the end of this file to steer the assistant.

> [!WARNING]
>
> The template tells the AI explicitly not to remove the "Powered by LeaderOS" link. It will refuse even if you ask; removal is only possible when `config.branding.canRemove` is `true`. This is a license requirement.

## Tips for good results

> [!TIP]
>
> * Work in small, clear steps: "product card → store page → cart".
> * Tell the assistant **what not to change** first ("don't touch API calls and guards").
> * After each step ask it to run `npm run typecheck` and `npm run build`.
> * Keep MCP on so it sees real data; this largely prevents invented field names.
> * After changing critical flows such as payments, always test by hand on a **test site**.

## Security warnings

* `LEADEROS_ALLOW_WRITE=1` in MCP should only be used on a test site.
* Do not give the AI your **admin panel passwords or database credentials**; the public key is all the Headless API needs.
* Review generated code before going live, especially form submissions and payment flows.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.