theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-mysql/SKILL.md

@@ -0,0 +1,420 @@
+---
+name: patrones-mysql
+description: Patrones de esquema, consultas, indexación, transacciones, replicación y pools de conexiones para MySQL y MariaDB en backends de producción.
+---
+
+# Patrones de MySQL
+
+Usa esta skill al trabajar en diseño de esquemas de MySQL o MariaDB, migraciones,
+investigación de consultas lentas, transacciones de tipo cola, pools de conexiones
+o configuración de bases de datos en producción. Prefiere comprobaciones exactas de
+versión antes de aplicar un patrón específico de una funcionalidad, porque MySQL y
+MariaDB han divergido en varios detalles de SQL.
+
+## Activación
+
+- Diseñar tablas, índices y constraints de MySQL o MariaDB
+- Revisar migraciones antes de ejecutarlas sobre tablas grandes de producción
+- Depurar consultas lentas, esperas de locks, deadlocks o agotamiento de conexiones
+- Añadir paginación por keyset, upserts, búsqueda full-text, columnas JSON o colas
+- Configurar pools de conexiones de la aplicación, réplicas de lectura, TLS o logs de consultas lentas
+
+## Comprobación de versión
+
+Empieza identificando el motor y la versión:
+
+```sql
+SELECT VERSION();
+SHOW VARIABLES LIKE 'version_comment';
+```
+
+Mantén separadas las recomendaciones de MySQL y MariaDB cuando la sintaxis difiere:
+
+- MySQL documenta los alias de fila como el reemplazo de `VALUES(col)` en
+  `ON DUPLICATE KEY UPDATE`; `VALUES(col)` está deprecado ahí.
+- MariaDB documenta `VALUES(col)` como la forma soportada de referenciar los
+  valores insertados en `ON DUPLICATE KEY UPDATE`; úsalo para compatibilidad
+  entre motores.
+- `SKIP LOCKED` es apropiado solo para trabajo de tipo cola. Salta las filas
+  bloqueadas y puede devolver una vista inconsistente, así que no lo uses para
+  lecturas contables generales ni sensibles a la integridad.
+
+## Valores por defecto de esquema
+
+```sql
+CREATE TABLE orders (
+    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    account_id BIGINT UNSIGNED NOT NULL,
+    status VARCHAR(32) NOT NULL,
+    total DECIMAL(15, 2) NOT NULL,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    deleted_at DATETIME NULL,
+    PRIMARY KEY (id),
+    KEY idx_orders_account_status_created (account_id, status, created_at),
+    KEY idx_orders_active (account_id, deleted_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+```
+
+Elecciones por defecto:
+
+| Caso de uso | Prefiere | Evita |
+| --- | --- | --- |
+| Claves primarias sustitutas | `BIGINT UNSIGNED AUTO_INCREMENT` | `INT` en tablas que pueden superar 2 000 millones de filas |
+| Claves de búsqueda UUID | `BINARY(16)` con helpers de conversión | Claves primarias `VARCHAR(36)` en tablas calientes |
+| Dinero y cantidades exactas | `DECIMAL(p, s)` | `FLOAT` o `DOUBLE` |
+| Texto visible al usuario | Tablas e índices en `utf8mb4` | Los defaults `utf8` / `utf8mb3` de MySQL |
+| Timestamps de aplicación | `DATETIME` con UTC gestionado por la app | Suponer que `DATETIME` guarda metadatos de zona horaria |
+| Borrados lógicos | `deleted_at DATETIME NULL` más índices acotados | Filtrar filas borradas lógicamente sin índice |
+| Valores de estado extensibles | Tabla de catálogo o `VARCHAR` restringido | `ENUM` cuando los valores cambian a menudo |
+
+## Indexación
+
+El orden de un índice compuesto normalmente sigue primero los predicados de
+igualdad y luego las columnas de rango u ordenación:
+
+```sql
+CREATE INDEX idx_orders_account_status_created
+    ON orders (account_id, status, created_at);
+
+SELECT id, total
+FROM orders
+WHERE account_id = ?
+  AND status = 'pending'
+  AND created_at >= ?
+ORDER BY created_at DESC
+LIMIT 50;
+```
+
+Usa `EXPLAIN` antes de añadir o cambiar un índice:
+
+```sql
+EXPLAIN
+SELECT id, total
+FROM orders
+WHERE account_id = 123 AND status = 'pending'
+ORDER BY created_at DESC
+LIMIT 50;
+```
+
+Señales que conviene investigar:
+
+| Campo | Señal de riesgo |
+| --- | --- |
+| `type` | `ALL` en una tabla grande |
+| `key` | `NULL` cuando existe un predicado selectivo |
+| `rows` | Estimación de filas muy alta en una ruta interactiva |
+| `Extra` | `Using temporary`, `Using filesort` o un `Using where` amplio |
+
+Evita añadir índices a ciegas. Cada índice incrementa el costo de escritura, el
+tiempo de migración, el tamaño de los backups y la presión sobre el buffer pool.
+
+## Patrones de consulta
+
+### Upsert
+
+Forma compatible entre motores:
+
+```sql
+INSERT INTO user_settings (user_id, setting_key, setting_value)
+VALUES (?, ?, ?)
+ON DUPLICATE KEY UPDATE
+    setting_value = VALUES(setting_value),
+    updated_at = CURRENT_TIMESTAMP;
+```
+
+Forma con alias de fila de MySQL:
+
+```sql
+INSERT INTO user_settings (user_id, setting_key, setting_value)
+VALUES (?, ?, ?) AS new
+ON DUPLICATE KEY UPDATE
+    setting_value = new.setting_value,
+    updated_at = CURRENT_TIMESTAMP;
+```
+
+Usa la forma con alias de fila solo tras confirmar que el destino es MySQL. Usa
+`VALUES(col)` para MariaDB o flotas mixtas MySQL/MariaDB.
+
+### Paginación por keyset
+
+```sql
+SELECT id, name, created_at
+FROM products
+WHERE (created_at, id) < (?, ?)
+ORDER BY created_at DESC, id DESC
+LIMIT 50;
+```
+
+Respáldala con un índice que coincida con el cursor:
+
+```sql
+CREATE INDEX idx_products_created_id ON products (created_at, id);
+```
+
+No uses paginación con `OFFSET` profundo en tablas grandes; obliga al servidor a
+escanear y descartar filas antes de devolver la página.
+
+### Campos JSON
+
+Usa columnas JSON para datos de extensión, no para campos que necesiten
+filtrado relacional intensivo o constraints.
+
+```sql
+CREATE TABLE events (
+    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+    payload JSON NOT NULL,
+    event_type VARCHAR(64)
+        GENERATED ALWAYS AS (JSON_UNQUOTE(JSON_EXTRACT(payload, '$.type'))) STORED,
+    KEY idx_events_type (event_type)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+Para rutas JSON consultadas con frecuencia, expón una columna generada e indexa
+esa columna. Mantén relacionales las claves foráneas, la propiedad, la
+multitenencia y los campos de ciclo de vida.
+
+### Búsqueda full-text
+
+```sql
+ALTER TABLE articles ADD FULLTEXT KEY ft_articles_title_body (title, body);
+
+SELECT id, title, MATCH(title, body) AGAINST (? IN NATURAL LANGUAGE MODE) AS score
+FROM articles
+WHERE MATCH(title, body) AGAINST (? IN NATURAL LANGUAGE MODE)
+ORDER BY score DESC
+LIMIT 20;
+```
+
+Usa un buscador externo cuando necesites tolerancia a errores tipográficos,
+ranking complejo, facetas entre tablas o análisis específico por idioma más allá
+del comportamiento full-text integrado.
+
+## Transacciones
+
+Mantén las transacciones cortas y bloquea las filas en un orden consistente:
+
+```sql
+START TRANSACTION;
+
+SELECT id, balance
+FROM accounts
+WHERE id IN (?, ?)
+ORDER BY id
+FOR UPDATE;
+
+UPDATE accounts SET balance = balance - ? WHERE id = ?;
+UPDATE accounts SET balance = balance + ? WHERE id = ?;
+
+COMMIT;
+```
+
+Lista de verificación para deadlocks y esperas de locks:
+
+- Bloquea las filas en un orden determinista en todas las rutas de código.
+- Haz las llamadas a APIs externas antes de abrir la transacción, no dentro de ella.
+- Añade índices para los predicados usados en `UPDATE`, `DELETE` y lecturas con lock.
+- Ante un deadlock, haz rollback y reintenta la transacción completa con un
+  presupuesto de reintentos acotado.
+- Captura `SHOW ENGINE INNODB STATUS\G` poco después de un deadlock; los eventos
+  posteriores lo sobrescriben.
+
+Reclamo de trabajo estilo cola:
+
+```sql
+START TRANSACTION;
+
+SELECT id
+FROM jobs
+WHERE status = 'pending'
+ORDER BY created_at
+LIMIT 1
+FOR UPDATE SKIP LOCKED;
+
+UPDATE jobs
+SET status = 'processing', started_at = CURRENT_TIMESTAMP
+WHERE id = ?;
+
+COMMIT;
+```
+
+Usa `SKIP LOCKED` solo para cargas de tipo cola donde saltar una fila bloqueada
+sea aceptable. No es un reemplazo de la consistencia transaccional normal.
+
+## Pools de conexiones
+
+Ejemplo con SQLAlchemy:
+
+```python
+from sqlalchemy import create_engine
+
+engine = create_engine(
+    "mysql+mysqlconnector://app:secret@db.internal/app",
+    pool_size=10,
+    max_overflow=5,
+    pool_timeout=30,
+    pool_recycle=240,
+    pool_pre_ping=True,
+    connect_args={"connect_timeout": 5},
+)
+```
+
+Ejemplo con `mysql2` en Node.js:
+
+```javascript
+import mysql from 'mysql2/promise';
+
+const pool = mysql.createPool({
+  host: process.env.DB_HOST,
+  user: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+  database: process.env.DB_NAME,
+  waitForConnections: true,
+  connectionLimit: 10,
+  queueLimit: 0,
+  enableKeepAlive: true,
+  keepAliveInitialDelay: 30000,
+});
+
+const [rows] = await pool.execute(
+  'SELECT id, total FROM orders WHERE account_id = ? LIMIT 50',
+  [accountId],
+);
+```
+
+Mantén el reciclado del pool de la aplicación por debajo del `wait_timeout` del
+servidor. Si el servidor usa `wait_timeout = 300`, un `pool_recycle` en torno a
+240 segundos es coherente; `pool_pre_ping` ayuda igualmente a recuperarse de
+eventos de red y de failover.
+
+## Diagnóstico
+
+Comandos útiles de primera pasada:
+
+```sql
+SHOW FULL PROCESSLIST;
+SHOW ENGINE INNODB STATUS\G;
+SHOW VARIABLES LIKE 'slow_query_log';
+SHOW VARIABLES LIKE 'long_query_time';
+```
+
+Activa el slow log en un entorno controlado:
+
+```sql
+SET GLOBAL slow_query_log = 'ON';
+SET GLOBAL long_query_time = 1;
+SET GLOBAL log_queries_not_using_indexes = 'ON';
+```
+
+Usa `EXPLAIN ANALYZE` solo cuando sea seguro ejecutar la consulta. Ejecuta la
+sentencia y puede ser costoso sobre datos de tamaño de producción.
+
+## Replicación
+
+Las réplicas de lectura pueden retrasarse. No enrutes a una réplica, justo
+después de una escritura, los flujos de leer-tu-propia-escritura, los flujos de
+checkout, las comprobaciones de permisos ni las lecturas de claves de
+idempotencia.
+
+```sql
+-- Terminología heredada de MySQL, aún común en flotas existentes
+SHOW SLAVE STATUS\G;
+
+-- Terminología más nueva donde esté soportada
+SHOW REPLICA STATUS\G;
+```
+
+Comprueba el motor/versión antes de estandarizar un comando. Monitorea la salud
+del hilo SQL de la réplica, la salud del hilo de IO y el lag, no solo si la
+conexión TCP sigue viva.
+
+## Seguridad
+
+```sql
+CREATE USER 'app'@'%' IDENTIFIED BY 'usa-un-gestor-de-secretos';
+GRANT SELECT, INSERT, UPDATE, DELETE ON appdb.* TO 'app'@'%';
+
+ALTER USER 'app'@'%' REQUIRE SSL;
+
+SELECT user, host
+FROM mysql.user
+WHERE user = '';
+
+DROP USER IF EXISTS ''@'localhost';
+DROP USER IF EXISTS ''@'%';
+```
+
+Puntos de revisión de seguridad:
+
+- No concedas `ALL PRIVILEGES` ni `*.*` a usuarios de aplicación.
+- Exige TLS a los usuarios de aplicación cuando el tráfico cruce hosts o redes.
+- Guarda las credenciales en el gestor de secretos de la plataforma, no en
+  ejemplos, scripts ni archivos del repositorio.
+- Separa los usuarios de migración/administración de los usuarios de runtime de
+  la aplicación.
+- Audita la exposición a redes públicas y las direcciones de bind antes de
+  ajustar el rendimiento.
+
+## Configuración
+
+Punto de partida de ejemplo para un host dedicado de base de datos:
+
+```ini
+[mysqld]
+innodb_buffer_pool_size = 4G
+innodb_flush_log_at_trx_commit = 1
+sync_binlog = 1
+
+max_connections = 300
+thread_cache_size = 50
+
+wait_timeout = 300
+interactive_timeout = 300
+innodb_lock_wait_timeout = 10
+
+slow_query_log = ON
+long_query_time = 1
+log_queries_not_using_indexes = ON
+
+log_bin = mysql-bin
+binlog_format = ROW
+binlog_expire_logs_seconds = 604800
+```
+
+Trata los valores de configuración como un punto de partida para revisión, no
+como un preset universal. Dimensiona la memoria, las conexiones, la retención de
+logs y los ajustes de durabilidad a partir de la carga de trabajo, el hardware,
+la política de backups y los objetivos de recuperación.
+
+## Antipatrones
+
+| Antipatrón | Riesgo | Patrón mejor |
+| --- | --- | --- |
+| `SELECT *` en rutas calientes | Sobre-lectura y clientes frágiles | Selecciona columnas explícitas |
+| Paginación con `OFFSET` profundo | Escaneos lineales y páginas lentas | Paginación por keyset |
+| Sin índice en joins por clave foránea | Joins lentos y deletes con muchos locks | Indexa las columnas FK de forma intencional |
+| Transacciones largas | Esperas de locks y gran historial de undo | Haz commit de unidades de trabajo pequeñas |
+| DML directo contra `mysql.user` | Riesgo de corrupción de las tablas de grants | Usa `CREATE USER`, `ALTER USER`, `DROP USER` |
+| Usuario de aplicación con grants de admin | Radio de impacto alto | Usuario de runtime con mínimo privilegio |
+| Reciclado del pool por encima de `wait_timeout` | Conexiones del pool obsoletas | Recicla por debajo del timeout y usa pre-ping |
+| Lecturas en réplica tras escrituras | Estado visible al usuario desactualizado | Fija los flujos de leer-tras-escribir al primario |
+
+## Expectativas de salida
+
+Cuando esta skill se use para revisión, devuelve:
+
+1. Supuestos de motor/versión.
+2. Los problemas de mayor riesgo de corrección, locks, seguridad y migración.
+3. Cambios exactos de SQL o de código para la ruta segura.
+4. Plan de validación: `EXPLAIN`, ensayo de la migración, verificación de
+   locks/deadlocks y criterios de rollback.
+5. Cualquier diferencia de sintaxis entre MySQL y MariaDB que afecte la
+   recomendación.
+
+## Relacionado
+
+- Skill: `patrones-postgres` — patrones de esquema y consultas específicos de PostgreSQL
+- Skill: `migraciones-bd` — planificación de migraciones y seguridad del despliegue
+- Skill: `patrones-backend` — patrones de API y de capa de servicio
+- Skill: `revision-seguridad` — manejo de secretos, autenticación y mínimo privilegio
+- Agente: `revisor-bd` — flujo más amplio de revisión de bases de datos

package/vendor/theus-arsenal/skills/patrones-nestjs/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: patrones-nestjs
+description: Patrones de arquitectura NestJS para módulos, controladores, providers, validación de DTOs, guards, interceptores, configuración y backends TypeScript de nivel productivo.
+---
+
+# Patrones de desarrollo con NestJS
+
+Patrones de NestJS de nivel productivo para backends TypeScript modulares.
+
+## Cuándo activarla
+
+- Al construir APIs o servicios con NestJS
+- Al estructurar módulos, controladores y providers
+- Al añadir validación de DTOs, guards, interceptores o filtros de excepciones
+- Al configurar ajustes por entorno e integraciones con bases de datos
+- Al testear unidades de NestJS o endpoints HTTP
+
+## Estructura del proyecto
+
+```text
+src/
+├── app.module.ts
+├── main.ts
+├── common/
+│   ├── filters/
+│   ├── guards/
+│   ├── interceptors/
+│   └── pipes/
+├── config/
+│   ├── configuration.ts
+│   └── validation.ts
+├── modules/
+│   ├── auth/
+│   │   ├── auth.controller.ts
+│   │   ├── auth.module.ts
+│   │   ├── auth.service.ts
+│   │   ├── dto/
+│   │   ├── guards/
+│   │   └── strategies/
+│   └── users/
+│       ├── dto/
+│       ├── entities/
+│       ├── users.controller.ts
+│       ├── users.module.ts
+│       └── users.service.ts
+└── prisma/ o database/
+```
+
+- Mantén el código de dominio dentro de módulos de funcionalidad.
+- Coloca filtros, decoradores, guards e interceptores transversales en `common/`.
+- Mantén los DTOs cerca del módulo que los posee.
+
+## Bootstrap y validación global
+
+```ts
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, { bufferLogs: true });
+
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,
+      forbidNonWhitelisted: true,
+      transform: true,
+      transformOptions: { enableImplicitConversion: true },
+    }),
+  );
+
+  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
+  app.useGlobalFilters(new HttpExceptionFilter());
+
+  await app.listen(process.env.PORT ?? 3000);
+}
+bootstrap();
+```
+
+- Habilita siempre `whitelist` y `forbidNonWhitelisted` en APIs públicas.
+- Prefiere un pipe de validación global en lugar de repetir la configuración de validación por ruta.
+
+## Módulos, controladores y providers
+
+```ts
+@Module({
+  controllers: [UsersController],
+  providers: [UsersService],
+  exports: [UsersService],
+})
+export class UsersModule {}
+
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Get(':id')
+  getById(@Param('id', ParseUUIDPipe) id: string) {
+    return this.usersService.getById(id);
+  }
+
+  @Post()
+  create(@Body() dto: CreateUserDto) {
+    return this.usersService.create(dto);
+  }
+}
+
+@Injectable()
+export class UsersService {
+  constructor(private readonly usersRepo: UsersRepository) {}
+
+  async create(dto: CreateUserDto) {
+    return this.usersRepo.create(dto);
+  }
+}
+```
+
+- Los controladores deben mantenerse delgados: parsear la entrada HTTP, llamar a un provider y devolver DTOs de respuesta.
+- Pon la lógica de negocio en servicios inyectables, no en controladores.
+- Exporta solo los providers que otros módulos genuinamente necesitan.
+
+## DTOs y validación
+
+```ts
+export class CreateUserDto {
+  @IsEmail()
+  email!: string;
+
+  @IsString()
+  @Length(2, 80)
+  name!: string;
+
+  @IsOptional()
+  @IsEnum(UserRole)
+  role?: UserRole;
+}
+```
+
+- Valida cada DTO de petición con `class-validator`.
+- Usa DTOs de respuesta dedicados o serializadores en lugar de devolver entidades del ORM directamente.
+- Evita filtrar campos internos como hashes de contraseñas, tokens o columnas de auditoría.
+
+## Autenticación, guards y contexto de la petición
+
+```ts
+@UseGuards(JwtAuthGuard, RolesGuard)
+@Roles('admin')
+@Get('admin/report')
+getAdminReport(@Req() req: AuthenticatedRequest) {
+  return this.reportService.getForUser(req.user.id);
+}
+```
+
+- Mantén las estrategias de auth y los guards locales al módulo salvo que sean realmente compartidos.
+- Codifica las reglas de acceso gruesas en guards, y haz la autorización específica por recurso en los servicios.
+- Prefiere tipos de petición explícitos para los objetos de petición autenticada.
+
+## Filtros de excepciones y forma del error
+
+```ts
+@Catch()
+export class HttpExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const response = host.switchToHttp().getResponse<Response>();
+    const request = host.switchToHttp().getRequest<Request>();
+
+    if (exception instanceof HttpException) {
+      return response.status(exception.getStatus()).json({
+        path: request.url,
+        error: exception.getResponse(),
+      });
+    }
+
+    return response.status(500).json({
+      path: request.url,
+      error: 'Error interno del servidor',
+    });
+  }
+}
+```
+
+- Mantén una envoltura de error consistente en toda la API.
+- Lanza excepciones del framework para los errores de cliente esperados; registra y envuelve los fallos inesperados de forma centralizada.
+
+## Configuración y validación del entorno
+
+```ts
+ConfigModule.forRoot({
+  isGlobal: true,
+  load: [configuration],
+  validate: validateEnv,
+});
+```
+
+- Valida el entorno al arrancar, no de forma perezosa en la primera petición.
+- Mantén el acceso a la configuración detrás de helpers tipados o servicios de configuración.
+- Separa las diferencias de dev/staging/prod en factorías de configuración en lugar de ramificar por todo el código de funcionalidad.
+
+## Persistencia y transacciones
+
+- Mantén el código de repositorio / ORM detrás de providers que hablen el lenguaje del dominio.
+- Con Prisma o TypeORM, aísla los flujos transaccionales en servicios que posean la unidad de trabajo.
+- No dejes que los controladores coordinen escrituras de varios pasos directamente.
+
+## Testing
+
+```ts
+describe('UsersController', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [UsersModule],
+    }).compile();
+
+    app = moduleRef.createNestApplication();
+    app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
+    await app.init();
+  });
+});
+```
+
+- Testea los providers de forma unitaria y aislada con dependencias simuladas (mocks).
+- Añade tests a nivel de petición para guards, pipes de validación y filtros de excepciones.
+- Reutiliza en los tests los mismos pipes/filtros globales que usas en producción.
+
+## Valores por defecto de producción
+
+- Habilita logging estructurado e IDs de correlación de peticiones.
+- Termina el proceso ante entorno/configuración inválidos en lugar de arrancar a medias.
+- Prefiere la inicialización asíncrona de providers para clientes de BD/caché con health checks explícitos.
+- Mantén los jobs en segundo plano y los consumidores de eventos en sus propios módulos, no dentro de controladores HTTP.
+- Haz explícitos el rate limiting, la autenticación y el registro de auditoría en los endpoints públicos.

package/vendor/theus-arsenal/skills/patrones-nextjs/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: patrones-nextjs
+description: Next.js 16+ moderno — bundling incremental con Turbopack, caché en sistema de archivos, velocidad de desarrollo y cuándo usar Turbopack vs webpack.
+---
+
+# Patrones de Next.js
+
+Next.js 16+ usa Turbopack por defecto para el desarrollo local: un bundler incremental escrito en Rust que acelera significativamente el arranque en desarrollo y las actualizaciones en caliente.
+
+## Cuándo usar
+
+- **Turbopack (dev por defecto)**: úsalo para el desarrollo del día a día. Arranque en frío y HMR más rápidos, especialmente en aplicaciones grandes.
+- **Webpack (dev legado)**: úsalo solo si te topas con un bug de Turbopack o dependes de un plugin exclusivo de webpack en desarrollo. Desactívalo con `--webpack` (o `--no-turbopack` según tu versión de Next.js; revisa la documentación de tu release).
+- **Producción**: el comportamiento del build de producción (`next build`) puede usar Turbopack o webpack según la versión de Next.js; consulta la documentación oficial de Next.js para tu versión.
+
+Úsala cuando: desarrolles o depures aplicaciones de Next.js 16+, diagnostiques un arranque en desarrollo o un HMR lentos, u optimices los bundles de producción.
+
+## Cómo funciona
+
+- **Turbopack**: bundler incremental para el desarrollo con Next.js. Usa caché en el sistema de archivos, así que los reinicios son mucho más rápidos (p. ej. 5–14x en proyectos grandes).
+- **Por defecto en dev**: desde Next.js 16, `next dev` se ejecuta con Turbopack salvo que se desactive.
+- **Caché en sistema de archivos**: los reinicios reutilizan el trabajo previo; la caché suele estar bajo `.next`; no requiere configuración adicional para el uso básico.
+- **Bundle Analyzer (Next.js 16.1+)**: Bundle Analyzer experimental para inspeccionar la salida y encontrar dependencias pesadas; actívalo vía configuración o flag experimental (consulta la documentación de Next.js para tu versión).
+
+## Ejemplos
+
+### Comandos
+
+```bash
+next dev
+next build
+next start
+```
+
+### Uso
+
+Ejecuta `next dev` para el desarrollo local con Turbopack. Usa el Bundle Analyzer (ver la documentación de Next.js) para optimizar el code-splitting y recortar dependencias grandes. Prefiere el App Router y los server components siempre que sea posible.
+
+## Nombre del archivo de middleware
+
+Next.js 16 introdujo `proxy.ts` como nombre del archivo de middleware, en reemplazo de la convención anterior `middleware.ts`:
+
+- **Next.js 16+**: usa `proxy.ts` en la raíz del proyecto
+- **Anterior a Next.js 16**: usa `middleware.ts` en la raíz del proyecto
+
+El cambio de nombre está ligado a la **versión de Next.js**, no al bundler en uso (Turbopack o webpack). Verifica siempre la documentación oficial de la versión que estés revisando.
+
+**No marques `proxy.ts` como un archivo de middleware mal nombrado o faltante en proyectos con Next.js 16.** El archivo es correcto e intencional. Sugerir renombrarlo a `middleware.ts` romperá la ejecución del middleware.
+
+Referencia: [documentación de proxy en Next.js](https://nextjs.org/docs/app/getting-started/proxy)
+
+## Buenas prácticas
+
+- Mantente en una versión reciente de Next.js 16.x para un comportamiento estable de Turbopack y su caché.
+- Si el desarrollo va lento, asegúrate de estar usando Turbopack (el valor por defecto) y de que la caché no se esté borrando innecesariamente.
+- Para problemas de tamaño de bundle en producción, usa las herramientas oficiales de análisis de bundles de Next.js para tu versión.