ajustes en docs generales

docs/06-hooks-and-cmsapi.md

@@ -287,6 +287,21 @@ set_hook_middleware({
 - Crear el `.php` con `acai-write` **NO** activa middleware automáticamente — hay que llamar `set_hook_middleware` explícitamente.
 - Lee `get_hook_middleware` antes de modificar para no sobrescribir configuraciones existentes.
 
+### Auto-registro en `layout.json`
+
+Cuando creas, renombras o borras un hook global con las tools de archivos, el backend mantiene `layout.json["hooks"]` sincronizado **automáticamente** — no necesitas tocarlo a mano:
+
+| Acción del agente | Efecto en `layout.json["hooks"]` |
+|---|---|
+| `acai-write hooks/hooks.X.php` (fichero nuevo) | Añade entry con `endPoint: /hooks/X/`, `middleWare: []`, `entryParams: [{variable: entryVariable}]` |
+| `acai-write` sobre un hook existente | Sin cambios (se preserva `middleWare`, `entryParams`, etc.) |
+| `acai-delete hooks/hooks.X.php` | Quita la entry huérfana |
+| `acai-rename hooks/hooks.X.php → hooks.Y.php` | Quita la vieja + añade la nueva con defaults |
+
+**Implicación**: tras `acai-write` de un hook nuevo, ya está registrado. Si quieres que se ejecute como middleware (`["allurls"]` o records concretos), solo te falta `set_hook_middleware` para configurar ese campo. Para los hooks de módulo (`template/estandar/modulos/<id>/hook.php`) no hay registro en `layout.json` — se descubren por convención de path al ejecutar el módulo.
+
+**Nunca edites `layout.json` directamente** para gestionar hooks. Eso compite con el sync del backend y deja el fichero inconsistente.
+
 ## Schemas y formato de datos al insertar
 
 Antes de un `CmsApi::insert`/`update` o de un `create_or_update_record` desde MCP, consulta el schema (`get_table_schema`). Tipos de campo y formato esperado: