docs/mcp-tools-reference.md

@@ -13,6 +13,8 @@
 | `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`, `builder-fields`, `css-js-conventions`, `hooks-and-api`) |
 | `acai-delete` | Archivos | Borra un archivo del proyecto |
+| `get_layout_field` | Layout global | Lee header/footer/CSS global/JS global (`field: header\|footer\|style\|javascript`) — NO son ficheros normales, ver [docs/modular-system.md](modular-system.md) |
+| `set_layout_field` | Layout global | Escribe header/footer/CSS global/JS global — **reemplazo destructivo del contenido completo**, no hay line-replace; verificar `compile_ok` en la respuesta |
 | `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 |

docs/modular-system.md

@@ -89,6 +89,28 @@ Use `<set>` tag to create variables from queries:
 <set :featured="'productos' | get({destacado: 1}, 'orden ASC', 3)"></set>
 ```
 
+### Header, footer, and site-wide style/JS — NOT regular files
+
+`template/estandar/modulos/custom-header-twig/index-base.tpl` and the equivalent `custom-footer-twig`
+one are **not editable as files** — `acai-write`/`acai-line-replace` reject them with
+`"Forbidden path: ... es un artefacto generado del layout global"`. They're special general sections
+(the header/footer of the **entire site**). The `.tpl` on disk is only a generated copy for fast reading
+(`acai-view` works fine on it), but the real source lives in `layout.json` and is edited with the
+`get_layout_field`/`set_layout_field` MCP tools (see
+[docs/mcp-tools-reference.md](mcp-tools-reference.md)):
+
+- `field: 'header'` / `field: 'footer'` — the header/footer templates themselves.
+- `field: 'style'` — global CSS for the whole site.
+- `field: 'javascript'` — global JS for the whole site (delegated listeners shared by every page live
+  here, not in any `.js` file in the repo — a `grep` of the repo for "how does X work in the header"
+  can find nothing even though X works fine in production).
+
+Workflow for a header/footer/global-CSS/global-JS change: `get_layout_field({field: '...'})` → edit the
+**full** string (there's no line-replace for this — `set_layout_field` is a destructive full-content
+replace) → `set_layout_field({field: '...', content: ...})`. The response includes `compile_ok` —
+verify it, same as any other write-op (see the reliability warning in
+[docs/mcp-tools-reference.md](mcp-tools-reference.md)).
+
 
 ## Repeatable Content (multiv2)