From 90c6ab57b5d7d16a3960c5ff402fbccdc94c05bb Mon Sep 17 00:00:00 2001
From: Jordan Diaz <panksft@hotmail.com>
Date: Wed, 1 Apr 2026 15:25:06 +0000
Subject: [PATCH] mas

---
 docs/builder-fields.md        | 7 +++++++
 docs/mcp-tools-reference.md   | 8 ++++----
 docs/module-creation-guide.md | 3 +++
 3 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/docs/builder-fields.md b/docs/builder-fields.md
index 0c95001..4bf7192 100644
--- a/docs/builder-fields.md
+++ b/docs/builder-fields.md
@@ -4,6 +4,13 @@
 
 El atributo `data-field-label` se convierte a variable removiendo espacios y caracteres especiales (minúsculas).
 
+Reglas obligatorias:
+- Todo elemento editable con `data-field-type` debe incluir también `data-field-label`
+- Si falta `data-field-label`, el builder puede generar variables temporales o incorrectas y el módulo queda mal configurado
+- Usa labels descriptivos y estables; no dejes labels vacíos ni genéricos como "Campo" o "Texto"
+
+Evita también en `index-base.tpl` las clases Tailwind con valores arbitrarios como `text-[44px]`, `font-['Cinzel']` o `leading-[1.1]`. En este stack pueden romper el parseo/compilación del template. Muévelas a `style.css`.
+
 | Label | Variable |
 |-------|----------|
 | Categoría Noticia | `categoranoticia` |
diff --git a/docs/mcp-tools-reference.md b/docs/mcp-tools-reference.md
index 7b5a8e5..3c71c11 100644
--- a/docs/mcp-tools-reference.md
+++ b/docs/mcp-tools-reference.md
@@ -11,7 +11,7 @@
 | `acai-glob` | Archivos | Busca rutas de archivos por patrón |
 | `acai-grep` | Archivos | Busca texto en archivos del proyecto |
 | `acai-line-replace` | Archivos | Reemplaza un bloque concreto en un archivo existente |
-| `acai-write` | Archivos | Crea o reescribe un archivo completo. Antes de usarlo, lee la doc correspondiente según el tipo de archivo (`module-creation-guide`, `css-js-conventions`, `hooks-and-api`) |
+| `acai-write` | Archivos | Crea o reescribe un archivo completo. Antes de usarlo, lee la doc correspondiente según el tipo de archivo (`module-creation-guide`, `builder-fields`, `css-js-conventions`, `hooks-and-api`) |
 | `acai-delete` | Archivos | Borra un archivo del proyecto |
 | `list_page_modules` | Registros | Lista módulos de una página |
 | `add_module_to_record` | Registros | Añade módulo a una página |
@@ -86,13 +86,13 @@ Reglas:
    - `tableName`: `"builder_custom"` (siempre sin cms_)
    - `recordId`: el recordNum del paso 1
    - `fieldName`: el campo de relations del builder.json (ej: `image1`)
-   - `imageUrl`: URL accesible desde Docker (ej: `http://localhost/cms/uploads/...`)
+   - `imageUrl`: usa la URL recomendada por la tool que generó/subió la imagen. En Forge, si `generate_image` devuelve `uploadUrl` o `fullUrl`, priorízala frente a `dockerUrl`
 
 ### Generar imagen con IA
 
 1. `generate_image` con prompt descriptivo + style (photographic, digital-art, minimalist...)
-2. La imagen se guarda en `cms/uploads/generated/` y devuelve `dockerUrl`
-3. Usar esa `dockerUrl` con `upload_record_image` para asignarla a un módulo
+2. La imagen se guarda en `cms/uploads/generated/` y devuelve una URL local de preview (`dockerUrl`) y, cuando aplica, una URL recomendada para subida (`uploadUrl` / `fullUrl`)
+3. Para `upload_record_image`, usa la URL recomendada por la tool. En Forge, prioriza `uploadUrl` o `fullUrl` si están presentes
 
 ### Gestionar registros de una tabla
 
diff --git a/docs/module-creation-guide.md b/docs/module-creation-guide.md
index 5784941..0e23bb6 100644
--- a/docs/module-creation-guide.md
+++ b/docs/module-creation-guide.md
@@ -40,6 +40,7 @@ Each module lives in `template/estandar/modulos/<moduleId>/` with:
 If the module needs JavaScript, you MUST read `docs/css-js-conventions.md` before writing `index-base.tpl` or `script.js`.
 If the module needs server-side logic, dynamic data processing, form handling, or reusable backend behavior, you MUST read `docs/hooks-and-api.md` before creating `hook.php` or any global hook.
 If the module will call hooks from Twig, also review `docs/twig-filters.md` for the `hook` filter syntax.
+If `index-base.tpl` contains builder fields (`data-field-type`), you MUST review `docs/builder-fields.md` before writing the template.
 
 Hard rules for module files:
 - `index-base.tpl` is for HTML/Twig only
@@ -51,6 +52,8 @@ Hard rules for module files:
 - `script.js` and `style.css` are static files: do NOT use Twig syntax inside them
 - Do NOT use `{{ ... }}`, `{% ... %}`, `c-if`, `c-for`, or builder attributes inside `script.js` or `style.css`
 - If JavaScript needs dynamic values such as `section_id` or a hook endpoint, expose them from `index-base.tpl` via `data-*` attributes
+- Every editable builder field with `data-field-type` MUST also define `data-field-label`
+- Avoid Tailwind arbitrary-value syntax such as `text-[...]`, `font-[...]`, `leading-[...]`, `bg-[...]` inside `index-base.tpl`; move those styles to `style.css`
 
 1. **Read style reference** (steps above)
 2. **`acai-write`** — Create the module files directly (`index-base.tpl`, `style.css`, `script.js`, optional `hook.php`) using project-relative paths and complete file contents.