fix: update compile and git handlers for permission normalization

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
+- **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**: read vars → edit `index-base.tpl` → `compile_module`
+- **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
 

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
+1. `acai-write` — Crea `index-base.tpl`, `style.css`, `script.js` y cualquier hook necesario con rutas relativas al proyecto
-2. `add_module_to_record` — Añade el módulo a una página (tabla padre, ej: `apartados`)
+2. `compile_module` — Compila el módulo tras editar `index-base.tpl`
-3. `set_module_config_vars` — Rellena las variables con contenido (textos, colores, opciones). **OBLIGATORIO** — sin esto el módulo no muestra nada. Devuelve:
+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. Para imágenes: `generate_image` o `upload_record_image` usando el `recordNum` y `fieldName` del `uploadFields` devuelto en el paso 4
-5. Verificar con `check_module` o recargando la página
+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`
+2. `acai-view` — Leer solo el tramo de `index-base.tpl` que se va a modificar
-3. `compile_module` — **OBLIGATORIO** tras cada edición de index-base.tpl
+3. `acai-line-replace` — Editar el bloque concreto. Usa `acai-write` solo si el archivo es nuevo o el cambio es masivo
-4. Si cambias variables: `set_module_config_vars` para actualizar valores
+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
 

docs/module-creation-guide.md

@@ -38,11 +38,12 @@ Each module lives in `template/estandar/modulos/<moduleId>/` 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`.
+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. **`add_module_to_record`** — Adds the module to a page. Response includes `sectionId` — use it directly in the next step.
+3. **`compile_module`** — Compile after editing `index-base.tpl` so the CMS syncs the generated output.
-4. **`set_module_config_vars`** — Fill variables with content. Response includes `uploadFields` with `{ fieldName, recordNum }` for each upload variable.
+4. **`add_module_to_record`** — Adds the module to a page. Response includes `sectionId` — use it directly in the next step.
-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.
+5. **`set_module_config_vars`** — Fill variables with content. Response includes `uploadFields` with `{ fieldName, recordNum }` for each upload variable.
-6. **`navigate_browser`** — Navigate to the page so the user can see the result.
+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