@gzl10/nexus-sdk 0.12.3 → 0.12.6

package/dist/index.d.ts

@@ -5,37 +5,37 @@ export { CookieOptions, NextFunction, Request, RequestHandler, Response, Router
 import { Logger } from 'pino';
 
 /**
- * Type guards y utilidades para EntityDefinitions
+ * Type guards and utilities for EntityDefinitions
  */
 
 /**
- * Entidades que persisten en BD local con tabla propia
- * Excluye: action, external, virtual, computed, single (usa tabla compartida)
+ * Entities that persist in the local DB with their own table.
+ * Excludes: action, external, virtual, computed, single (uses shared table).
  */
 type PersistentEntityDefinition = CollectionEntityDefinition | ReferenceEntityDefinition | EventEntityDefinition | ConfigEntityDefinition | TempEntityDefinition | ViewEntityDefinition;
 /**
- * Entidades sin persistencia local (read-only o sin BD)
+ * Entities without local persistence (read-only or without DB)
  */
 type NonPersistentEntityDefinition = ActionEntityDefinition | ExternalEntityDefinition | VirtualEntityDefinition | ComputedEntityDefinition;
 /**
- * Type guard para verificar si una entidad persiste en BD local con tabla propia
+ * Type guard to check whether an entity persists in the local DB with its own table
  */
 declare function isPersistentEntity(entity: EntityDefinition): entity is PersistentEntityDefinition;
 /**
- * Type guard para verificar si es un singleton (usa tabla compartida sys_settings)
+ * Type guard to check whether it is a singleton (uses shared sys_settings table)
  */
 declare function isSingletonEntity(entity: EntityDefinition): entity is SingleEntityDefinition;
 /**
- * Type guard para verificar si una entidad tiene tabla propia (para migraciones)
+ * Type guard to check whether an entity has its own table (for migrations)
  */
 declare function hasTable(entity: EntityDefinition): entity is PersistentEntityDefinition;
 /**
- * Obtiene el nombre de una entidad en PascalCase singular
+ * Gets an entity name in singular PascalCase.
  * 'cms_posts' → 'Post', 'rol_role_permissions' → 'RolePermission'
  */
 declare function getEntityName(entity: EntityDefinition): string;
 /**
- * Obtiene el subject CASL de una entidad
+ * Gets the CASL subject for an entity
  */
 declare function getEntitySubject(entity: PersistentEntityDefinition): string;
 
@@ -47,57 +47,59 @@ declare function getEntitySubject(entity: PersistentEntityDefinition): string;
  * depending on the full @gzl10/nexus-backend package.
  */
 /**
- * Unión discriminada de todos los tipos de entidad
+ * Discriminated union of all entity types
  *
- * | Type       | Persistencia | CRUD            | Uso principal                    |
- * |------------|--------------|-----------------|----------------------------------|
- * | collection | Sí (BD)      | Completo        | Datos de negocio (users, posts)  |
- * | single     | Sí (BD)      | Update/Read     | Config global (site_config)      |
- * | external   | No           | Read            | Datos externos (stripe_customers)|
- * | virtual    | No           | Read            | Orquestación (unified_customers) |
- * | computed   | No/opcional  | Read            | KPIs, estadísticas               |
- * | view       | Sí/virtual   | Read            | Lectura optimizada (projections) |
- * | reference  | Sí           | Read (admin)    | Catálogos (countries, currencies)|
- * | config     | Sí           | Update/Read     | Config por módulo                |
- * | event      | Sí           | Append          | Auditoría (audit_logs)           |
- * | temp       | No (TTL)     | Read/Write      | Cache, sesiones (otp_codes)      |
- * | action     | No           | Execute         | Operaciones, workflows           |
+ * | Type       | Persistence | CRUD            | Primary use                      |
+ * |------------|-------------|-----------------|----------------------------------|
+ * | collection | Yes (DB)    | Full            | Business data (users, posts)     |
+ * | single     | Yes (DB)    | Update/Read     | Global config (site_config)      |
+ * | external   | No          | Read            | External data (stripe_customers) |
+ * | virtual    | No          | Read            | Orchestration (unified_customers)|
+ * | computed   | No/optional | Read            | KPIs, stats                      |
+ * | view       | Yes/virtual | Read            | Optimized reads (projections)    |
+ * | reference  | Yes         | Read (admin)    | Catalogs (countries, currencies) |
+ * | config     | Yes         | Update/Read     | Per-module config                |
+ * | event      | Yes         | Append          | Audit logs (audit_logs)          |
+ * | temp       | No (TTL)    | Read/Write      | Cache, sessions (otp_codes)      |
+ * | action     | No          | Execute         | Operations, workflows            |
  */
 
 type KnexCreateTableBuilder = Knex.CreateTableBuilder;
 type KnexAlterTableBuilder = Knex.AlterTableBuilder;
 type KnexTransaction = Knex.Transaction;
 /**
- * Request autenticado con usuario y abilities CASL
- * El backend especializa TUser y TAbility con tipos concretos
+ * Base authenticated request with user and CASL abilities (generic).
+ * Use AuthRequest for the pre-typed version.
  */
-interface AuthRequest<TUser = unknown, TAbility = unknown> extends Request {
+interface BaseAuthRequest<TUser = unknown, TAbility = unknown> extends Request {
     user: TUser;
     ability: TAbility;
 }
 /**
- * Usuario base sin contraseña para uso en plugins
- * Usado para tipar relaciones con usuarios (ej: author, created_by)
+ * Base user without a password for plugin use.
+ * Used to type relations with users (e.g., author, created_by).
+ * Note: Multi-role support - roles are loaded via user_roles pivot table.
  */
 interface BaseUser {
     id: string;
     name: string;
     email: string;
-    role_id: string;
     created_at: Date;
     updated_at: Date;
     created_by: string | null;
     updated_by: string | null;
+    /** Extensibility: allows custom user properties */
+    [key: string]: unknown;
 }
 /**
- * Parámetros de paginación para queries
+ * Pagination parameters for queries
  */
 interface PaginationParams {
     page: number;
     limit: number;
 }
 /**
- * Resultado paginado genérico
+ * Generic paginated result
  */
 interface PaginatedResult<T> {
     items: T[];
@@ -108,183 +110,603 @@ interface PaginatedResult<T> {
     hasNext: boolean;
 }
 /**
- * Tipos de columna en base de datos
+ * Standard validation error detail for API responses
+ */
+interface ValidationDetail {
+    path: string;
+    message: string;
+}
+/**
+ * Localized string supporting multiple languages.
+ * Can be a simple string (single language) or object with language codes.
+ *
+ * @example
+ * // Simple string (backward compatible)
+ * label: 'Users'
+ *
+ * // Multi-language object
+ * label: { en: 'Users', es: 'Usuarios' }
+ */
+type LocalizedString = string | Record<string, string>;
+/**
+ * Resolves a LocalizedString to the appropriate language.
+ * Falls back to 'en', then first available, then empty string.
+ *
+ * @param value - The localized string to resolve
+ * @param locale - The target locale (e.g., 'en', 'es')
+ * @returns The resolved string for the given locale
  */
-type DbType = 'string' | 'text' | 'integer' | 'decimal' | 'boolean' | 'date' | 'datetime' | 'json' | 'uuid';
+declare function resolveLocalized(value: LocalizedString | undefined, locale: string): string;
 /**
- * Tipos de input en UI
+ * Gets the appropriate label based on count (pluralization).
+ * Returns labelPlural for count !== 1, label otherwise.
+ *
+ * @param label - Singular form
+ * @param labelPlural - Plural form (optional, defaults to label)
+ * @param count - The count to determine singular/plural
+ * @param locale - The target locale
+ * @returns The resolved string for the given count and locale
  */
-type InputType = 'text' | 'email' | 'password' | 'url' | 'tel' | 'number' | 'decimal' | 'textarea' | 'markdown' | 'json' | 'select' | 'multiselect' | 'tags' | 'checkbox' | 'switch' | 'date' | 'datetime' | 'file' | 'fileArray' | 'image' | 'imageArray' | 'hidden';
+declare function getCountLabel(label: LocalizedString | undefined, labelPlural: LocalizedString | undefined, count: number, locale: string): string;
 /**
- * Configuración de base de datos para un campo
+ * Database column types for Knex migrations.
+ *
+ * Maps to SQL column types:
+ * - `string` → VARCHAR(size) - Use with `db.size` for length
+ * - `text` → TEXT - Unlimited length text
+ * - `integer` → INTEGER - Whole numbers
+ * - `decimal` → DECIMAL(p,s) - Use with `db.precision` for scale
+ * - `boolean` → BOOLEAN - True/false values
+ * - `date` → DATE - Date without time
+ * - `datetime` → DATETIME/TIMESTAMP - Date with time
+ * - `json` → JSON/JSONB - Structured data (use for LocalizedString)
+ * - `uuid` → UUID - Universally unique identifier
+ * - `array` → Virtual only - No database column generated
+ *
+ * @example
+ * ```typescript
+ * db: { type: 'string', size: 100 }      // VARCHAR(100)
+ * db: { type: 'decimal', precision: [10, 2] } // DECIMAL(10,2)
+ * db: { type: 'json', nullable: false }  // JSON NOT NULL
+ * ```
+ */
+type DbType = 'string' | 'text' | 'integer' | 'decimal' | 'boolean' | 'date' | 'datetime' | 'json' | 'uuid' | 'array';
+/**
+ * UI input types that determine which form component renders.
+ *
+ * **Text inputs:**
+ * - `text` → NInput - Single line text
+ * - `email` → NInput with email validation
+ * - `password` → NInput with password mask
+ * - `url` → NInput with URL validation
+ * - `tel` → NInput for phone numbers
+ *
+ * **Numeric inputs:**
+ * - `number` → NInputNumber - Integer values
+ * - `decimal` → NInputNumber with decimal precision
+ *
+ * **Rich text:**
+ * - `textarea` → NInput multiline
+ * - `markdown` → MarkdownInput with preview
+ * - `json` → JsonInput with syntax highlighting
+ *
+ * **Selection:**
+ * - `select` → NSelect - Single selection dropdown
+ * - `multiselect` → NSelect with multiple - Multiple selection
+ * - `transfer` → NTransfer - Dual list selection
+ * - `tags` → NSelect with tags - Free-form tags input
+ *
+ * **Boolean:**
+ * - `checkbox` → NCheckbox
+ * - `switch` → NSwitch - Toggle switch
+ *
+ * **Date/Time:**
+ * - `date` → NDatePicker - Date only
+ * - `datetime` → NDatePicker with time
+ *
+ * **Files:**
+ * - `file` → FileInput - Single file upload
+ * - `fileArray` → FileInput multiple - Multiple files
+ * - `image` → ImageInput - Single image with preview
+ * - `imageArray` → ImageInput multiple - Image gallery
+ *
+ * **Other:**
+ * - `icon` → IconPicker - Icon selection from library
+ *
+ * @see {@link FieldOptions} for select/multiselect configuration
+ * @see {@link FieldStorageConfig} for file/image configuration
+ */
+type InputType = 'text' | 'email' | 'password' | 'url' | 'tel' | 'number' | 'decimal' | 'textarea' | 'markdown' | 'json' | 'select' | 'multiselect' | 'transfer' | 'tags' | 'checkbox' | 'switch' | 'date' | 'datetime' | 'file' | 'fileArray' | 'image' | 'imageArray' | 'icon';
+/**
+ * Database column configuration for Knex migrations.
+ *
+ * @example
+ * ```typescript
+ * // String with max length
+ * db: { type: 'string', size: 100, nullable: false }
+ *
+ * // Decimal with precision
+ * db: { type: 'decimal', precision: [10, 2] }
+ *
+ * // UUID with auto-generation
+ * db: { type: 'uuid', defaultFn: 'uuid' }
+ *
+ * // Virtual field (no column in DB)
+ * db: { type: 'array', virtual: true }
+ * ```
  */
 interface FieldDbConfig {
+    /** Column type for the database */
     type: DbType;
+    /** If true, no database column is created (for computed/virtual fields like role_ids) */
+    virtual?: boolean;
+    /** String length for VARCHAR columns */
     size?: number;
+    /** Precision and scale for DECIMAL: [precision, scale] e.g., [10, 2] for DECIMAL(10,2) */
     precision?: [number, number];
-    nullable: boolean;
+    /** Allow NULL values. Inferred from `required` if not specified */
+    nullable?: boolean;
+    /** Create unique constraint on this column */
     unique?: boolean;
+    /** Static default value for the column */
     default?: unknown;
+    /** Database function for default value: 'now' for timestamps, 'uuid' for auto-generated UUIDs */
     defaultFn?: 'now' | 'uuid';
+    /** Create index on this column for faster queries */
     index?: boolean;
 }
 /**
- * Configuración de relación (Foreign Key)
+ * Foreign key relationship configuration.
+ *
+ * Defines how this field references another table in the database.
+ * Used for both migrations (FK constraint) and UI (dropdown options).
+ *
+ * @example
+ * ```typescript
+ * // Basic relation to users table
+ * relation: { table: 'users' }
+ *
+ * // With cascade delete
+ * relation: { table: 'categories', onDelete: 'CASCADE' }
+ *
+ * // Reference non-id column
+ * relation: { table: 'countries', column: 'code' }
+ * ```
  */
 interface FieldRelation {
+    /** Target table name */
     table: string;
+    /** Target column name (default: 'id') */
     column?: string;
+    /** Action when referenced row is deleted */
     onDelete?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+    /** Action when referenced row's key is updated */
     onUpdate?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
 }
 /**
- * Configuración de validación para un campo
+ * Validation rules for runtime and form validation.
+ *
+ * Used to generate Zod schemas for API validation and
+ * form validation rules in the UI.
+ *
+ * @example
+ * ```typescript
+ * // String length constraints
+ * validation: { min: 1, max: 200 }
+ *
+ * // Email format
+ * validation: { format: 'email' }
+ *
+ * // Regex pattern
+ * validation: { pattern: '^[a-z0-9-]+$' }
+ *
+ * // Enum values
+ * validation: { enum: ['draft', 'published', 'archived'] }
+ * ```
  */
 interface FieldValidationConfig {
-    required?: boolean;
+    /** Minimum value (numbers) or minimum length (strings) */
     min?: number;
+    /** Maximum value (numbers) or maximum length (strings) */
     max?: number;
+    /** Regular expression pattern for validation */
     pattern?: string;
+    /** Predefined format validation */
     format?: 'email' | 'url' | 'uuid' | 'slug';
+    /** Allowed values (creates enum constraint) */
     enum?: string[];
 }
 /**
- * Opciones para campos select/relaciones
+ * Configuration for select, multiselect, and dropdown fields.
+ *
+ * Options can be loaded from:
+ * - Static array defined in the field
+ * - Dynamic endpoint (API call)
+ * - Related entity via `relation` config
+ *
+ * @example
+ * ```typescript
+ * // Static options
+ * options: {
+ *   static: [
+ *     { value: 'draft', label: { en: 'Draft', es: 'Borrador' } },
+ *     { value: 'published', label: { en: 'Published', es: 'Publicado' } }
+ *   ]
+ * }
+ *
+ * // Dynamic from API
+ * options: {
+ *   endpoint: '/api/categories',
+ *   valueField: 'id',
+ *   labelField: 'name'
+ * }
+ *
+ * // Allow creating new options (combobox)
+ * options: { allowCreate: true, endpoint: '/api/tags' }
+ * ```
  */
 interface FieldOptions {
+    /** API endpoint for dynamic options (GET request) */
     endpoint?: string;
+    /** Field to use as option value (default: 'id') */
     valueField?: string;
+    /** Field to use as option label (default: 'name') */
     labelField?: string;
+    /** Static list of options */
     static?: Array<{
         value: string;
-        label: string;
+        label: LocalizedString;
     }>;
+    /** Allow creating new options on-the-fly (renders combobox) */
     allowCreate?: boolean;
 }
 /**
- * Restricciones de acceso CASL para un campo
- */
-interface FieldCaslAccess {
-    /** Roles que pueden leer este campo (vacío = todos, null = nadie excepto ADMIN) */
-    readRoles?: string[];
-    /** Roles que pueden escribir este campo (vacío = todos, null = nadie excepto ADMIN) */
-    writeRoles?: string[];
-}
-/**
- * Configuración de storage para campos file/image
+ * Storage configuration for file and image upload fields.
+ *
+ * Controls upload behavior, file validation, and image processing.
+ *
+ * @example
+ * ```typescript
+ * // Image with thumbnails
+ * storage: {
+ *   accept: 'image/*',
+ *   maxSize: 5 * 1024 * 1024, // 5MB
+ *   folder: 'avatars',
+ *   thumbnails: [{ width: 100, height: 100 }, { width: 300, height: 300 }]
+ * }
+ *
+ * // PDF documents with deduplication
+ * storage: {
+ *   accept: 'application/pdf',
+ *   maxSize: 20 * 1024 * 1024, // 20MB
+ *   folder: 'documents',
+ *   dedupe: true
+ * }
+ *
+ * // Multiple images
+ * storage: {
+ *   accept: 'image/*',
+ *   maxFiles: 10,
+ *   folder: 'gallery'
+ * }
+ * ```
  */
 interface FieldStorageConfig {
-    /** Tipos MIME aceptados (ej: 'image/*', 'application/pdf') */
+    /** Accepted MIME types (e.g., 'image/*', 'application/pdf', 'image/png,image/jpeg') */
     accept?: string;
-    /** Tamaño máximo en bytes (default: 10MB) */
+    /** Maximum file size in bytes (default: 10MB = 10485760) */
     maxSize?: number;
-    /** Número máximo de archivos para tipos array */
+    /** Maximum number of files for array types (fileArray, imageArray) */
     maxFiles?: number;
-    /** Carpeta/prefijo en storage (ej: 'avatars', 'documents') */
+    /** Folder/prefix in storage bucket (e.g., 'avatars', 'documents/contracts') */
     folder?: string;
-    /** Tamaños de thumbnails a generar para imágenes */
+    /** Thumbnail sizes to auto-generate for images. Creates resized versions on upload */
     thumbnails?: Array<{
         width: number;
         height: number;
     }>;
+    /** Enable SHA256 hash deduplication - if identical file exists, reuse it instead of uploading again */
+    dedupe?: boolean;
 }
 /**
- * Metadata del campo
+ * Field metadata for UI behavior and data operations.
+ *
+ * Controls how the field behaves in tables, forms, exports, and searches.
+ *
+ * @example
+ * ```typescript
+ * // Searchable and sortable title field
+ * meta: { searchable: true, sortable: true, exportable: true }
+ *
+ * // Audit field (auto-populated)
+ * meta: { auditField: 'created_by', showInForm: false }
+ *
+ * // Show only in edit form, not create
+ * meta: { showInForm: 'edit' }
+ *
+ * // Hidden from tables but visible in forms
+ * meta: { showInDisplay: false }
+ * ```
  */
 interface FieldMeta {
+    /** Enable sorting by this field in table columns */
     sortable?: boolean;
+    /** Include this field in search/filter operations */
     searchable?: boolean;
+    /** Include this field in CSV/Excel exports */
     exportable?: boolean;
+    /** Mark as audit field (auto-populated with user ID on create/update) */
     auditField?: 'created_by' | 'updated_by';
-    /** Restricciones de acceso CASL para este campo */
-    casl?: FieldCaslAccess;
+    /** Show in display components (Table, List, Masonry). Default: true */
+    showInDisplay?: boolean;
+    /** Show in forms. Use 'create'/'edit' for conditional display. Default: true */
+    showInForm?: boolean | 'create' | 'edit';
 }
 /**
- * Definición completa de un campo
+ * Conditional boolean - can be static or evaluated at runtime based on record
+ * Functions are evaluated in backend before serializing to DTO
+ */
+type ConditionalBoolean = boolean | ((record: Record<string, unknown>) => boolean);
+/**
+ * Complete field definition for entity fields.
+ *
+ * This is the core building block for defining entity schemas in Nexus.
+ * Contains all the information needed for:
+ * - **UI**: Form inputs, table columns, list displays
+ * - **Database**: Knex migrations, column types, constraints
+ * - **Validation**: Zod schemas, runtime validation rules
  *
- * Contiene toda la información necesaria para:
- * - UI: formularios, listas
- * - BD: migraciones Knex
- * - Validación: schemas Zod
+ * @example
+ * ```typescript
+ * const titleField: FieldDefinition = {
+ *   name: 'title',
+ *   label: { en: 'Title', es: 'Título' },
+ *   input: 'text',
+ *   required: true,
+ *   db: { type: 'string', nullable: false },
+ *   validation: { min: 1, max: 200 }
+ * }
+ * ```
+ *
+ * @see {@link FieldDefinitionDTO} for the serializable API response version
+ * @see {@link EntityDefinition} for the parent entity structure
  */
 interface FieldDefinition {
+    /**
+     * Field identifier used as the database column name.
+     * Should be snake_case for database compatibility.
+     * @example 'title', 'created_at', 'author_id'
+     */
     name: string;
-    label: string;
+    /**
+     * Human-readable label displayed in forms, tables, and lists.
+     * Supports localization with `{ en: '...', es: '...' }` format.
+     */
+    label: LocalizedString;
+    /**
+     * Input type that determines which UI component renders this field.
+     * @see {@link InputType} for all available input types
+     */
     input: InputType;
-    placeholder?: string;
-    hint?: string;
-    hidden?: boolean;
-    disabled?: boolean;
+    /**
+     * Placeholder text shown in empty input fields.
+     * Supports localization.
+     */
+    placeholder?: LocalizedString;
+    /**
+     * Help text displayed below the input field.
+     * Use for additional guidance or format hints.
+     */
+    hint?: LocalizedString;
+    /**
+     * Controls field visibility in the UI.
+     * - `true`: Always hidden
+     * - `false`: Always visible
+     * - `(record) => boolean`: Dynamic based on record values
+     * @example hidden: (record) => record.type === 'draft'
+     */
+    hidden?: ConditionalBoolean;
+    /**
+     * Controls whether the field is read-only in forms.
+     * - `true`: Always disabled
+     * - `false`: Always editable
+     * - `(record) => boolean`: Dynamic based on record values
+     * @example disabled: (record) => record.status === 'published'
+     */
+    disabled?: ConditionalBoolean;
+    /**
+     * Marks the field as required for form validation.
+     * - `true`: Always required
+     * - `false`: Always optional
+     * - `(record) => boolean`: Dynamic based on record values
+     * @example required: (record) => record.is_featured === true
+     */
+    required?: ConditionalBoolean;
+    /**
+     * Default value used when creating new records.
+     * Type should match the field's expected data type.
+     */
+    defaultValue?: unknown;
+    /**
+     * Database column configuration for Knex migrations.
+     * Optional for virtual fields, actions, or external data sources.
+     * @see {@link FieldDbConfig}
+     */
     db?: FieldDbConfig;
+    /**
+     * Foreign key relationship configuration.
+     * Defines how this field relates to another entity's table.
+     * @see {@link FieldRelation}
+     */
     relation?: FieldRelation;
+    /**
+     * Validation rules applied during form submission and API requests.
+     * Used to generate Zod schemas for runtime validation.
+     * @see {@link FieldValidationConfig}
+     */
     validation?: FieldValidationConfig;
+    /**
+     * Configuration for select inputs and relationship dropdowns.
+     * Defines static options or dynamic data sources.
+     * @see {@link FieldOptions}
+     */
     options?: FieldOptions;
+    /**
+     * Storage configuration for file and image inputs.
+     * Defines upload constraints, folders, and thumbnail generation.
+     * @see {@link FieldStorageConfig}
+     */
     storage?: FieldStorageConfig;
+    /**
+     * Additional metadata for categorization and UI organization.
+     * @see {@link FieldMeta}
+     */
     meta?: FieldMeta;
+    /**
+     * Additional props passed directly to the form input component.
+     * Allows customization of Naive UI component behavior.
+     * @example inputProps: { rows: 5, showCount: true }
+     */
+    inputProps?: Record<string, unknown>;
+    /**
+     * Additional props passed to display components (table columns, list items).
+     * Use `order` prop to control field position in tables.
+     * @example displayProps: { order: 1, width: 200 }
+     */
+    displayProps?: Record<string, unknown>;
 }
 /**
- * Índice compuesto de tabla
+ * Composite table index definition for database migrations.
+ *
+ * Creates multi-column indexes for optimized queries.
+ *
+ * @example
+ * ```typescript
+ * // Composite index for frequent queries
+ * indexes: [{ columns: ['tenant_id', 'created_at'] }]
+ *
+ * // Unique constraint on multiple columns
+ * indexes: [{ columns: ['user_id', 'role_id'], unique: true }]
+ * ```
  */
 interface EntityIndex {
+    /** Column names to include in the composite index */
     columns: string[];
+    /** Create unique constraint on the column combination */
     unique?: boolean;
 }
 /**
- * Acciones CASL estándar
+ * Standard CASL authorization actions.
+ *
+ * - `manage` - Full access (superuser wildcard, includes all actions)
+ * - `create` - Create new records
+ * - `read` - Read/view records
+ * - `update` - Modify existing records
+ * - `delete` - Remove records
+ * - `execute` - Execute actions/operations on records
+ *
+ * @see {@link RolePermission} for role-based permission configuration
+ * @see https://casl.js.org/v6/en/guide/intro
  */
 type CaslAction = 'manage' | 'create' | 'read' | 'update' | 'delete' | 'execute';
 /**
- * Condición de ownership para permisos
- * El campo de la entidad que referencia al usuario
+ * Ownership condition for CASL permissions.
+ *
+ * Automatically generates conditions that restrict access to records
+ * owned by the current user.
+ *
+ * @example
+ * ```typescript
+ * // Users can only edit their own posts
+ * ownership: { field: 'author_id' }
+ * // Generates: { author_id: user.id }
+ *
+ * // Match against user's email instead of id
+ * ownership: { field: 'owner_email', userField: 'email' }
+ * // Generates: { owner_email: user.email }
+ * ```
  */
 interface OwnershipCondition {
-    /** Campo que contiene el ID del propietario (ej: 'author_id', 'created_by') */
+    /** Entity field that contains the owner reference (e.g., 'author_id', 'created_by') */
     field: string;
-    /** Variable del usuario a comparar (default: 'id') */
+    /** User property to compare against (default: 'id'). Use 'email' for email-based ownership */
     userField?: string;
 }
 /**
- * Permiso CASL para un rol específico
+ * CASL permission definition for a specific role.
+ *
+ * Defines what actions a role can perform on an entity,
+ * optionally with conditions and field restrictions.
+ *
+ * @example
+ * ```typescript
+ * // Editor can read and update, but not delete
+ * EDITOR: {
+ *   actions: ['read', 'update'],
+ *   fields: ['title', 'content', 'status']
+ * }
+ *
+ * // Viewer can only read published items
+ * VIEWER: {
+ *   actions: ['read'],
+ *   conditions: { status: 'published' }
+ * }
+ *
+ * // Deny delete for everyone except admin
+ * EDITOR: {
+ *   actions: ['delete'],
+ *   inverted: true
+ * }
+ * ```
  */
 interface RolePermission {
-    /** Acciones permitidas */
+    /** Actions this role can perform on the entity */
     actions: CaslAction[];
-    /** Condiciones (ownership, status, etc.) */
+    /** CASL conditions to filter which records the permission applies to */
     conditions?: Record<string, unknown>;
-    /** Campos permitidos (null = todos) */
+    /** Restrict permission to specific fields. null = all fields allowed */
     fields?: string[] | null;
-    /** Invertir permiso (cannot en lugar de can) */
+    /** If true, this is a denial rule (cannot) instead of allow (can) */
     inverted?: boolean;
 }
 /**
- * Configuración de autorización CASL para una entidad
+ * CASL authorization configuration for an entity.
+ *
+ * Defines role-based access control (RBAC) using CASL.
+ * Permissions are evaluated at runtime for each request.
+ *
+ * @example
+ * ```typescript
+ * casl: {
+ *   subject: 'BlogPost',
+ *   ownership: { field: 'author_id' },
+ *   permissions: {
+ *     ADMIN: { actions: ['manage'] },
+ *     EDITOR: { actions: ['read', 'create', 'update'] },
+ *     AUTHOR: { actions: ['read', 'update', 'delete'] }, // with ownership
+ *     VIEWER: { actions: ['read'], conditions: { status: 'published' } }
+ *   },
+ *   sensitiveFields: ['internal_notes', 'analytics']
+ * }
+ * ```
+ *
+ * @see https://casl.js.org/v6/en/guide/intro
  */
 interface EntityCaslConfig {
-    /**
-     * Subject CASL (default: inferido de table → 'cms_posts' → 'CmsPost')
-     */
+    /** CASL subject name. Default: inferred from table (e.g., 'cms_posts' → 'CmsPost') */
     subject?: string;
-    /**
-     * Campo de ownership para conditions automáticas
-     * Si se define, se genera condition { [field]: '${user.id}' }
-     */
+    /** Ownership configuration for automatic user-based filtering */
     ownership?: OwnershipCondition;
-    /**
-     * Permisos por rol
-     * Las keys son nombres de roles (ADMIN, EDITOR, VIEWER, etc.)
-     */
+    /** Role-based permissions. Keys are role names (ADMIN, EDITOR, VIEWER, etc.) */
     permissions?: Record<string, RolePermission>;
-    /**
-     * Campos sensibles que requieren permiso especial
-     * Se excluyen de 'read' para roles sin acceso explícito
-     */
+    /** Fields excluded from 'read' permission unless explicitly granted. Use for PII or internal data */
     sensitiveFields?: string[];
 }
 /**
- * Action vinculada a un registro de la entidad
- * Define operaciones que actúan sobre registros existentes
+ * Action linked to an entity record.
+ * Defines operations that act on existing records.
  *
- * Ruta generada: GET|POST /{entityRoutePrefix}/{key}/:id
+ * Generated route: GET|POST /{entityRoutePrefix}/{key}/:id
  *
  * @example
  * ```typescript
@@ -296,493 +718,920 @@ interface EntityCaslConfig {
  *   select: ['id', 'filename', 'mimetype'],
  *   handler: async (ctx, input, _req, res) => {
  *     const { _record: file, _authUserId } = input
- *     // file y _authUserId vienen inyectados automáticamente
+ *     // file and _authUserId are injected automatically
  *   }
  * }]
  * ```
  */
 interface EntityAction {
-    /** Key única para la ruta (ej: 'download' → /download/:id) */
+    /** Unique key for the route (e.g., 'download' → /download/:id) */
     key: string;
-    /** Label para UI */
-    label: string;
-    /** Icono Iconify (default: 'mdi:play') */
+    /** Label for the UI */
+    label: LocalizedString;
+    /** Iconify icon (default: 'mdi:play') */
     icon?: string;
-    /** Método HTTP (default: 'POST') */
-    method?: 'GET' | 'POST';
-    /** Campos a seleccionar del registro (default: todos) */
+    /** HTTP method (default: 'POST') */
+    method?: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+    /** Fields to select from the record (default: all) */
     select?: string[];
-    /** Schema de validación del body (opcional) */
+    /** Body validation schema (optional) */
     inputSchema?: ValidationSchema;
-    /** Schema del output (documentación) */
+    /** Output schema (documentation) */
     outputSchema?: ValidationSchema;
-    /** Middleware custom (ej: multer) */
+    /** Custom middleware (e.g., multer) */
     middleware?: (ctx: ModuleContext) => RequestHandler | RequestHandler[];
     /**
-     * Handler - recibe _record y _authUserId automáticamente
-     * @param ctx - Contexto del módulo
-     * @param input - Body validado + _record + _authUserId
+     * Handler - receives _record and _authUserId automatically.
+     * @param ctx - Module context
+     * @param input - Validated body + _record + _authUserId
      * @param req - Express Request
-     * @param res - Express Response (para streams, headers custom)
+     * @param res - Express Response (for streams, custom headers)
      */
     handler: (ctx: ModuleContext, input: unknown, req?: Request, res?: Response) => Promise<unknown>;
     /**
-     * Permisos CASL específicos para esta action
-     * Si no se define, hereda los permisos de la entidad padre
+     * Skip authentication for this action.
+     * Use for public endpoints like thumbnails, previews, etc.
+     * @default false
+     */
+    skipAuth?: boolean;
+    /**
+     * CASL permissions specific to this action.
+     * If not defined, it inherits permissions from the parent entity.
+     * Ignored if skipAuth is true.
      */
     casl?: {
-        /** Action CASL (default: 'execute') */
+        /** CASL action (default: 'execute') */
         action?: string;
-        /** Conditions adicionales */
+        /** Additional conditions */
         conditions?: Record<string, unknown>;
     };
 }
 /**
- * Propiedades base compartidas por todas las EntityDefinition
+ * Base properties shared by all EntityDefinition types.
+ *
+ * @internal This interface is not exported directly. Use specific entity types instead.
+ * @see {@link CollectionEntityDefinition}
+ * @see {@link SingleEntityDefinition}
+ * @see {@link ReferenceEntityDefinition}
  */
 interface BaseEntityDefinition {
-    /** Nombre de tabla en BD (con prefijo: 'cms_posts') */
+    /** Database table name with module prefix (e.g., 'cms_posts', 'auth_users') */
     table: string;
-    /** Nombre para mostrar en UI */
-    label: string;
-    /** Definición de campos */
+    /** Display name for the UI (singular form) */
+    label: LocalizedString;
+    /** Display name for the UI (plural form, used in navigation menus and list headers) */
+    labelPlural?: LocalizedString;
+    /** Field definitions keyed by field name. See {@link FieldDefinition} */
     fields: Record<string, FieldDefinition>;
-    /** Autorización CASL */
+    /** CASL authorization configuration for role-based access control */
     casl?: EntityCaslConfig;
-    /** Prefijo de ruta para montar (default: inferido de table) */
+    /** API route prefix. Default: inferred from table name (e.g., 'cms_posts' → '/cms-posts') */
     routePrefix?: string;
-    /** Orden de visualización en UI (menor = primero, default: 999) */
+    /** UI sidebar ordering. Lower values appear first (default: 999) */
     order?: number;
+    /** UI display mode: 'table' for data grids, 'list' for cards, 'masonry' for image galleries */
+    displayMode?: DisplayMode;
+    /** If true, hides from UI sidebar but entity remains accessible via API */
+    hidden?: boolean;
 }
 /**
- * Entidad de colección - CRUD completo (users, posts, orders)
- * Default cuando no se especifica type
+ * Collection entity - the most common entity type with full CRUD operations.
+ *
+ * Use for business data like users, posts, orders, products, etc.
+ * This is the default type when `type` is not specified.
+ *
+ * @example
+ * ```typescript
+ * const posts: CollectionEntityDefinition = {
+ *   type: 'collection', // optional, default
+ *   table: 'cms_posts',
+ *   label: { en: 'Post', es: 'Publicación' },
+ *   labelField: 'title',
+ *   timestamps: true,
+ *   audit: true,
+ *   softDelete: true,
+ *   fields: { ... }
+ * }
+ * ```
  */
 interface CollectionEntityDefinition extends BaseEntityDefinition {
+    /** Entity type. Default: 'collection' */
     type?: 'collection';
-    /** Campo para mostrar en selects/referencias */
+    /** Field used as display label in dropdowns, references, and breadcrumbs (e.g., 'name', 'title') */
     labelField: string;
-    /** Añadir created_at, updated_at */
+    /** Auto-add created_at and updated_at timestamp columns */
     timestamps?: boolean;
-    /** Añadir created_by, updated_by */
+    /** Auto-add created_by and updated_by user reference columns */
     audit?: boolean;
-    /** Índices compuestos */
+    /** Composite database indexes for query optimization */
     indexes?: EntityIndex[];
-    /** Usar deleted_at en vez de DELETE físico */
+    /** Use soft delete (deleted_at column) instead of physical DELETE */
     softDelete?: boolean;
-    /** Actions vinculadas a registros de esta entidad */
+    /** Custom actions that operate on entity records (e.g., download, publish, archive) */
     actions?: EntityAction[];
+    /** Show "Create" button in UI. Set false for entities created only via API/actions */
+    allowCreate?: boolean;
+    /** Allow editing in UI. Set false for read-only display entities */
+    allowEdit?: boolean;
 }
 /**
- * Entidad singleton - Un solo registro en tabla compartida sys_settings
- * Usa key-value: key identifica el registro, value es JSON con la estructura de fields
+ * Singleton entity - stores a single record in the shared sys_settings table.
+ *
+ * Perfect for application-wide configuration like site settings, SMTP config,
+ * feature flags, etc. Data is stored as JSON in a key-value format.
  *
  * @example
- * // site_config singleton
- * { type: 'single', key: 'site_config', label: 'Site Config', fields: { siteName: {...}, logo: {...} } }
- * // Se guarda en sys_settings como: { key: 'site_config', value: { siteName: 'Mi App', logo: '...' } }
+ * ```typescript
+ * const siteConfig: SingleEntityDefinition = {
+ *   type: 'single',
+ *   key: 'site_config',
+ *   label: { en: 'Site Configuration', es: 'Configuración del Sitio' },
+ *   defaults: { siteName: 'My App', maintenanceMode: false },
+ *   fields: {
+ *     siteName: { name: 'siteName', label: 'Site Name', input: 'text', ... },
+ *     logo: { name: 'logo', label: 'Logo', input: 'image', ... }
+ *   }
+ * }
+ * // Stored in sys_settings: { key: 'site_config', value: '{"siteName":"My App","logo":"..."}' }
+ * ```
  */
 interface SingleEntityDefinition {
+    /** Entity type identifier */
     type: 'single';
-    /** Clave única en tabla sys_settings (ej: 'site_config', 'smtp_settings') */
+    /** Unique key in sys_settings table (e.g., 'site_config', 'smtp_settings', 'feature_flags') */
     key: string;
-    /** Nombre para mostrar en UI */
-    label: string;
-    /** Definición de campos (estructura del JSON value) */
+    /** Display name for the UI (singular form) */
+    label: LocalizedString;
+    /** Display name for the UI (plural form) */
+    labelPlural?: LocalizedString;
+    /** Field definitions describing the JSON structure */
     fields: Record<string, FieldDefinition>;
-    /** Valores por defecto al crear */
+    /** Default values applied when the setting is first accessed */
     defaults?: Record<string, unknown>;
-    /** Autorización CASL */
+    /** CASL authorization for read/update operations */
     casl?: EntityCaslConfig;
-    /** Prefijo de ruta para montar (default: inferido de key) */
+    /** API route prefix. Default: inferred from key */
     routePrefix?: string;
-    /** Actions vinculadas a esta entidad single */
+    /** Custom actions for this singleton (e.g., 'test-smtp', 'reset-defaults') */
     actions?: EntityAction[];
 }
 /**
- * Entidad de referencia - Catálogos con CRUD admin (countries, currencies)
+ * Reference entity - read-only catalogs for lookups and dropdowns.
+ *
+ * Use for relatively static data like countries, currencies, categories, statuses.
+ * Data can be seeded from code and optionally edited by admins.
+ *
+ * @example
+ * ```typescript
+ * const countries: ReferenceEntityDefinition = {
+ *   type: 'reference',
+ *   table: 'ref_countries',
+ *   label: { en: 'Country', es: 'País' },
+ *   labelField: 'name',
+ *   seed: [
+ *     { code: 'US', name: 'United States' },
+ *     { code: 'ES', name: 'Spain' }
+ *   ],
+ *   allowAdminEdit: true,
+ *   fields: { ... }
+ * }
+ * ```
  */
 interface ReferenceEntityDefinition extends BaseEntityDefinition {
+    /** Entity type identifier */
     type: 'reference';
-    /** Campo para mostrar en selects/referencias */
+    /** Field used as display label in dropdowns (e.g., 'name', 'title') */
     labelField: string;
-    /** Añadir created_at, updated_at */
+    /** Auto-add created_at and updated_at timestamp columns */
     timestamps?: boolean;
-    /** Índices compuestos */
+    /** Composite database indexes */
     indexes?: EntityIndex[];
-    /** Datos iniciales para seed */
+    /** Initial seed data inserted on first migration/startup */
     seed?: Array<Record<string, unknown>>;
-    /** Permitir CRUD para admin (default: false, solo lectura) */
+    /** Allow admin users to edit reference data. Default: false (read-only) */
     allowAdminEdit?: boolean;
 }
 /**
- * Entidad de eventos - Logs de auditoría, append-only
+ * Event entity - append-only logs for audit trails and analytics.
+ *
+ * Records can only be created (appended), never updated or deleted.
+ * Supports automatic retention policies to prevent unbounded growth.
+ *
+ * @example
+ * ```typescript
+ * const auditLogs: EventEntityDefinition = {
+ *   type: 'event',
+ *   table: 'sys_audit_logs',
+ *   label: { en: 'Audit Log', es: 'Log de Auditoría' },
+ *   labelField: 'action',
+ *   timestamps: true,
+ *   retention: { days: 90, maxRows: 100000 },
+ *   fields: {
+ *     action: { name: 'action', label: 'Action', input: 'text', ... },
+ *     user_id: { name: 'user_id', label: 'User', input: 'select', ... },
+ *     payload: { name: 'payload', label: 'Data', input: 'json', ... }
+ *   }
+ * }
+ * ```
  */
 interface EventEntityDefinition extends BaseEntityDefinition {
+    /** Entity type identifier */
     type: 'event';
-    /** Campo para mostrar en listas */
+    /** Field used as display label in event lists (e.g., 'action', 'event_type') */
     labelField: string;
-    /** Si false, no añade created_at/updated_at automáticos (útil si defines created_at explícitamente) */
+    /** Auto-add created_at column. Set false if you define timestamp fields explicitly */
     timestamps?: boolean;
-    /** Política de retención automática */
+    /** Automatic data retention to limit table growth */
     retention?: {
-        /** Eliminar registros más antiguos que N días */
+        /** Delete records older than N days */
         days?: number;
-        /** Mantener solo los últimos N registros */
+        /** Keep only the most recent N records (FIFO) */
         maxRows?: number;
     };
 }
 /**
- * Entidad de acción - Comandos/operaciones sin persistencia
- * Para actions que operan sobre registros existentes, usar EntityAction en la entidad padre
+ * Action entity - standalone commands/operations without data persistence.
+ *
+ * Use for operations like sending emails, generating reports, triggering workflows.
+ * For actions that operate on existing records, use {@link EntityAction} instead.
+ *
+ * @example
+ * ```typescript
+ * const sendEmail: ActionEntityDefinition = {
+ *   type: 'action',
+ *   label: { en: 'Send Email', es: 'Enviar Email' },
+ *   icon: 'mdi:email-send',
+ *   fields: {
+ *     to: { name: 'to', label: 'To', input: 'email', required: true },
+ *     subject: { name: 'subject', label: 'Subject', input: 'text', required: true },
+ *     body: { name: 'body', label: 'Body', input: 'markdown' }
+ *   },
+ *   handler: async (ctx, input) => {
+ *     await ctx.services.mail.send(input)
+ *     return { success: true }
+ *   }
+ * }
+ * ```
  */
 interface ActionEntityDefinition {
+    /** Entity type identifier */
     type: 'action';
-    /** Nombre para mostrar en UI */
-    label: string;
-    /** Icono Iconify para UI (default: 'mdi:play') */
+    /** Display name for the action button/form */
+    label: LocalizedString;
+    /** Iconify icon identifier (default: 'mdi:play') */
     icon?: string;
-    /** Solo campos de formulario para input, sin BD */
+    /** Form fields for action input. These don't create database columns */
     fields: Record<string, FieldDefinition>;
-    /** Schema Zod de input (se valida antes de ejecutar) */
+    /** Zod schema for validating input before execution */
     inputSchema?: ValidationSchema;
-    /** Schema Zod de output (documenta respuesta) */
+    /** Zod schema documenting the response structure */
     outputSchema?: ValidationSchema;
-    /** Método HTTP (default: POST) */
-    method?: 'GET' | 'POST';
-    /**
-     * Middleware a aplicar antes del handler (ej: multer para uploads)
-     * Puede retornar un middleware o un array de middlewares
-     */
+    /** HTTP method for the action endpoint (default: 'POST') */
+    method?: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+    /** Custom middleware (e.g., multer for file uploads). Returns single or array of handlers */
     middleware?: (ctx: ModuleContext) => RequestHandler | RequestHandler[];
-    /**
-     * Handler que ejecuta la acción
-     * @param ctx - Contexto del módulo
-     * @param input - Datos del body. Incluye _authUserId si hay usuario autenticado.
-     * @param req - Request de Express (opcional, para acceder a req.file, etc.)
-     * @param res - Response de Express (opcional, para streams, headers custom, etc.)
-     */
+    /** Handler function that executes the action logic. Input includes _authUserId if authenticated */
     handler?: (ctx: ModuleContext, input: unknown, req?: Request, res?: Response) => Promise<unknown>;
-    /** HTTP status code para respuesta exitosa (default: 200, usar 201 para creación) */
+    /** HTTP status code for success response. Default: 200, use 201 for resource creation */
     successStatus?: number;
-    /** Autorización CASL */
+    /** CASL authorization configuration */
     casl?: EntityCaslConfig;
-    /** Prefijo de ruta para montar */
+    /** API route prefix for the action endpoint */
     routePrefix?: string;
-    /** Orden de visualización en UI (menor = primero, default: 999) */
+    /** UI sidebar ordering. Lower values appear first (default: 999) */
     order?: number;
 }
 /**
- * Entidad externa - Datos de APIs externas (stripe_customers, github_repos)
- * Read-only, sin persistencia local
+ * External entity - read-only data from external APIs.
+ *
+ * Use for integrating third-party services like Stripe customers, GitHub repos,
+ * or any external REST API. Data is fetched on-demand through adapters.
+ *
+ * @example
+ * ```typescript
+ * const stripeCustomers: ExternalEntityDefinition = {
+ *   type: 'external',
+ *   label: { en: 'Stripe Customer', es: 'Cliente Stripe' },
+ *   labelField: 'email',
+ *   adapter: 'stripe',
+ *   source: { endpoint: 'customers' },
+ *   cache: { ttl: 300, invalidateOn: ['stripe.customer.*'] },
+ *   fields: {
+ *     id: { name: 'id', label: 'ID', input: 'text' },
+ *     email: { name: 'email', label: 'Email', input: 'email' },
+ *     name: { name: 'name', label: 'Name', input: 'text' }
+ *   }
+ * }
+ * ```
  */
 interface ExternalEntityDefinition {
+    /** Entity type identifier */
     type: 'external';
-    /** Nombre para mostrar en UI */
-    label: string;
-    /** Campo para mostrar en selects/referencias */
+    /** Display name for the UI (singular form) */
+    label: LocalizedString;
+    /** Display name for the UI (plural form) */
+    labelPlural?: LocalizedString;
+    /** Field used as display label in lists and references */
     labelField: string;
-    /** Definición de campos (estructura esperada del API externo) */
+    /** Field definitions mapping to the external API response structure */
     fields: Record<string, FieldDefinition>;
-    /** Nombre del adapter registrado (ej: 'stripe', 'github') */
+    /** Registered adapter name that handles API communication (e.g., 'stripe', 'github', 'salesforce') */
     adapter: string;
-    /** Configuración del origen externo (pasada al adapter) */
+    /** Configuration passed to the adapter */
     source?: {
-        /** Endpoint o recurso específico */
+        /** API endpoint or resource path */
         endpoint?: string;
-        /** Config adicional */
+        /** Additional adapter-specific configuration */
         [key: string]: unknown;
     };
-    /** Configuración de cache */
+    /** Response caching to reduce API calls */
     cache?: {
-        /** TTL en segundos */
+        /** Cache time-to-live in seconds */
         ttl: number;
-        /** Campo para generar cache key */
+        /** Field used to generate unique cache keys */
         key?: string;
-        /** Eventos que invalidan la cache (ej: ['db.users.*']) */
+        /** Event patterns that invalidate cached data (e.g., ['stripe.customer.*']) */
         invalidateOn?: string[];
     };
-    /** Autorización CASL */
+    /** CASL authorization for read operations */
     casl?: EntityCaslConfig;
-    /** Prefijo de ruta para montar */
+    /** API route prefix */
     routePrefix?: string;
-    /** Orden de visualización en UI (menor = primero, default: 999) */
+    /** UI sidebar ordering (default: 999) */
     order?: number;
+    /** UI display mode: 'table', 'list', or 'masonry' */
+    displayMode?: DisplayMode;
 }
 /**
- * Entidad virtual - Orquestación de múltiples fuentes (unified_customers)
- * Read-only, combina datos de varias entidades
+ * Virtual entity - data aggregation across multiple sources.
+ *
+ * Use to create unified views combining local entities, external APIs, or computed data.
+ * Read-only, no persistence - data is resolved on each request.
+ *
+ * @example
+ * ```typescript
+ * const unifiedContacts: VirtualEntityDefinition = {
+ *   type: 'virtual',
+ *   label: { en: 'Contact', es: 'Contacto' },
+ *   labelField: 'name',
+ *   sources: ['crm_contacts', 'stripe_customers'],
+ *   resolver: (sources, ctx) => {
+ *     const contacts = sources.crm_contacts.map(c => ({ ...c, source: 'crm' }))
+ *     const customers = sources.stripe_customers.map(c => ({ ...c, source: 'stripe' }))
+ *     return [...contacts, ...customers]
+ *   },
+ *   fields: { ... }
+ * }
+ * ```
  */
 interface VirtualEntityDefinition {
+    /** Entity type identifier */
     type: 'virtual';
-    /** Nombre para mostrar en UI */
-    label: string;
-    /** Campo para mostrar en selects/referencias */
+    /** Display name for the UI (singular form) */
+    label: LocalizedString;
+    /** Display name for the UI (plural form) */
+    labelPlural?: LocalizedString;
+    /** Field used as display label in lists and references */
     labelField: string;
-    /** Definición de campos (esquema unificado) */
+    /** Unified field definitions for the combined schema */
     fields: Record<string, FieldDefinition>;
-    /** Fuentes de datos que se combinan (nombres de entidades/tables) */
+    /** Entity or table names to fetch data from */
     sources: string[];
-    /** Función que combina los datos de las fuentes */
+    /** Custom function to combine and transform data from all sources */
     resolver?: (sources: Record<string, unknown[]>, ctx: ModuleContext) => unknown[] | Promise<unknown[]>;
-    /** Autorización CASL */
+    /** CASL authorization for read operations */
     casl?: EntityCaslConfig;
-    /** Prefijo de ruta para montar */
+    /** API route prefix */
     routePrefix?: string;
-    /** Orden de visualización en UI (menor = primero, default: 999) */
+    /** UI sidebar ordering (default: 999) */
     order?: number;
+    /** UI display mode: 'table', 'list', or 'masonry' */
+    displayMode?: DisplayMode;
 }
 /**
- * Entidad computed - KPIs, estadísticas, métricas calculadas
- * Read-only, puede cachear opcionalmente
+ * Computed entity - dynamically calculated data like KPIs, statistics, and metrics.
+ *
+ * Use for dashboards, reports, and analytics that derive from other data sources.
+ * Read-only, computed on-demand with optional caching.
+ *
+ * @example
+ * ```typescript
+ * const salesMetrics: ComputedEntityDefinition = {
+ *   type: 'computed',
+ *   label: { en: 'Sales Metrics', es: 'Métricas de Ventas' },
+ *   isSingle: true, // returns single record with all metrics
+ *   cache: { ttl: 60, invalidateOn: ['db.orders.*'] },
+ *   compute: async (ctx) => [{
+ *     totalSales: await ctx.db('orders').sum('total'),
+ *     orderCount: await ctx.db('orders').count(),
+ *     avgOrderValue: await ctx.db('orders').avg('total')
+ *   }],
+ *   fields: {
+ *     totalSales: { name: 'totalSales', label: 'Total Sales', input: 'number' },
+ *     orderCount: { name: 'orderCount', label: 'Orders', input: 'number' },
+ *     avgOrderValue: { name: 'avgOrderValue', label: 'Avg Order', input: 'decimal' }
+ *   }
+ * }
+ * ```
  */
 interface ComputedEntityDefinition {
+    /** Entity type identifier */
     type: 'computed';
-    /** Nombre para mostrar en UI */
-    label: string;
-    /** Campo para mostrar en selects/referencias */
+    /** Display name for the UI (singular form) */
+    label: LocalizedString;
+    /** Display name for the UI (plural form) */
+    labelPlural?: LocalizedString;
+    /** Field used as display label (optional for computed entities) */
     labelField?: string;
-    /** Definición de campos (estructura del resultado) */
+    /** Field definitions for the computed result structure */
     fields: Record<string, FieldDefinition>;
-    /** Función que calcula los datos */
+    /** Function that computes and returns the data. Receives query params from URL */
     compute?: (ctx: ModuleContext, params?: Record<string, unknown>) => Promise<unknown[]>;
-    /** Configuración de cache */
+    /** Caching to avoid recomputation on every request */
     cache?: {
-        /** TTL en segundos (0 = sin cache) */
+        /** Cache time-to-live in seconds. 0 = no caching */
         ttl: number;
-        /** Eventos que invalidan la cache (ej: ['db.users.*']) */
+        /** Event patterns that trigger cache invalidation */
         invalidateOn?: string[];
     };
-    /** Autorización CASL */
+    /** If true, returns single object instead of array (for dashboards, system info) */
+    isSingle?: boolean;
+    /** CASL authorization for read operations */
     casl?: EntityCaslConfig;
-    /** Prefijo de ruta para montar */
+    /** API route prefix */
     routePrefix?: string;
-    /** Orden de visualización en UI (menor = primero, default: 999) */
+    /** UI sidebar ordering (default: 999) */
     order?: number;
+    /** UI display mode: 'table', 'list', or 'masonry' */
+    displayMode?: DisplayMode;
 }
 /**
- * Entidad view - Vista optimizada para lectura (projections, denormalizaciones)
- * Read-only, puede ser vista de BD o virtual
+ * View entity - read-only database view or projection.
+ *
+ * Use for optimized read patterns, denormalized data, or SQL VIEWs.
+ * Can reference actual database views or define virtual queries.
+ *
+ * @example
+ * ```typescript
+ * const orderSummary: ViewEntityDefinition = {
+ *   type: 'view',
+ *   table: 'v_order_summary', // actual SQL VIEW
+ *   label: { en: 'Order Summary', es: 'Resumen de Pedidos' },
+ *   labelField: 'order_number',
+ *   sourceEntity: 'orders',
+ *   query: (db) => db('orders')
+ *     .select('orders.*', 'customers.name as customer_name')
+ *     .join('customers', 'orders.customer_id', 'customers.id'),
+ *   fields: { ... }
+ * }
+ * ```
  */
 interface ViewEntityDefinition {
+    /** Entity type identifier */
     type: 'view';
-    /** Tabla o vista en BD (puede ser VIEW SQL) */
+    /** Database table or SQL VIEW name */
     table: string;
-    /** Nombre para mostrar en UI */
-    label: string;
-    /** Campo para mostrar en selects/referencias */
+    /** Display name for the UI (singular form) */
+    label: LocalizedString;
+    /** Display name for the UI (plural form) */
+    labelPlural?: LocalizedString;
+    /** Field used as display label in lists and references */
     labelField: string;
-    /** Definición de campos */
+    /** Field definitions for the view columns */
     fields: Record<string, FieldDefinition>;
-    /** Entidad fuente de la que deriva */
+    /** Source entity this view derives from (for documentation) */
     sourceEntity?: string;
-    /** Query SQL o builder para crear la vista */
+    /** SQL query string or Knex query builder function to define the view */
     query?: string | ((db: Knex) => Knex.QueryBuilder);
-    /** Autorización CASL */
+    /** CASL authorization for read operations */
     casl?: EntityCaslConfig;
-    /** Prefijo de ruta para montar */
+    /** API route prefix */
     routePrefix?: string;
-    /** Orden de visualización en UI (menor = primero, default: 999) */
+    /** UI sidebar ordering (default: 999) */
     order?: number;
 }
 /**
- * Entidad config - Configuración por módulo/tenant
- * Similar a single pero con scope
+ * Config entity - scoped configuration settings.
+ *
+ * Similar to single entity but with scoping support for multi-tenant,
+ * per-module, or per-user configurations.
+ *
+ * @example
+ * ```typescript
+ * const moduleConfig: ConfigEntityDefinition = {
+ *   type: 'config',
+ *   table: 'module_configs',
+ *   label: { en: 'Module Config', es: 'Config de Módulo' },
+ *   scope: 'module',
+ *   scopeField: 'module_name',
+ *   defaults: { enableFeatureX: false, maxItems: 100 },
+ *   timestamps: true,
+ *   fields: {
+ *     module_name: { name: 'module_name', label: 'Module', input: 'text' },
+ *     enableFeatureX: { name: 'enableFeatureX', label: 'Feature X', input: 'switch' },
+ *     maxItems: { name: 'maxItems', label: 'Max Items', input: 'number' }
+ *   }
+ * }
+ * ```
  */
 interface ConfigEntityDefinition extends BaseEntityDefinition {
+    /** Entity type identifier */
     type: 'config';
-    /** Campo que identifica el scope (ej: 'module_name', 'tenant_id') */
+    /** Field that identifies the configuration scope (e.g., 'module_name', 'tenant_id', 'user_id') */
     scopeField?: string;
-    /** Scope de la configuración */
+    /** Configuration scope level: 'global', 'module', 'tenant', or 'user' */
     scope?: 'global' | 'module' | 'tenant' | 'user';
-    /** Valores por defecto */
+    /** Default values applied when config is first accessed */
     defaults?: Record<string, unknown>;
-    /** Añadir updated_at */
+    /** Auto-add updated_at timestamp column */
     timestamps?: boolean;
-    /** Añadir updated_by */
+    /** Auto-add updated_by user reference column */
     audit?: boolean;
 }
 /**
- * Entidad temporal - Cache, sesiones, OTP codes
- * Con TTL automático, sin auditoría
+ * Temporary entity - short-lived data with automatic expiration.
+ *
+ * Use for OTP codes, session tokens, password reset links, cache entries.
+ * Records are automatically deleted after TTL expires.
+ *
+ * @example
+ * ```typescript
+ * const otpCodes: TempEntityDefinition = {
+ *   type: 'temp',
+ *   table: 'auth_otp_codes',
+ *   label: { en: 'OTP Code', es: 'Código OTP' },
+ *   ttl: 300, // 5 minutes
+ *   indexes: [{ columns: ['user_id', 'code'] }],
+ *   fields: {
+ *     user_id: { name: 'user_id', label: 'User', input: 'select', ... },
+ *     code: { name: 'code', label: 'Code', input: 'text', ... },
+ *     expires_at: { name: 'expires_at', label: 'Expires', input: 'datetime', ... }
+ *   }
+ * }
+ * ```
  */
 interface TempEntityDefinition extends BaseEntityDefinition {
+    /** Entity type identifier */
     type: 'temp';
-    /** Tiempo de vida en segundos */
+    /** Time-to-live in seconds. Records are deleted after this duration */
     ttl: number;
-    /** Campo que almacena la fecha de expiración (default: 'expires_at') */
+    /** Field that stores the expiration timestamp (default: 'expires_at') */
     ttlField?: string;
-    /** Campo para mostrar en listas (opcional) */
+    /** Field used as display label in lists (optional for temp entities) */
     labelField?: string;
-    /** Índices para búsqueda rápida */
+    /** Database indexes for efficient lookups */
     indexes?: EntityIndex[];
 }
 /**
- * Todos los tipos de entidad disponibles
+ * All available entity type identifiers.
+ *
+ * @see {@link EntityDefinition} for the full discriminated union with documentation
  */
 type EntityType = 'collection' | 'single' | 'external' | 'virtual' | 'computed' | 'view' | 'reference' | 'config' | 'event' | 'temp' | 'action';
 /**
- * Union de todas las definiciones de entidad
- *
- * | Type       | Persistencia | CRUD            | Uso principal                    |
- * |------------|--------------|-----------------|----------------------------------|
- * | collection | Sí (BD)      | Completo        | Datos de negocio (users, posts)  |
- * | single     | Sí (BD)      | Update/Read     | Config global (site_config)      |
- * | external   | No           | Read            | Datos externos (stripe_customers)|
- * | virtual    | No           | Read            | Orquestación (unified_customers) |
- * | computed   | No/opcional  | Read            | KPIs, estadísticas               |
- * | view       | Sí/virtual   | Read            | Lectura optimizada (projections) |
- * | reference  | Sí           | Read (admin)    | Catálogos (countries, currencies)|
- * | config     | Sí           | Update/Read     | Config por módulo                |
- * | event      | Sí           | Append          | Auditoría (audit_logs)           |
- * | temp       | No (TTL)     | Read/Write      | Cache, sesiones (otp_codes)      |
- * | action     | No           | Execute         | Operaciones, workflows           |
+ * Display mode for entity list views in the UI.
+ *
+ * - `table` - Data grid with columns, sorting, filtering (default)
+ * - `list` - Card-based vertical list
+ * - `masonry` - Pinterest-style image gallery grid
+ */
+type DisplayMode = 'table' | 'list' | 'masonry';
+/**
+ * Union of all entity definitions
+ *
+ * | Type       | Persistence | CRUD            | Primary use                      |
+ * |------------|-------------|-----------------|----------------------------------|
+ * | collection | Yes (DB)    | Full            | Business data (users, posts)     |
+ * | single     | Yes (DB)    | Update/Read     | Global config (site_config)      |
+ * | external   | No          | Read            | External data (stripe_customers) |
+ * | virtual    | No          | Read            | Orchestration (unified_customers)|
+ * | computed   | No/optional | Read            | KPIs, stats                      |
+ * | view       | Yes/virtual | Read            | Optimized reads (projections)    |
+ * | reference  | Yes         | Read (admin)    | Catalogs (countries, currencies) |
+ * | config     | Yes         | Update/Read     | Per-module config                |
+ * | event      | Yes         | Append          | Audit logs (audit_logs)          |
+ * | temp       | No (TTL)    | Read/Write      | Cache, sessions (otp_codes)      |
+ * | action     | No          | Execute         | Operations, workflows            |
  */
 type EntityDefinition = CollectionEntityDefinition | SingleEntityDefinition | ExternalEntityDefinition | VirtualEntityDefinition | ComputedEntityDefinition | ViewEntityDefinition | ReferenceEntityDefinition | ConfigEntityDefinition | EventEntityDefinition | TempEntityDefinition | ActionEntityDefinition;
 /**
- * Requisitos para activar un módulo
+ * Requirements that must be met to activate a module.
+ *
+ * Modules with unmet requirements are skipped during initialization.
+ *
+ * @example
+ * ```typescript
+ * requirements: {
+ *   env: ['STRIPE_SECRET_KEY', 'STRIPE_WEBHOOK_SECRET'],
+ *   modules: ['auth', 'storage']
+ * }
+ * ```
  */
 interface ModuleRequirements {
+    /** Environment variables that must be defined */
     env?: string[];
+    /** Other modules that must be loaded first */
     modules?: string[];
 }
 /**
- * Interfaz genérica para ability CASL
- * Permite verificar permisos sin depender directamente de @casl/ability
+ * Generic interface for CASL ability.
+ *
+ * Provides permission checking without directly depending on @casl/ability package.
+ * Used in request objects for authorization checks.
+ *
+ * @example
+ * ```typescript
+ * if (req.ability.can('update', post)) {
+ *   // User can update this post
+ * }
+ * if (req.ability.cannot('delete', post)) {
+ *   throw new ForbiddenError('Cannot delete post')
+ * }
+ * ```
  */
 interface AbilityLike {
+    /** Check if action is allowed on subject */
     can: (action: string, subject: unknown) => boolean;
+    /** Check if action is denied on subject */
     cannot: (action: string, subject: unknown) => boolean;
 }
 /**
- * Error de forbidden con método throwUnlessCan
+ * CASL ForbiddenError instance for throwing permission errors.
  */
 interface ForbiddenErrorInstance {
+    /** Throws ForbiddenError if action is not allowed on subject */
     throwUnlessCan: (action: string, subject: unknown) => void;
 }
 /**
- * Constructor de ForbiddenError con método from()
+ * CASL ForbiddenError constructor for creating error instances.
  */
 interface ForbiddenErrorConstructor {
+    /** Creates a ForbiddenErrorInstance bound to an ability */
     from: (ability: any) => ForbiddenErrorInstance;
 }
 /**
- * Abilities CASL disponibles en el contexto
- * Permite usar CASL en plugins sin importar @casl/ability directamente
+ * CASL abilities API available in module context.
+ *
+ * Allows modules to use CASL for authorization without importing @casl/ability directly.
+ *
+ * @example
+ * ```typescript
+ * // In module handler
+ * const ability = ctx.abilities.defineAbilityFor(user)
+ * ctx.abilities.ForbiddenError.from(ability).throwUnlessCan('update', post)
+ * ```
  */
 interface ModuleAbilities {
-    /** Crea una ability CASL para un usuario */
-    defineAbilityFor: (user: BaseUser | null, ...args: unknown[]) => unknown;
-    /** Empaqueta reglas CASL para enviar al cliente */
+    /** Creates CASL ability instance for a user based on their roles */
+    defineAbilityFor: (user: {
+        id: string;
+    } | null, ...args: unknown[]) => unknown;
+    /** Serializes CASL rules for client-side authorization (frontend) */
     packRules: (ability: unknown) => unknown[];
-    /** Wrapper para verificar permisos contra instancias */
+    /** Wraps an object as CASL subject for instance-level permission checks */
     subject: (type: string, object: Record<string, unknown>) => unknown;
-    /** Error de CASL para throwUnlessCan */
+    /** ForbiddenError constructor for throwUnlessCan pattern */
     ForbiddenError: ForbiddenErrorConstructor;
 }
 /**
- * AuthRequest pre-tipado para uso en plugins
- * Usa BaseUser y AbilityLike para tipado básico sin depender del backend
+ * Pre-typed authenticated request with BaseUser and AbilityLike.
+ *
+ * Use this type for route handlers that require authentication.
+ *
+ * @example
+ * ```typescript
+ * const handler = async (req: AuthRequest, res: Response) => {
+ *   const userId = req.user.id
+ *   if (req.ability.can('read', 'Post')) { ... }
+ * }
+ * ```
  */
-type PluginAuthRequest = AuthRequest<BaseUser, AbilityLike>;
+type AuthRequest = BaseAuthRequest<BaseUser, AbilityLike>;
 /**
- * Helpers del contexto (migraciones, utilidades)
+ * Helper utilities available in module context.
+ *
+ * Provides common operations for migrations, ID generation, and path resolution.
  */
 interface ContextHelpers {
+    /** Generates a unique UUID v4 identifier */
     generateId: () => string;
+    /** Adds created_at and updated_at columns to a table during migration */
     addTimestamps: (table: Knex.CreateTableBuilder, db: Knex) => void;
+    /** Adds created_by and updated_by columns if they don't exist */
     addAuditFieldsIfMissing: (db: Knex, tableName: string) => Promise<void>;
-    /** Añade campo is_default a tablas de tipo config */
+    /** Adds is_default boolean field for config tables */
     addConfigDefaultField: (db: Knex, tableName: string) => Promise<void>;
+    /** Adds a column only if it doesn't exist. Returns true if column was added */
     addColumnIfMissing: (db: Knex, tableName: string, columnName: string, columnBuilder: (table: Knex.AlterTableBuilder) => void) => Promise<boolean>;
+    /** Gets the path to the nexus-backend library directory */
     getLibPath: () => string;
+    /** Gets the path to the user's project root directory */
     getProjectPath: () => string;
-    /** Timestamp formateado para el driver de BD actual (MySQL: 'YYYY-MM-DD HH:MM:SS', otros: ISO 8601) */
+    /** Returns current timestamp formatted for the DB driver (MySQL: 'YYYY-MM-DD HH:MM:SS', others: ISO 8601) */
     nowTimestamp: (db: Knex) => string;
-    /** Formatea una fecha para el driver de BD actual */
+    /** Formats a Date object for the current DB driver */
     formatTimestamp: (db: Knex, date?: Date) => string;
 }
 /**
- * Utilidades criptográficas del contexto
+ * Cryptographic utilities for password handling.
+ *
+ * Uses bcrypt with cost factor 12 for secure password hashing.
  */
 interface ContextCrypto {
-    /** Hash de password usando bcrypt (cost factor 12) */
+    /** Hashes a password using bcrypt (cost factor 12) */
     hashPassword: (password: string) => Promise<string>;
-    /** Verifica password contra hash bcrypt (timing-safe) */
+    /** Verifies password against bcrypt hash (timing-safe comparison) */
     verifyPassword: (password: string, hash: string) => Promise<boolean>;
-    /** Hash dummy para timing-safe comparison cuando usuario no existe */
+    /** Pre-computed dummy hash for timing-safe comparison when user doesn't exist */
     DUMMY_HASH: string;
 }
 /**
- * API de Socket.IO del contexto
- * @note Solo disponible si Socket.IO está inicializado
+ * Socket.IO real-time communication API.
+ *
+ * Provides access to WebSocket connections for real-time features.
+ * Only available if Socket.IO is initialized in the backend configuration.
  */
 interface ContextSocket {
-    /** Obtiene la instancia de Socket.IO (throws si no inicializado) */
+    /** Gets the Socket.IO server instance. Throws if not initialized */
     getIO: () => unknown;
-    /** Verifica si Socket.IO está inicializado */
+    /** Checks if Socket.IO server is running */
     isInitialized: () => boolean;
-    /** Verifica si un usuario específico está conectado */
+    /** Checks if a specific user has active WebSocket connections */
     isUserConnected: (userId: string) => boolean;
-    /** Obtiene el número de sockets conectados para un usuario */
+    /** Gets the number of active sockets for a user (multiple tabs/devices) */
     getUserSocketCount: (userId: string) => number;
-    /** Obtiene los IDs de usuarios conectados */
+    /** Gets array of all connected user IDs */
     getConnectedUsers: () => string[];
 }
 /**
- * API del Engine para introspección de módulos y plugins
- * Permite acceder al registro de módulos y plugins cargados
+ * Application manifest with module and plugin registry.
+ *
+ * Represents either the core nexus-backend manifest or a user project manifest.
+ */
+interface AppManifest {
+    /** Package name from package.json */
+    name: string;
+    /** Package version from package.json */
+    version: string;
+    /** Registered modules in this application */
+    modules: ModuleManifest[];
+    /** Registered plugins (only present in user manifest) */
+    plugins?: PluginManifest[];
+}
+/**
+ * Engine API for runtime introspection of modules and plugins.
+ *
+ * Provides access to the complete registry of loaded components.
  */
 interface ContextEngine {
-    /** Obtiene todos los módulos registrados */
+    /** Gets all registered modules (core + user) */
     getModules: () => ModuleManifest[];
-    /** Obtiene todos los plugins registrados */
+    /** Gets all registered plugins */
     getPlugins: () => PluginManifest[];
-    /** Obtiene los subjects CASL de un módulo específico */
+    /** Gets CASL subjects defined by a specific module */
     getModuleSubjects: (mod: ModuleManifest) => string[];
-    /** Obtiene todos los subjects CASL registrados en el sistema */
+    /** Gets all CASL subjects registered across all modules */
     getRegisteredSubjects: () => string[];
-}
-/**
- * Schema de validación genérico (compatible con Zod sin depender de él)
- * Cualquier objeto con método parse() es válido
+    /** Gets modules from nexus-backend core (auth, users, storage, etc.) */
+    getCoreModules: () => ModuleManifest[];
+    /** Gets modules from user project and plugins */
+    getUserModules: () => ModuleManifest[];
+    /** Gets the nexus-backend library manifest */
+    getCoreManifest: () => AppManifest;
+    /** Gets the user project manifest. Returns null in standalone development mode */
+    getUserManifest: () => AppManifest | null;
+    /** Returns true if running as a library inside a user project */
+    hasUserApp: () => boolean;
+}
+/**
+ * Generic validation schema interface compatible with Zod.
+ *
+ * Any object with a parse() method that throws on invalid data works.
  */
 interface ValidationSchema {
+    /** Parses and validates data. Throws on validation failure */
     parse: (data: unknown) => unknown;
 }
 /**
- * Opciones para el middleware de validación
+ * Schemas for the validation middleware.
+ *
+ * Validates request body, query parameters, and URL parameters.
  */
 interface ValidateSchemas {
+    /** Schema for request body (req.body) */
     body?: ValidationSchema;
+    /** Schema for query parameters (req.query) */
     query?: ValidationSchema;
+    /** Schema for URL parameters (req.params) */
     params?: ValidationSchema;
 }
 /**
- * Middlewares disponibles en el contexto
+ * Configuration options for rate limiting middleware.
+ */
+interface RateLimitOptions {
+    /** Time window duration in milliseconds (default: 60000 = 1 minute) */
+    windowMs?: number;
+    /** Maximum requests allowed per window (default: 100) */
+    max?: number;
+    /** Error message when rate limit is exceeded */
+    message?: string;
+}
+/**
+ * Middleware factories available in module context.
+ *
+ * Provides common Express middlewares for validation, rate limiting, etc.
  */
 interface ModuleMiddlewares {
+    /** Creates validation middleware for body/query/params */
     validate: (schemas: ValidateSchemas) => RequestHandler;
+    /** Creates rate limiting middleware */
+    rateLimit: (options?: RateLimitOptions) => RequestHandler;
+    /** Extensible: additional middlewares can be registered */
     [key: string]: RequestHandler | ((...args: any[]) => RequestHandler) | undefined;
 }
 /**
- * Interfaz mínima de EventEmitter compatible con EventEmitter2
+ * Minimal EventEmitter interface compatible with EventEmitter2.
+ *
+ * Used for inter-module communication and event-driven architecture.
  */
 interface EventEmitterLike {
+    /** Emits an event with arguments. Returns true if listeners exist */
     emit: (event: string, ...args: unknown[]) => boolean;
+    /** Registers an event listener */
     on: (event: string, listener: (...args: unknown[]) => void) => this;
+    /** Removes an event listener */
     off: (event: string, listener: (...args: unknown[]) => void) => this;
+    /** Registers a one-time event listener */
     once: (event: string, listener: (...args: unknown[]) => void) => this;
+    /** Registers a listener for all events (EventEmitter2 feature) */
     onAny?: (listener: (event: string, ...args: unknown[]) => void) => this;
 }
 /**
- * Reporter mínimo para errores (Sentry/GlitchTip, etc.)
+ * Error reporter interface for external monitoring services.
+ *
+ * Compatible with Sentry, GlitchTip, or any error tracking service.
  */
 interface LoggerReporter {
+    /** Captures and reports an exception to the monitoring service */
     captureException: (error: Error, context?: Record<string, unknown>) => void;
 }
+/**
+ * Filter operators for advanced filtering
+ *
+ * @example
+ * // Simple equality (shorthand)
+ * { status: 'active' }
+ *
+ * // With operators
+ * { name: { $contains: 'john' } }
+ * { age: { $gte: 18 } }
+ * { email: { $startswith: 'admin' } }
+ *
+ * // Array (IN operator shorthand)
+ * { status: ['active', 'pending'] }
+ */
+interface FilterOperators {
+    /** Equal (default if no operator) */
+    $eq?: unknown;
+    /** Not equal */
+    $ne?: unknown;
+    /** Greater than */
+    $gt?: number | string | Date;
+    /** Greater than or equal */
+    $gte?: number | string | Date;
+    /** Less than */
+    $lt?: number | string | Date;
+    /** Less than or equal */
+    $lte?: number | string | Date;
+    /** Contains (LIKE %value%) */
+    $contains?: string;
+    /** Starts with (LIKE value%) */
+    $startswith?: string;
+    /** Ends with (LIKE %value) */
+    $endswith?: string;
+    /** In array */
+    $in?: unknown[];
+    /** Not in array */
+    $nin?: unknown[];
+    /** Is null (true = IS NULL, false = IS NOT NULL) */
+    $isnull?: boolean;
+}
+/**
+ * Filter value can be:
+ * - Primitive (shorthand for $eq)
+ * - Array (shorthand for $in)
+ * - Object with operators
+ */
+type FilterValue = string | number | boolean | null | unknown[] | FilterOperators;
 /**
  * Query parameters for entity list operations
+ *
+ * @example
+ * // Simple filters
+ * { filters: { status: 'active' } }
+ *
+ * // With operators (see FilterOperators)
+ * { filters: { name: { $contains: 'john' }, age: { $gte: 18 } } }
  */
 interface EntityQuery {
     page?: number;
@@ -790,52 +1639,92 @@ interface EntityQuery {
     sort?: string;
     order?: 'asc' | 'desc';
     search?: string;
+    /** Filters with optional operators - use FilterValue type for type safety */
     filters?: Record<string, unknown>;
 }
 /**
- * Interfaz base para sub-servicio de roles
- * El backend extiende esto con tipos concretos
+ * Role management service interface.
+ *
+ * Provides CRUD operations for roles. Used internally by UsersService.
  */
 interface BaseRolesService {
+    /** Gets paginated list of all roles */
     findAll(query?: EntityQuery): Promise<PaginatedResult<unknown>>;
+    /** Gets a role by its ID */
     findById(id: string): Promise<unknown>;
+    /** Gets a role by its name (e.g., 'ADMIN', 'EDITOR') */
     findByName(name: string): Promise<unknown | undefined>;
-    getPermissionsByRoleId(roleId: string): Promise<unknown[]>;
+    /** Creates a new role */
     create(data: Record<string, unknown>, userId?: string): Promise<unknown>;
+    /** Updates an existing role */
     update(id: string, data: Record<string, unknown>, userId?: string): Promise<unknown>;
+    /** Deletes a role by ID */
     delete(id: string): Promise<void>;
-    updatePermissions(id: string, permissions: unknown[], userId?: string): Promise<unknown>;
 }
 /**
- * Interfaz base para servicio de usuarios
- * El backend extiende esto con tipos concretos (UserWithRole, etc.)
+ * User management service interface.
+ *
+ * Provides user CRUD and role assignment operations.
+ * The backend extends this with concrete types (UserWithRole, etc.).
  */
 interface BaseUsersService {
+    /** Gets paginated list of users */
     findAll(query?: EntityQuery): Promise<PaginatedResult<unknown>>;
+    /** Gets a user by ID without role information */
     findById(id: string): Promise<unknown>;
-    findByIdWithRole(id: string): Promise<unknown | null>;
+    /** Gets a user by ID including their assigned roles */
+    findByIdWithRoles(id: string): Promise<unknown | null>;
+    /** Creates a new user */
     create(data: Record<string, unknown>, userId?: string): Promise<unknown>;
+    /** Updates an existing user */
     update(id: string, data: Record<string, unknown>, userId?: string): Promise<unknown>;
+    /** Deletes a user by ID */
     delete(id: string): Promise<void>;
+    /** Gets array of role IDs for a user */
+    getRoleIds(userId: string): Promise<string[]>;
+    /** Gets array of role names for a user (e.g., ['ADMIN', 'EDITOR']) */
+    getRoleNames(userId: string): Promise<string[]>;
+    /** Gets full role objects for a user */
+    getUserRoles(userId: string): Promise<unknown[]>;
+    /** Assigns a single role to a user (adds to existing roles) */
+    assignRole(userId: string, roleId: string): Promise<void>;
+    /** Removes a single role from a user */
+    removeRole(userId: string, roleId: string): Promise<void>;
+    /** Replaces all user roles with the provided list */
+    setRoles(userId: string, roleIds: string[]): Promise<void>;
+    /** Nested roles service for direct role management */
     roles: BaseRolesService;
 }
 /**
- * Opciones para envío de email
+ * Email sending options.
+ *
+ * Supports both simple text emails and rich HTML templates with actions.
  */
 interface SendMailOptions {
+    /** Recipient email address(es) */
     to: string | string[];
+    /** Email subject line */
     subject: string;
+    /** Title for email template (displayed prominently) */
     title?: string;
+    /** Plain text message for simple emails */
     message?: string;
+    /** Full HTML content (overrides template) */
     html?: string;
+    /** Plain text fallback (generated from HTML if not provided) */
     text?: string;
+    /** Sender email address (uses default if not provided) */
     from?: string;
+    /** Reply-to email address */
     replyTo?: string;
+    /** CTA buttons for email template */
     actions?: Array<{
         label: string;
         url: string;
     }>;
+    /** Logo URL for email header */
     logoUrl?: string;
+    /** File attachments */
     attachments?: Array<{
         filename: string;
         content: Buffer | string;
@@ -843,290 +1732,642 @@ interface SendMailOptions {
     }>;
 }
 /**
- * Resultado del envío de email
+ * Result from sending an email.
  */
 interface SendMailResult {
+    /** Unique message ID from the mail server */
     messageId: string;
+    /** Email addresses that accepted the message */
     accepted: string[];
+    /** Email addresses that rejected the message */
     rejected: string[];
 }
 /**
- * Interfaz base para servicio de email
+ * Email service interface for sending emails.
  */
 interface BaseMailService {
+    /** Sends an email. Returns null if mail service is not configured */
     send(options: SendMailOptions): Promise<SendMailResult | null>;
+    /** Verifies SMTP connection is working */
     verify(): Promise<boolean>;
 }
 /**
- * Servicios core disponibles en ctx.services
- * Los plugins pueden extender con servicios adicionales
+ * Core services available via ctx.services.
+ *
+ * Modules can extend this with additional services.
  */
 interface CoreServices {
+    /** Error logging and reporting service */
     logger?: LoggerReporter;
+    /** User management service */
     users?: BaseUsersService;
+    /** Email sending service */
     mail?: BaseMailService;
+    /** Extensible: additional services registered by modules */
     [key: string]: unknown;
 }
 /**
- * Interfaz base para todos los servicios de entidades
+ * Base interface for all entity services.
+ *
+ * Provides read operations common to all entity types.
  */
 interface BaseEntityService<T = unknown> {
+    /** Gets paginated list of records with optional filtering/sorting */
     findAll(query?: EntityQuery): Promise<PaginatedResult<T>>;
+    /** Gets a single record by ID. Returns null if not found */
     findById(id: string): Promise<T | null>;
+    /** The entity definition this service operates on */
     readonly definition: EntityDefinition;
 }
 /**
- * Servicio para entidades Collection (CRUD completo)
+ * Service for Collection entities with full CRUD operations.
+ *
+ * @see {@link CollectionEntityDefinition}
  */
 interface CollectionEntityService<T = unknown> extends BaseEntityService<T> {
+    /** Creates a new record. userId is used for audit fields */
     create(data: Partial<T>, userId?: string): Promise<T>;
+    /** Updates an existing record by ID */
     update(id: string, data: Partial<T>, userId?: string): Promise<T>;
+    /** Deletes a record by ID (soft delete if configured) */
     delete(id: string): Promise<void>;
 }
 /**
- * Servicio para entidades Temp (TTL auto-cleanup)
+ * Service for Temp entities with automatic TTL expiration.
+ *
+ * @see {@link TempEntityDefinition}
  */
 interface TempEntityService<T = unknown> extends BaseEntityService<T> {
+    /** Creates a temporary record with automatic expiration */
     create(data: Partial<T>): Promise<T>;
+    /** Updates a record. Optionally extends TTL from current time */
     update(id: string, data: Partial<T>, extendTtl?: boolean): Promise<T>;
+    /** Deletes a record immediately */
     delete(id: string): Promise<void>;
+    /** Extends the TTL of a record by additional seconds */
     extendTtl(id: string, additionalSeconds?: number): Promise<T>;
+    /** Removes all expired records. Returns count of deleted records */
     cleanup(): Promise<number>;
+    /** Gets remaining TTL in seconds. Returns null if expired or not found */
     getRemainingTtl(id: string): Promise<number | null>;
+    /** Checks if a record exists and hasn't expired */
     isValid(id: string): Promise<boolean>;
 }
 /**
- * Servicio para entidades Event (append-only, immutable)
+ * Service for Event entities (append-only audit logs).
+ *
+ * @see {@link EventEntityDefinition}
  */
 interface EventEntityService<T = unknown> extends BaseEntityService<T> {
+    /** Creates a new event record (append-only) */
     create(data: Partial<T>): Promise<T>;
+    /** Alias for create - appends a new event */
     append(data: Partial<T>): Promise<T>;
+    /** Runs retention policy cleanup. Returns count of deleted records */
     runRetentionCleanup(): Promise<number>;
+    /** Queries events within a date range */
     findByDateRange(start: Date, end: Date, query?: EntityQuery): Promise<PaginatedResult<T>>;
 }
 /**
- * Servicio para entidades Single (registro único, update/read)
+ * Service for Single entities (global configuration).
+ *
+ * @see {@link SingleEntityDefinition}
  */
 interface SingleEntityService<T = unknown> extends BaseEntityService<T> {
+    /** Gets the single record (creates with defaults if not exists) */
     get(): Promise<T | null>;
+    /** Updates the single record */
     update(data: Partial<T>, userId?: string): Promise<T>;
 }
 /**
- * Servicio para entidades Config (configuración clave-valor)
+ * Service for Config entities (scoped key-value configuration).
+ *
+ * @see {@link ConfigEntityDefinition}
  */
 interface ConfigEntityService<T = unknown> extends BaseEntityService<T> {
+    /** Gets configuration value by key */
     get(key: string): Promise<T | null>;
+    /** Sets configuration value for a key */
     set(key: string, value: unknown, userId?: string): Promise<T>;
+    /** Gets all configuration as key-value object */
     getAll(): Promise<Record<string, unknown>>;
 }
-/** Servicio para entidades Reference (lectura con join automático) */
+/**
+ * Service for Reference entities (read-only catalogs).
+ * @see {@link ReferenceEntityDefinition}
+ */
 type ReferenceEntityService<T = unknown> = BaseEntityService<T>;
-/** Servicio para entidades View (vista SQL, solo lectura) */
+/**
+ * Service for View entities (SQL views, read-only).
+ * @see {@link ViewEntityDefinition}
+ */
 type ViewEntityService<T = unknown> = BaseEntityService<T>;
-/** Servicio para entidades Computed (campos calculados, solo lectura) */
+/**
+ * Service for Computed entities (dynamically calculated data).
+ * @see {@link ComputedEntityDefinition}
+ */
 type ComputedEntityService<T = unknown> = BaseEntityService<T>;
-/** Servicio para entidades External (datos de API externa) */
+/**
+ * Service for External entities (external API data).
+ * @see {@link ExternalEntityDefinition}
+ */
 type ExternalEntityService<T = unknown> = BaseEntityService<T>;
-/** Servicio para entidades Virtual (orquestación de múltiples fuentes) */
+/**
+ * Service for Virtual entities (aggregated from multiple sources).
+ * @see {@link VirtualEntityDefinition}
+ */
 type VirtualEntityService<T = unknown> = BaseEntityService<T>;
 /**
- * Servicio para entidades Action (ejecutar acciones)
+ * Service for Action entities (command execution).
+ *
+ * @see {@link ActionEntityDefinition}
  */
 interface ActionEntityService<T = unknown> {
+    /** Executes the action with provided input data */
     execute(data: Partial<T>): Promise<unknown>;
+    /** The action definition this service implements */
     readonly definition: EntityDefinition;
 }
 /**
- * Hooks para personalizar comportamiento de servicios de entidad
- * Permite a plugins añadir lógica sin necesitar herencia
+ * Hooks to customize entity service behavior.
+ * Allows plugins to add logic without inheritance.
  */
 interface EntityServiceHooks<T = unknown> {
     /**
-     * Ejecutado antes de crear un registro
-     * @param data Datos a insertar
-     * @returns Datos modificados
+     * Runs before creating a record.
+     * @param data Data to insert
+     * @returns Modified data
      */
     beforeCreate?: (data: Partial<T>) => Promise<Partial<T>> | Partial<T>;
     /**
-     * Ejecutado después de crear un registro
-     * @param record Registro creado
+     * Runs after creating a record.
+     * @param record Created record
      */
     afterCreate?: (record: T) => Promise<void> | void;
     /**
-     * Ejecutado antes de actualizar un registro
-     * @param id ID del registro
-     * @param data Datos a actualizar
-     * @returns Datos modificados
+     * Runs before updating a record.
+     * @param id Record ID
+     * @param data Data to update
+     * @returns Modified data
      */
     beforeUpdate?: (id: string, data: Partial<T>) => Promise<Partial<T>> | Partial<T>;
     /**
-     * Ejecutado después de actualizar un registro
-     * @param record Registro actualizado
+     * Runs after updating a record.
+     * @param record Updated record
      */
     afterUpdate?: (record: T) => Promise<void> | void;
     /**
-     * Ejecutado antes de eliminar un registro
-     * @param id ID del registro
+     * Runs before deleting a record.
+     * @param id Record ID
      */
     beforeDelete?: (id: string) => Promise<void> | void;
     /**
-     * Ejecutado después de eliminar un registro
-     * @param id ID eliminado
+     * Runs after deleting a record.
+     * @param id Deleted ID
      */
     afterDelete?: (id: string) => Promise<void> | void;
     /**
-     * Ejecutado después de obtener un registro por ID
-     * @param record Registro obtenido (o null)
-     * @returns Registro modificado
+     * Runs after getting a record by ID.
+     * @param record Retrieved record (or null)
+     * @returns Modified record
      */
     afterFindById?: (record: T | null) => Promise<T | null> | T | null;
     /**
-     * Ejecutado después de obtener lista paginada
-     * @param result Resultado paginado
-     * @returns Resultado modificado
+     * Runs after retrieving a paginated list.
+     * @param result Paginated result
+     * @returns Modified result
      */
     afterFindAll?: (result: PaginatedResult<T>) => Promise<PaginatedResult<T>> | PaginatedResult<T>;
 }
 /**
- * Opciones para createEntityService
+ * Options for createEntityService
  */
 interface CreateEntityServiceOptions<T = unknown> {
-    /** Hooks para personalizar comportamiento */
+    /** Hooks to customize behavior */
     hooks?: EntityServiceHooks<T>;
 }
 /**
- * Handler de entidad para Express
+ * Express route handler type for entity operations.
  */
 type EntityHandler = (req: Request, res: Response) => Promise<void>;
 /**
- * Controller de entidad con handlers CRUD
+ * Entity controller with CRUD operation handlers.
+ *
+ * Generated by `createEntityController` with built-in CASL authorization.
  */
 interface EntityController {
+    /** GET / - List all records with pagination */
     list: EntityHandler;
+    /** GET /:id - Get single record by ID */
     get: EntityHandler;
+    /** POST / - Create new record (collection entities) */
     create?: EntityHandler;
+    /** PUT /:id - Update existing record */
     update?: EntityHandler;
+    /** DELETE /:id - Delete record */
     delete?: EntityHandler;
+    /** POST /:id/:action - Execute entity action */
     execute?: EntityHandler;
 }
 /**
- * Contexto inyectado a los módulos
+ * Module context providing access to all Nexus services and utilities.
+ *
+ * Injected into module lifecycle functions (init, routes, migrate, seed).
+ *
+ * @example
+ * ```typescript
+ * const myModule: ModuleManifest = {
+ *   name: 'my-module',
+ *   routes: (ctx) => {
+ *     const router = ctx.createRouter()
+ *     router.get('/hello', (req, res) => res.json({ message: 'Hello!' }))
+ *     return router
+ *   }
+ * }
+ * ```
  */
 interface ModuleContext {
+    /** Knex database connection for queries and transactions */
     db: Knex;
+    /** Pino logger instance for structured logging */
     logger: Logger;
+    /** Helper utilities for migrations and common operations */
     helpers: ContextHelpers;
-    /** Utilidades criptográficas (hashPassword, verifyPassword) */
+    /** Cryptographic utilities (password hashing) */
     crypto: ContextCrypto;
-    /** API de Socket.IO para comunicación en tiempo real */
+    /** Socket.IO API for real-time communication */
     socket: ContextSocket;
-    /** API del Engine para introspección de módulos y plugins */
+    /** Engine API for module/plugin introspection */
     engine: ContextEngine;
+    /** Factory for creating Express routers */
     createRouter: () => Router;
+    /** Middleware factories (validate, rateLimit, etc.) */
     middleware: ModuleMiddlewares;
-    /** Configuración resuelta de la aplicación */
+    /** Resolved application configuration from env and config files */
     config: Record<string, unknown>;
+    /** HTTP error constructors for consistent error responses */
     errors: {
+        /** Generic application error with status code */
         AppError: new (message: string, statusCode?: number, details?: unknown) => Error & {
             details?: unknown;
         };
+        /** 404 Not Found error */
         NotFoundError: new (message?: string) => Error;
+        /** 401 Unauthorized error */
         UnauthorizedError: new (message?: string) => Error;
+        /** 403 Forbidden error */
         ForbiddenError: new (message?: string) => Error;
+        /** 409 Conflict error */
         ConflictError: new (message?: string) => Error;
-        ValidationError: new (message?: string, errors?: unknown[]) => Error & {
-            errors: unknown[];
+        /** 400 Validation error with field details */
+        ValidationError: new (message?: string, details?: ValidationDetail[]) => Error & {
+            details: ValidationDetail[];
         };
     };
+    /** CASL abilities API for authorization */
     abilities: ModuleAbilities;
-    /** Sistema de eventos compatible con EventEmitter2 */
+    /** Event emitter for inter-module communication */
     events: EventEmitterLike;
-    /** Servicios de módulos (inyectados por backend) */
+    /** Core services (users, mail, logger) */
     services: CoreServices;
-    /** Factory para crear servicios de entidades (detecta tipo automáticamente) */
+    /** Creates entity service based on definition type (auto-detects) */
     createEntityService<T = unknown>(definition: EntityDefinition, options?: CreateEntityServiceOptions<T>): BaseEntityService<T>;
-    /** Factory para crear controller de entidad con CASL y validación */
+    /** Creates entity controller with CASL authorization and validation */
     createEntityController(service: BaseEntityService, definition: EntityDefinition): EntityController;
-    /** Factory para crear router de entidad con rutas CRUD */
+    /** Creates Express router with standard CRUD routes */
     createEntityRouter(controller: EntityController, definition: EntityDefinition): Router;
 }
 /**
- * Manifest de un módulo Nexus
+ * Module manifest defining a Nexus module.
+ *
+ * Modules are the core building blocks of Nexus applications.
+ * Each module can define entities, routes, migrations, and services.
+ *
+ * @example
+ * ```typescript
+ * const postsModule: ModuleManifest = {
+ *   name: 'posts',
+ *   label: { en: 'Posts', es: 'Publicaciones' },
+ *   icon: 'mdi:post',
+ *   category: 'content',
+ *   definitions: [postsEntity, categoriesEntity],
+ *   routes: (ctx) => {
+ *     const router = ctx.createRouter()
+ *     // Custom routes here
+ *     return router
+ *   }
+ * }
+ * ```
  */
 interface ModuleManifest {
-    /** Identificador único del módulo (ej: 'users', 'posts') */
+    /** Unique module identifier (e.g., 'users', 'posts', 'cms') */
     name: string;
-    /** Nombre para mostrar en UI. Opcional si pertenece a un plugin */
-    label?: string;
-    /** Icono del módulo (Iconify MDI: 'mdi:account-group') */
+    /** Display name for UI (singular). Optional if module belongs to a plugin */
+    label?: LocalizedString;
+    /** Display name for UI (plural, used in menus and lists) */
+    labelPlural?: LocalizedString;
+    /** Iconify MDI icon identifier (e.g., 'mdi:account-group') */
     icon?: string;
-    /** Descripción del módulo */
-    description?: string;
-    /** Tipo de módulo */
+    /** Module description for documentation */
+    description?: LocalizedString;
+    /** Module type: 'core' (built-in), 'plugin' (from plugin), 'auth-plugin', or 'custom' */
     type?: 'core' | 'plugin' | 'auth-plugin' | 'custom';
-    /** Categoría del módulo para agrupar en sidebar */
+    /** Category for sidebar grouping */
     category: Category;
-    /** Dependencias de otros módulos */
+    /** Other module names that must be loaded before this one */
     dependencies?: string[];
-    /** Requisitos para activar el módulo */
+    /** Requirements that must be met to enable this module */
     required?: ModuleRequirements;
-    /** Función de migración de base de datos. Normalmente se genera desde definitions (EntityDefinition) */
+    /** Database migration function. Usually auto-generated from entity definitions */
     migrate?: (ctx: ModuleContext) => Promise<void>;
-    /** Función de seed de datos iniciales */
+    /** Seed function for initial/reference data */
     seed?: (ctx: ModuleContext) => Promise<void>;
-    /** Inicialización del módulo */
+    /** Initialization function called on app startup */
     init?: (ctx: ModuleContext) => void;
-    /** Factory de rutas del módulo */
+    /** Factory function returning Express router with custom routes */
     routes?: (ctx: ModuleContext) => Router;
-    /** Prefijo de rutas (default: /{name}) */
+    /** API route prefix. Default: `/{name}` */
     routePrefix?: string;
-    /**
-     * Definiciones de entidades (nuevo sistema unificado).
-     * Single source of truth para BD, validación, UI y CASL.
-     * Sus subjects se registran automáticamente.
-     */
+    /** Entity definitions - single source of truth for DB, validation, UI, and CASL */
     definitions?: EntityDefinition[];
 }
 /**
- * Categorías disponibles para plugins y módulos
+ * Available categories for organizing modules in the UI sidebar.
+ *
+ * @see {@link CATEGORIES} for metadata (labels, icons, order)
  */
-type Category = 'content' | 'data' | 'storage' | 'messaging' | 'jobs' | 'ai' | 'analytics' | 'integrations' | 'commerce' | 'security';
+type Category = 'content' | 'data' | 'assets' | 'messaging' | 'jobs' | 'ai' | 'analytics' | 'integrations' | 'commerce' | 'security' | 'legal' | 'settings';
 /**
- * Metadata de una categoría
+ * Metadata for a category including display information.
  */
 interface CategoryMeta {
-    label: string;
+    /** Localized display label */
+    label: LocalizedString;
+    /** Iconify MDI icon identifier */
     icon: string;
+    /** Sort order in sidebar (lower = first) */
     order: number;
 }
 /**
- * Registro centralizado de categorías con su metadata
+ * Registry of all categories with their metadata.
+ *
+ * Used by the UI to render the sidebar navigation.
  */
 declare const CATEGORIES: Record<Category, CategoryMeta>;
 /**
- * Orden de categorías para sidebar (derivado de CATEGORIES)
+ * Categories sorted by their display order for sidebar rendering.
  */
 declare const CATEGORY_ORDER: Category[];
 /**
- * Manifest de un plugin Nexus
+ * Plugin manifest defining a distributable Nexus plugin package.
+ *
+ * Plugins bundle one or more modules into a reusable package.
+ * Distributed via npm (e.g., @gzl10/nexus-plugin-cms).
+ *
+ * @example
+ * ```typescript
+ * const cmsPlugin: PluginManifest = {
+ *   name: '@gzl10/nexus-plugin-cms',
+ *   code: 'CMS',
+ *   label: { en: 'CMS', es: 'CMS' },
+ *   category: 'content',
+ *   version: '1.0.0',
+ *   description: { en: 'Content Management System', es: 'Sistema de Gestión de Contenidos' },
+ *   modules: [postsModule, categoriesModule, tagsModule]
+ * }
+ * ```
  */
 interface PluginManifest {
-    /** Nombre del plugin (normalmente el nombre del paquete npm) */
+    /** Plugin npm package name (e.g., '@gzl10/nexus-plugin-cms') */
     name: string;
-    /** Código del plugin (3-4 chars UPPERCASE). Se hereda a todos los módulos */
+    /** Short code prefix for tables (3-4 uppercase chars, e.g., 'CMS'). Applied to all modules */
     code: string;
-    /** Etiqueta para mostrar en UI. Se hereda a los módulos si no la definen */
-    label: string;
-    /** Icono del plugin (Iconify MDI). Se hereda a los módulos si no lo definen */
+    /** Display label (singular). Inherited by modules without explicit label */
+    label: LocalizedString;
+    /** Display label (plural, for menus) */
+    labelPlural?: LocalizedString;
+    /** Iconify MDI icon. Inherited by modules without explicit icon */
     icon?: string;
-    /** Categoría del plugin para agrupar en sidebar */
+    /** Category for sidebar grouping. Inherited by modules without explicit category */
     category: Category;
-    /** Versión del plugin (semver) */
+    /** Plugin version following SemVer (e.g., '1.0.0') */
     version: string;
-    /** Descripción del plugin */
-    description: string;
-    /** Módulos incluidos en el plugin */
+    /** Plugin description for documentation */
+    description: LocalizedString;
+    /** Modules bundled in this plugin */
     modules: ModuleManifest[];
 }
+/**
+ * Serializable field definition for API responses.
+ *
+ * Unlike {@link FieldDefinition}, this contains no functions (ConditionalBoolean
+ * resolved to static boolean). Some fields may be omitted for security.
+ *
+ * @see {@link FieldDefinition} for the full server-side definition
+ */
+interface FieldDefinitionDTO {
+    /** Field identifier */
+    name: string;
+    /** Display label */
+    label: LocalizedString;
+    /** Input type for form rendering */
+    input: InputType;
+    /** Placeholder text */
+    placeholder?: LocalizedString;
+    /** Help text */
+    hint?: LocalizedString;
+    /** Whether field is hidden (resolved from ConditionalBoolean) */
+    hidden?: boolean;
+    /** Whether field is disabled (resolved from ConditionalBoolean) */
+    disabled?: boolean;
+    /** Whether field is required (resolved from ConditionalBoolean) */
+    required?: boolean;
+    /** Default value for form creation */
+    defaultValue?: unknown;
+    /** Database config (may be partially omitted for security) */
+    db?: {
+        type: string;
+        nullable?: boolean;
+        default?: unknown;
+        unique?: boolean;
+        index?: boolean;
+    };
+    /** Relationship config (table name may be omitted for security) */
+    relation?: {
+        table?: string;
+        column?: string;
+        labelField?: string;
+        onDelete?: string;
+    };
+    /** Validation rules */
+    validation?: {
+        min?: number;
+        max?: number;
+        pattern?: string;
+        format?: string;
+        enum?: string[];
+    };
+    /** Select/dropdown options configuration */
+    options?: {
+        endpoint?: string;
+        valueField?: string;
+        labelField?: string;
+        static?: Array<{
+            value: string;
+            label: LocalizedString;
+        }>;
+        allowCreate?: boolean;
+    };
+    /** Storage configuration for file uploads */
+    storage?: {
+        accept?: string;
+        maxSize?: number;
+        maxFiles?: number;
+        folder?: string;
+        thumbnails?: Array<{
+            width: number;
+            height: number;
+        }>;
+        dedupe?: boolean;
+    };
+    /** Field metadata */
+    meta?: FieldMeta;
+    /** Props for input components */
+    inputProps?: Record<string, unknown>;
+    /** Props for display components */
+    displayProps?: Record<string, unknown>;
+}
+/**
+ * Serializable entity definition for API responses.
+ *
+ * Flattened structure without discriminated union.
+ * Sensitive information may be omitted for security.
+ *
+ * @see {@link EntityDefinition} for the full server-side definition
+ */
+interface EntityDefinitionDTO {
+    /** Unique entity identifier (auto-generated at registration) */
+    id: string;
+    /** Table name (may be omitted for security) */
+    table?: string;
+    /** Key for single entities */
+    key?: string;
+    /** Entity type */
+    type: EntityType;
+    /** Display label (singular) */
+    label: LocalizedString;
+    /** Display label (plural) */
+    labelPlural?: LocalizedString;
+    /** Field used as display label */
+    labelField?: string;
+    /** Iconify icon */
+    icon?: string;
+    /** API route prefix */
+    routePrefix?: string;
+    /** UI sort order */
+    order?: number;
+    /** Field definitions */
+    fields: Record<string, FieldDefinitionDTO>;
+    /** Total field count */
+    fieldsCount: number;
+    /** Has created_at/updated_at columns */
+    hasTimestamps: boolean;
+    /** Has created_by/updated_by columns */
+    hasAudit: boolean;
+    /** CASL subject name */
+    caslSubject?: string;
+    /** Returns single record instead of array */
+    isSingle?: boolean;
+    /** UI display mode */
+    displayMode?: DisplayMode;
+    /** Show create button in UI */
+    allowCreate?: boolean;
+    /** Allow editing in UI */
+    allowEdit?: boolean;
+    /** Hidden from UI sidebar */
+    hidden?: boolean;
+}
+/**
+ * Serializable module for API responses.
+ */
+interface ModuleDTO {
+    /** Module identifier */
+    name: string;
+    /** Display label */
+    label: LocalizedString;
+    /** Display label (plural) */
+    labelPlural?: LocalizedString;
+    /** Iconify icon */
+    icon?: string;
+    /** Module description */
+    description?: LocalizedString;
+    /** Module type */
+    type: string;
+    /** Sidebar category */
+    category?: Category;
+    /** Module dependencies */
+    dependencies: string[];
+    /** API route prefix */
+    routePrefix: string;
+    /** CASL subjects defined by this module */
+    subjects: string[];
+    /** Entity definitions */
+    definitions: EntityDefinitionDTO[];
+    /** Has custom routes */
+    hasRoutes: boolean;
+    /** Has migrations */
+    hasMigrate: boolean;
+    /** Has seed data */
+    hasSeed: boolean;
+    /** Has init function */
+    hasInit: boolean;
+}
+/**
+ * Serializable plugin for API responses.
+ */
+interface PluginDTO {
+    /** Plugin package name */
+    name: string;
+    /** Plugin code prefix */
+    code: string;
+    /** Display label */
+    label: LocalizedString;
+    /** Display label (plural) */
+    labelPlural?: LocalizedString;
+    /** Iconify icon */
+    icon?: string;
+    /** Sidebar category */
+    category?: Category;
+    /** Plugin version */
+    version: string;
+    /** Plugin description */
+    description: LocalizedString;
+    /** Modules in this plugin */
+    modules: ModuleDTO[];
+}
+/**
+ * Application manifest DTO (core or user app).
+ */
+interface ManifestDTO {
+    /** Application name */
+    name: string;
+    /** Application version */
+    version: string;
+    /** Registered modules */
+    modules: ModuleDTO[];
+    /** Registered plugins */
+    plugins?: PluginDTO[];
+}
+/**
+ * Combined manifest DTO with both core and user manifests.
+ */
+interface CombinedManifestDTO {
+    /** Core nexus-backend manifest */
+    core: ManifestDTO;
+    /** User project manifest (null in standalone mode) */
+    user: ManifestDTO | null;
+    /** Whether running with a user project */
+    hasUserApp: boolean;
+}
 
-export { type AbilityLike, type ActionEntityDefinition, type ActionEntityService, type AuthRequest, type BaseEntityService, type BaseMailService, type BaseRolesService, type BaseUser, type BaseUsersService, CATEGORIES, CATEGORY_ORDER, type CaslAction, type Category, type CategoryMeta, type CollectionEntityDefinition, type CollectionEntityService, type ComputedEntityDefinition, type ComputedEntityService, type ConfigEntityDefinition, type ConfigEntityService, type ContextCrypto, type ContextEngine, type ContextHelpers, type ContextSocket, type CoreServices, type CreateEntityServiceOptions, type DbType, type EntityAction, type EntityCaslConfig, type EntityController, type EntityDefinition, type EntityHandler, type EntityIndex, type EntityQuery, type EntityServiceHooks, type EntityType, type EventEmitterLike, type EventEntityDefinition, type EventEntityService, type ExternalEntityDefinition, type ExternalEntityService, type FieldCaslAccess, type FieldDbConfig, type FieldDefinition, type FieldMeta, type FieldOptions, type FieldRelation, type FieldStorageConfig, type FieldValidationConfig, type ForbiddenErrorConstructor, type ForbiddenErrorInstance, type InputType, type KnexAlterTableBuilder, type KnexCreateTableBuilder, type KnexTransaction, type LoggerReporter, type ModuleAbilities, type ModuleContext, type ModuleManifest, type ModuleMiddlewares, type ModuleRequirements, type NonPersistentEntityDefinition, type OwnershipCondition, type PaginatedResult, type PaginationParams, type PersistentEntityDefinition, type PluginAuthRequest, type PluginManifest, type ReferenceEntityDefinition, type ReferenceEntityService, type RolePermission, type SendMailOptions, type SendMailResult, type SingleEntityDefinition, type SingleEntityService, type TempEntityDefinition, type TempEntityService, type ValidateSchemas, type ValidationSchema, type ViewEntityDefinition, type ViewEntityService, type VirtualEntityDefinition, type VirtualEntityService, getEntityName, getEntitySubject, hasTable, isPersistentEntity, isSingletonEntity };
+export { type AbilityLike, type ActionEntityDefinition, type ActionEntityService, type AppManifest, type AuthRequest, type BaseAuthRequest, type BaseEntityService, type BaseMailService, type BaseRolesService, type BaseUser, type BaseUsersService, CATEGORIES, CATEGORY_ORDER, type CaslAction, type Category, type CategoryMeta, type CollectionEntityDefinition, type CollectionEntityService, type CombinedManifestDTO, type ComputedEntityDefinition, type ComputedEntityService, type ConditionalBoolean, type ConfigEntityDefinition, type ConfigEntityService, type ContextCrypto, type ContextEngine, type ContextHelpers, type ContextSocket, type CoreServices, type CreateEntityServiceOptions, type DbType, type DisplayMode, type EntityAction, type EntityCaslConfig, type EntityController, type EntityDefinition, type EntityDefinitionDTO, type EntityHandler, type EntityIndex, type EntityQuery, type EntityServiceHooks, type EntityType, type EventEmitterLike, type EventEntityDefinition, type EventEntityService, type ExternalEntityDefinition, type ExternalEntityService, type FieldDbConfig, type FieldDefinition, type FieldDefinitionDTO, type FieldMeta, type FieldOptions, type FieldRelation, type FieldStorageConfig, type FieldValidationConfig, type FilterOperators, type FilterValue, type ForbiddenErrorConstructor, type ForbiddenErrorInstance, type InputType, type KnexAlterTableBuilder, type KnexCreateTableBuilder, type KnexTransaction, type LocalizedString, type LoggerReporter, type ManifestDTO, type ModuleAbilities, type ModuleContext, type ModuleDTO, type ModuleManifest, type ModuleMiddlewares, type ModuleRequirements, type NonPersistentEntityDefinition, type OwnershipCondition, type PaginatedResult, type PaginationParams, type PersistentEntityDefinition, type PluginDTO, type PluginManifest, type RateLimitOptions, type ReferenceEntityDefinition, type ReferenceEntityService, type RolePermission, type SendMailOptions, type SendMailResult, type SingleEntityDefinition, type SingleEntityService, type TempEntityDefinition, type TempEntityService, type ValidateSchemas, type ValidationDetail, type ValidationSchema, type ViewEntityDefinition, type ViewEntityService, type VirtualEntityDefinition, type VirtualEntityService, getCountLabel, getEntityName, getEntitySubject, hasTable, isPersistentEntity, isSingletonEntity, resolveLocalized };