diff --git a/CLAUDE.md b/CLAUDE.md
index 50bdd85..b80df67 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -110,7 +110,7 @@ Do NOT modify web-base files — they are shared across all projects.
 
 - [docs/modular-system.md](docs/modular-system.md) — Modules, general sections, global variables
 - [docs/builder-fields.md](docs/builder-fields.md) — Builder field types, Acai attributes, c-form, components
-- [docs/twig-filters.md](docs/twig-filters.md) — Twig filters reference (get, hook, module, queryDB, etc.)
+- [docs/twig-reference.md](docs/twig-reference.md) — Twig reference: filters, operators, syntax, global variables
 - [docs/hooks-and-api.md](docs/hooks-and-api.md) — PHP hooks, CmsApi, CocoDB, record creation
 - [docs/css-js-conventions.md](docs/css-js-conventions.md) — CSS/JS/Vue 3, Tailwind, BEM, native components
 - [docs/quick-reference.md](docs/quick-reference.md) — Cheat sheet: domain rules, field types, filters
diff --git a/docs/hooks-and-api.md b/docs/hooks-and-api.md
index 6f5b66c..f35cdca 100644
--- a/docs/hooks-and-api.md
+++ b/docs/hooks-and-api.md
@@ -56,34 +56,51 @@ El `.htaccess` de Acai añade `tipo=barra` a cada request. Si envías `tipo` com
 
 **Usar nombres alternativos:** `account_type`, `user_tipo`, `record_tipo`, etc.
 
-#### Módulos fantasma interceptan hooks
-Si `save_module` crea un directorio `modulos/auth_signup/hook.php`, este intercepta la URL `/hooks/auth_signup/` porque `addModulesHooksToLayout()` se ejecuta ANTES que `addFilesHooksToLayout()`.
+#### Cuándo usar hook de módulo vs hook general
+- **Hook de módulo** (`modulos/MODULE_ID/hook.php`): cuando el hook solo lo usa ese módulo. Ej: un módulo `calculadora` con su propio `hook.php`.
+- **Hook general** (`hooks/hooks.{nombre}.php`): cuando la lógica se usa desde varias partes del sitio (login, carrito, etc.).
 
-**Regla:** Nunca crear un directorio en `modulos/` solo para tener un hook. Para lógica server-side, usar siempre hooks generales en `hooks/hooks.{nombre}.php`. Si aparecen módulos fantasma por accidente, borrar el directorio.
+Nunca crear un directorio en `modulos/` **solo** para tener un hook sin módulo visual. Si `save_module` crea un módulo fantasma (ej: `modulos/auth_signup/`), este intercepta `/hooks/auth_signup/` porque `addModulesHooksToLayout()` se ejecuta ANTES que `addFilesHooksToLayout()`. Si aparecen fantasmas, borrar el directorio.
 
 ### Cómo Llamar Hooks
 
-**Desde HTML (recomendado para módulos):**
+La URL del endpoint depende del tipo de hook:
+- **Hook de módulo:** `/modulos/MODULE_ID/hook.php` (se llama con el path del módulo)
+- **Hook general:** `/hooks/nombre/`
+
+#### Desde HTML (recomendado para módulos)
 ```html
-<hook result="myVar" endpoint="/hooks/module_id/" :param1="value1" :param2="'string'"></hook>
+<!-- Hook de módulo -->
+<hook result="myVar" endpoint="/modulos/calculadora/hook.php" :param1="value1"></hook>
+
+<!-- Hook general -->
+<hook result="myVar" endpoint="/hooks/auth_login/" :param1="value1"></hook>
 <p>{{ myVar.message }}</p>
 ```
 
-**Desde Twig:**
+#### Desde Twig
 ```twig
-{% set resultado = 'hooks/mimodulo/' | hook({param1: 100, param2: 'texto'}) %}
-<p>{{ resultado.message }}</p>
+{# Hook de módulo #}
+{% set resultado = 'modulos/calculadora/hook.php' | hook({param1: 100}) %}
+
+{# Hook general #}
+{% set resultado = 'hooks/auth_login/' | hook({param1: 100}) %}
 ```
 
-**Desde JavaScript:** (ver [CmsApi JS](#cmsapi-javascript--client-side) para callback + Promise)
+#### Desde JavaScript
+(ver [CmsApi JS](#cmsapi-javascript--client-side) para callback + Promise)
 ```js
-CmsApi.hook('/hooks/mimodulo/', {param1: 100, param2: 'texto'}).then(res => console.log(res));
+// Hook de módulo
+CmsApi.hook('/modulos/calculadora/hook.php', {param1: 100}).then(res => console.log(res));
+
+// Hook general
+CmsApi.hook('/hooks/auth_login/', {param1: 100}).then(res => console.log(res));
 ```
 
-**Desde otro Hook PHP:**
+#### Desde otro Hook PHP
 ```php
 <?php
-$result = hook("/hooks/mimodulo/", ["param1" => 100, "param2" => "texto"]);
+$result = hook("/hooks/auth_login/", ["param1" => 100]);
 $mensaje = $result["message"];
 ?>
 ```
@@ -188,7 +205,7 @@ CmsApi::delete('productos',
 
 - Nombres de tabla **sin** prefijo `cms_`
 - Primary key siempre es `num`, nunca `id`
-- Foreign keys: consultar siempre el schema (ver [Gotchas de BD](#gotchas-de-base-de-datos))
+- Foreign keys: consultar siempre el schema en `cms/data/schema/` (ver [Gotchas de BD](#gotchas-de-base-de-datos))
 - Upload fields: no se manejan via insert/update
 - Operadores: `=`, `!=`, `>`, `>=`, `<`, `<=`, `LIKE`, `IN`
 - **Traducción en PHP:** Usar `t_var()` para todo texto visible al usuario:
diff --git a/docs/modular-system.md b/docs/modular-system.md
index 216b6c3..c271329 100644
--- a/docs/modular-system.md
+++ b/docs/modular-system.md
@@ -14,6 +14,8 @@ Modules are the visual building blocks of Acai websites. Each module lives in `t
 ├── builder.json      # Compiled builder vars (auto-generated, do NOT edit)
 ├── style.css         # Module-scoped styles
 ├── script.js         # Module JavaScript
+├── hook.php          # Module hook (optional — only if this module needs server-side logic)
+├── assets/           # Vue components and other JS assets for this module
 └── minified/
     ├── script-{hash}.js   # JS minificado (servido al browser, do NOT edit)
     └── style-{hash}.css   # CSS minificado (servido al browser, do NOT edit)
@@ -48,13 +50,7 @@ Parameters are received as variables inside the included module.
 
 ### Global Variables
 
-| Variable | Description |
-|----------|-------------|
-| `section_id` | Unique ID per module instance (use for anchors, JS scoping) |
-| `interno` | `true` when viewing in CMS editor, `false` on public site |
-| `server.HTTP_HOST` | Current domain |
-| `loop.index` | 1-based iteration index (inside `c-for`) |
-| `loop.index is odd` / `loop.index is even` | For alternating layouts |
+See [twig-reference.md — Global Variables](twig-reference.md#global-variables) for the full list of variables available in all templates.
 
 
 ## General Sections
@@ -89,7 +85,7 @@ Use `<set>` tag to create variables from queries:
 
 ```html
 <set :categories="'categorias' | get()"></set>
-<set :featured="'productos' | get({destacado: 1}, 'orden ASC', 3)"></set>
+<set :featured="'productos' | get('destacado=1', 'orden ASC', 3)"></set>
 ```
 
 
diff --git a/docs/twig-filters.md b/docs/twig-reference.md
similarity index 86%
rename from docs/twig-filters.md
rename to docs/twig-reference.md
index 6382801..1aec816 100644
--- a/docs/twig-filters.md
+++ b/docs/twig-reference.md
@@ -1,6 +1,6 @@
-# Twig Filters Reference
+# Twig Reference
 
-Acai usa filtros Twig con sintaxis `|`. No usar funciones Twig — solo filtros.
+Referencia completa de filtros, operadores, sintaxis y variables globales disponibles en templates Acai. Solo filtros (con `|`), nunca funciones Twig.
 
 ## `get` — Consultar tabla de BD
 
@@ -207,3 +207,18 @@ En `c-if` usar `=` (simple). En `{% if %}` usar `==` (doble).
 2. **Upload fields son arrays:** `record.imagen[0].urlPath`, no `record.imagen`
 3. **Tablas sin prefijo `cms_`** en `get()`. Con prefijo en `queryDB()`
 4. **Concatenar con `~`:** `'stocks' | get('producto_num=' ~ producto.num)`
+
+---
+
+## Global Variables
+
+Variables disponibles en todos los templates (módulos y general sections):
+
+| Variable | Description |
+|----------|-------------|
+| `section_id` | Unique ID per module instance (use for anchors, JS scoping) |
+| `interno` | `true` when viewing in CMS editor, `false` on public site |
+| `server.HTTP_HOST` | Current domain |
+| `loop.index` | 1-based iteration index (inside `c-for`) |
+| `loop.index is odd` / `loop.index is even` | For alternating layouts |
+| `thisrecord` | Current record data (only in general sections) |