diff --git a/CLAUDE.md b/CLAUDE.md index 6829135..cb1da75 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -103,7 +103,7 @@ Do NOT modify web-base files — they are shared across all projects. ## Critical Rules 1. **Before working with any area (hooks, modules, templates, CSS/JS, etc.), read the corresponding documentation in `docs/` first.** Do not guess or assume — always consult the docs before taking action. -2. **NEVER use `mkdir` to create directories.** Instead, use the `Write` tool to create the first file inside the directory — this creates parent directories automatically. For example, to create a new module, directly write the `index-base.tpl` file. +2. **NEVER use `mkdir` to create directories.** Instead, use `acai-write` to create the first file inside the directory — this creates parent directories automatically. For example, to create a new module, directly write the `index-base.tpl` file. 3. Only edit `index-base.tpl` in modules — `index.tpl`, `index-twig.tpl`, and `builder.json` are auto-generated 3. **After editing any `index-base.tpl`, ALWAYS call the `compile_module` MCP tool** to compile the module/section. This is mandatory — without compilation, changes won't take effect in the CMS. 4. Use Twig **filters** (with `|`), never Twig functions @@ -122,8 +122,8 @@ This project has MCP tools for managing modules, records, media, and more. **Bef See [docs/mcp-tools-reference.md](docs/mcp-tools-reference.md) for the complete list of available tools and step-by-step workflows. Key workflows: -- **Create module**: Read [docs/module-creation-guide.md](docs/module-creation-guide.md) first → `create_module` → `add_module_to_record` (returns sectionId) → `set_module_config_vars` (returns uploadFields) → images via uploadFields -- **Edit module**: read vars → edit `index-base.tpl` → `compile_module` +- **Create module**: Read [docs/module-creation-guide.md](docs/module-creation-guide.md) first → create files with `acai-write` / refine with `acai-line-replace` → `compile_module` → `add_module_to_record` (returns sectionId) → `set_module_config_vars` (returns uploadFields) → images via uploadFields +- **Edit module**: `acai-view` → `acai-line-replace` (or `acai-write` for full rewrites) → `compile_module` - **Add images**: use `uploadFields` from `set_module_config_vars` response → `upload_record_image` - **Generate images**: `generate_image` → `upload_record_image` with returned URL diff --git a/docs/mcp-tools-reference.md b/docs/mcp-tools-reference.md index 317534a..5af5633 100644 --- a/docs/mcp-tools-reference.md +++ b/docs/mcp-tools-reference.md @@ -4,11 +4,14 @@ | Tool | Categoría | Acción | |------|-----------|--------| -| `create_module` | Módulos | Crea módulo nuevo (directorio + archivos + compila) | | `compile_module` | Módulos | Compila módulo tras editar index-base.tpl | | `check_module` | Módulos | Preview de cómo renderiza un módulo | | `check_module_usage` | Módulos | Qué páginas usan un módulo | | `set_module_example_data` | Módulos | Datos de ejemplo para editor visual | +| `acai-view` | Archivos | Lee un archivo del proyecto por tramos | +| `acai-line-replace` | Archivos | Reemplaza un bloque concreto en un archivo existente | +| `acai-write` | Archivos | Crea o reescribe un archivo completo | +| `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 | | `remove_module_from_record` | Registros | Elimina módulo de una página | @@ -37,21 +40,35 @@ ### Crear un módulo nuevo desde cero -1. `create_module` — Crea el directorio con index-base.tpl, style.css, script.js y compila -2. `add_module_to_record` — Añade el módulo a una página (tabla padre, ej: `apartados`) -3. `set_module_config_vars` — Rellena las variables con contenido (textos, colores, opciones). **OBLIGATORIO** — sin esto el módulo no muestra nada. Devuelve: +1. `acai-write` — Crea `index-base.tpl`, `style.css`, `script.js` y cualquier hook necesario con rutas relativas al proyecto +2. `compile_module` — Compila el módulo tras editar `index-base.tpl` +3. `add_module_to_record` — Añade el módulo a una página (tabla padre, ej: `apartados`) +4. `set_module_config_vars` — Rellena las variables con contenido (textos, colores, opciones). **OBLIGATORIO** — sin esto el módulo no muestra nada. Devuelve: - `configVars`: mapa de variables → recordNums - `uploadFields`: mapa de variables upload → `{ fieldName, recordNum }` — **usa estos directamente** para subir imágenes sin necesidad de leer builder.json - Para vars multi con uploads: `uploadFields["varName.subVarName"]` es un array con `[{ index, fieldName, recordNum }]` -4. Para imágenes: `generate_image` o `upload_record_image` usando el `recordNum` y `fieldName` del `uploadFields` devuelto en el paso 3 -5. Verificar con `check_module` o recargando la página +5. Para imágenes: `generate_image` o `upload_record_image` usando el `recordNum` y `fieldName` del `uploadFields` devuelto en el paso 4 +6. Verificar con `check_module` o recargando la página ### Editar un módulo existente 1. `get_module_config_vars` — Leer el estado actual del módulo (variables, recordNums) -2. Editar `index-base.tpl` con la tool `Write` o `Edit` -3. `compile_module` — **OBLIGATORIO** tras cada edición de index-base.tpl -4. Si cambias variables: `set_module_config_vars` para actualizar valores +2. `acai-view` — Leer solo el tramo de `index-base.tpl` que se va a modificar +3. `acai-line-replace` — Editar el bloque concreto. Usa `acai-write` solo si el archivo es nuevo o el cambio es masivo +4. `compile_module` — **OBLIGATORIO** tras cada edición de index-base.tpl +5. Si cambias variables: `set_module_config_vars` para actualizar valores + +### Editar archivos del proyecto con bajo consumo de tokens + +1. `acai-view` — Leer el archivo o un rango de líneas +2. `acai-line-replace` — Reemplazar el bloque exacto en archivos existentes +3. `acai-write` — Crear archivos nuevos o reescribirlos por completo si es necesario +4. `acai-delete` — Borrar archivos solo cuando sea explícitamente necesario + +Reglas: +- Usa siempre rutas relativas al proyecto +- No edites `index.tpl`, `index-twig.tpl` ni `builder.json` — son auto-generados +- Tras editar cualquier `index-base.tpl`, llama a `compile_module` ### Añadir/modificar imágenes de un módulo diff --git a/docs/module-creation-guide.md b/docs/module-creation-guide.md index 4b0f559..8002171 100644 --- a/docs/module-creation-guide.md +++ b/docs/module-creation-guide.md @@ -38,11 +38,12 @@ Each module lives in `template/estandar/modulos//` with: ## Creating a Module — Full Workflow 1. **Read style reference** (steps above) -2. **`create_module`** — Creates the directory with index-base.tpl, style.css, script.js and compiles. Use descriptive `moduleId` and clear `label`. -3. **`add_module_to_record`** — Adds the module to a page. Response includes `sectionId` — use it directly in the next step. -4. **`set_module_config_vars`** — Fill variables with content. Response includes `uploadFields` with `{ fieldName, recordNum }` for each upload variable. -5. **Upload images** — Use `generate_image` then `upload_record_image` with the `recordNum` and `fieldName` from step 4's `uploadFields`. No need to read builder.json or call get_module_config_vars. -6. **`navigate_browser`** — Navigate to the page so the user can see the result. +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. +3. **`compile_module`** — Compile after editing `index-base.tpl` so the CMS syncs the generated output. +4. **`add_module_to_record`** — Adds the module to a page. Response includes `sectionId` — use it directly in the next step. +5. **`set_module_config_vars`** — Fill variables with content. Response includes `uploadFields` with `{ fieldName, recordNum }` for each upload variable. +6. **Upload images** — Use `generate_image` then `upload_record_image` with the `recordNum` and `fieldName` from step 5's `uploadFields`. No need to read builder.json or call get_module_config_vars. +7. **`navigate_browser`** — Navigate to the page so the user can see the result. ## HTML Field Types