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

docs/module-creation-guide.md

@@ -39,6 +39,9 @@ Each module lives in `template/estandar/modulos/<moduleId>/` with:
 
 1. **Read style reference** (steps above)
 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.
+   - If the server-side logic belongs only to that module, create `template/estandar/modulos/<module-id>/hook.php`
+   - If the logic should be reused across modules/pages, create a global hook in `hooks/hooks.<hook-id>.php`
+   - Inside the module, reference its own hook with `/hooks/<module-id>/`
 3. **Automatic compile** — Writing `index-base.tpl` automatically creates the generated template placeholders and triggers compilation. `compile_module` is only a manual recovery tool if you need to force a recompile without changing the file.
 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.