ajustes codex

docs/hooks-and-api.md

@@ -2,7 +2,29 @@
 
 ## Hooks
 
-Hooks son archivos PHP en `hooks/` que ejecutan lógica server-side. También pueden estar dentro de un módulo en `template/estandar/modulos/<module-id>/hook.php`.
+Hooks son archivos PHP que ejecutan lógica server-side. Pueden existir en dos sitios:
+- Hooks globales en `hooks/hooks.<hook-id>.php`
+- Hooks propios de módulo en `template/estandar/modulos/<module-id>/hook.php`
+
+### Tipos de hooks
+
+**1. Hook global**
+- Archivo: `hooks/hooks.<hook-id>.php`
+- Endpoint: `/hooks/<hook-id>/`
+- Úsalo cuando la lógica se reutiliza entre módulos, páginas o formularios
+
+**2. Hook propio de módulo**
+- Archivo: `template/estandar/modulos/<module-id>/hook.php`
+- Endpoint: `/hooks/<module-id>/`
+- Úsalo cuando la lógica pertenece solo a ese módulo
+
+Ejemplos:
+- `hooks/hooks.buscar_barcos.php` -> `/hooks/buscar_barcos/`
+- `template/estandar/modulos/hero_banner/hook.php` -> `/hooks/hero_banner/`
+
+Regla práctica:
+- Si el hook solo sirve a un módulo, créalo dentro del módulo
+- Si varias piezas del proyecto lo van a consumir, créalo como hook global
 
 ### Estructura de un Hook
 
@@ -34,6 +56,10 @@ No usar X-Hooks-Token en desarrollo local.
 
 ### Cómo Llamar Hooks
 
+La referencia siempre se hace con el endpoint `/hooks/<id>/`:
+- Para hooks globales, `<id>` es el nombre lógico del hook sin `hooks.` ni `.php`
+- Para hooks de módulo, `<id>` es el `module-id` de la carpeta del módulo
+
 **Desde HTML (recomendado para módulos):**
 ```html
 <hook result="myVar" endpoint="/hooks/module_id/" :param1="value1" :param2="'string'"></hook>
@@ -379,6 +405,9 @@ return [
 <p>Total: ${{ precio.total }}</p>
 ```
 
+En este ejemplo, el endpoint usa `calcular_precio` porque el archivo vive en:
+`template/estandar/modulos/calcular_precio/hook.php`
+
 ### Hook con Operaciones de BD
 
 ```php