# ThemeForge — machine entry point for AI assistants

ThemeForge turns a static HTML site into a WordPress theme with a working admin panel.
You mark elements with attributes (fld- / opt- / tax-); the generator turns those into
custom fields, page templates and the admin UI the site owner will edit.

Read this page first, then pull only the modules the site needs.

## 1. Agree the site map BEFORE you design anything

File names decide WordPress templates: `single-product.html` becomes the product template,
`archive.html` the blog list, `about.html` a static page (`about.php`). A file named
`blog.html` becomes a static page called blog, NOT the blog feed — the generator does not
guess.

So your FIRST reply to the person is a site map, not markup:

- every page file with its slug;
- content types the site needs (blog posts, custom types, taxonomies, products);
- which values are site-wide — header, footer, contacts — they belong in `theme-options.html`;
- languages.

Wait for confirmation, then build. Changing a slug later means regenerating the theme.

## 2. Pull the rules

    GET https://themeforge.pro/ai?m=core       <- always, before writing any markup
    GET https://themeforge.pro/ai?m=build      <- if you are GENERATING the site, not annotating an existing one
    GET https://themeforge.pro/ai?m=<module>   <- add what this site needs

| module | pull it when | bytes |
|---|---|---|
| core | always — read this before writing any markup | 33108 |
| build | you are GENERATING the site, not annotating an existing one — read it with core, before designing | 9016 |
| pages | when you need the page/template naming: which slug becomes which template | 3844 |
| blog | the site has a blog, news or any post listing | 1539 |
| cpt | the site has its own content type (projects, services, events) | 1931 |
| woocommerce | the site sells something — catalog, product, cart, checkout, wishlist | 16249 |
| deploy | you are finishing: what to hand over and in what shape | 4736 |
| legacy | you are reading markup that uses the older f_ / o_ / t_ spellings | 1306 |

`all` returns the whole canon (71717 bytes). An unknown module name returns the core
rules rather than an error.

## 3. The design is yours

The rules constrain STRUCTURE only — attribute names, page slugs, how repeatable blocks are
expressed. Layout, styling, typography, imagery, animation: no constraints. Do not imitate
any ThemeForge sample; build what the person asked for.

## 4. Check yourself — free, no account

    POST https://themeforge.pro/api/validate-markup
    Content-Type: application/json

    {"pages":[{"name":"index.html","html":"…"},{"name":"theme-options.html","html":"…"}]}

Runs the real generator's parser and lists what it would object to, most severe first:
`error` breaks the theme, `warning` means something is silently dropped, `hint` is worth
knowing. Send the WHOLE set in one request and repeat until `"ok": true`. Nothing is stored.

`"ok": true` means: no two things share a field name, no repeater lost its row, no unknown
or misplaced attribute, the home page exists, the options page exists and declares fields.
It does NOT check — these are on you: every `opt-*` also on `theme-options.html`, two real
rows per repeater, `fld-tab` right before its group, and a container name used on two pages
with different insides.

## 5. Deliver

One ZIP of the site's CONTENTS — `index.html` at the root of the archive, not inside a
folder — with every page of the agreed map, `theme-options.html`, and CSS, JS and images by
relative paths (no CDN links).

**If you can make HTTP requests**, build the theme yourself:

    POST https://themeforge.pro/api/projects/<project-id>/build?token=<token>
    Content-Type: application/zip
    <the ZIP>

Every page in the archive is built: the archive is the page list. The answer is JSON with
`zip_url` (a one-time download of the WordPress theme), `pages` and `templates` (what was
built — compare them with the map), `warnings` and `issues`. The archive is deleted after
the build; the theme behind `zip_url` is deleted once downloaded, or after 24 hours.

The id and the token come from the person's ThemeForge project. The panel does not display
them yet: they are inside any theme downloaded from that project, the blank one included —
the id in `themeforge_origin.php`, the token in `tf-update-key.php`.

**If you cannot**, hand the person the ZIP. They create a project, tick "The source will be
uploaded on the site", install the blank theme it gives them, and upload your ZIP in
wp-admin → ThemeForge → Site source. Step by step: https://themeforge.pro/docs/site-source

The full hand-over checklist is in the `deploy` module.

---
Attribute format: `fld-` / `opt-` / `tax-` (the older `f_` / `o_` / `t_` spellings still work).
Guide for people, six languages: https://themeforge.pro/docs/ai-guide