@saulwade/swl-ses 1.0.0

package/habilidades/context-builder/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: context-builder
+description: >
+  Ensamblador de contexto con presupuesto de tokens para inyección automática
+  entre sesiones SWL. Cargar cuando se configure la inyección de contexto,
+  se depure el hook inyeccion-contexto.js, o se necesite entender cómo SWL
+  prioriza información entre sesiones. Budget default recalibrado a 2500 por
+  el tokenizer de Opus 4.7 (+15-30% tokens vs 4.6).
+version: "1.1.0"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para depurar hooks que no sean `inyeccion-contexto.js` — la lógica de ensamblado es específica de ese hook."
+  - "No cargar para buscar en el historial de sesiones; para búsqueda semántica usar `memoria-busqueda`."
+  - "No cargar si `tokenBudget` ya fue configurado en la sesión y no hay cambios de modelo o proyecto — re-configurarlo mid-session no tiene efecto."
+  - "No cargar para ajustar la compactación del contexto activo; para eso usar `compactacion-contexto`."
+evolvable: true  # default para skill estandar
+---
+# Context Builder
+
+## Qué es y por qué importa
+
+El Context Builder (`hooks/lib/context-builder.js`) ensambla el bloque de contexto
+que se inyecta al inicio de cada sesión nueva. Su trabajo es responder en pocos
+tokens la pregunta: *"¿Dónde estaba yo?"*
+
+Sin el Context Builder, cada sesión parte de cero. Con él, el modelo recibe en
+los primeros mensajes: el proyecto activo, los patrones aprendidos, el resumen de
+la sesión anterior y los aprendizajes recientes. Todo dentro de un presupuesto
+controlado que no satura el contexto.
+
+---
+
+## Las 5 secciones en orden de prioridad
+
+El ensamblado es secuencial con prioridad decreciente. Si el presupuesto se agota,
+las secciones de mayor número se omiten primero.
+
+| Prioridad | Sección | Fuente |
+|-----------|---------|--------|
+| 1 (siempre) | Header | `path.basename(baseDir)` + `.planning/CONTEXTO.md` |
+| 2 | Instintos activos | `instintos/proyecto.yaml` (confidence >= 0.7) |
+| 3 | Sesión anterior | `.planning/sessions/latest.json` |
+| 4 | Aprendizajes recientes | `.planning/APRENDIZAJES.md` (últimos N bloques H2) |
+| 5 | Footer de truncamiento | Generado automáticamente si se omitió algo |
+
+### Sección 1 — Header
+
+Siempre incluida. Formato:
+```
+[SWL Context] Proyecto: nombre-proyecto | Modo: dev
+```
+
+El modo se lee de `**Modo**: valor` en `.planning/CONTEXTO.md`. Fallback: `dev`.
+
+### Sección 2 — Instintos activos
+
+Instintos del archivo `instintos/proyecto.yaml` que cumplen:
+- `status: active`
+- `confidence >= 0.7`
+
+Se ordenan por confianza descendente y se limitan a `maxInstintos` (default: 5).
+
+### Sección 3 — Sesión anterior
+
+Lee `.planning/sessions/latest.json` para localizar el JSON de la sesión.
+No se incluye si:
+- La sesión tiene `status: active` (es la sesión actual)
+- La sesión tiene menos de 3 tool calls (demasiado corta para aportar contexto)
+
+Incluye: `id`, `summary` (max 200 chars), `filesChanged` (max 5 archivos).
+
+### Sección 4 — Aprendizajes recientes
+
+Lee los últimos N bloques `## título` de `.planning/APRENDIZAJES.md`.
+Solo incluye el título de cada bloque (no el contenido completo).
+Respeta el budget restante de forma estricta: deja de agregar si se agotaría.
+
+### Sección 5 — Footer de truncamiento
+
+Solo aparece si alguna sección fue omitida por presupuesto agotado:
+```
+[Contexto truncado — secciones omitidas: instintos, aprendizajes. Budget: 2000 tokens]
+```
+
+---
+
+## Token budget: por qué 2500 es el default óptimo (Opus 4.7)
+
+El presupuesto controla cuántos tokens puede ocupar el bloque de contexto inyectado.
+
+| Budget | Resultado |
+|--------|-----------|
+| < 1200 tokens | Contexto insuficiente. El header y poco más. Pierde continuidad. |
+| 1200-2500 tokens | Zona óptima. Header + instintos + sesión anterior caben completos. |
+| 2500-6000 tokens | Aceptable para proyectos con muchos instintos o aprendizajes. |
+| > 6000 tokens | Contexto saturado. Diluye información útil. Penaliza el rendimiento. |
+
+El default de 2500 tokens (~10,000 caracteres en español) cubre los 3 niveles de
+contexto más valiosos sin consumir más del 1.25% de la ventana de un modelo sonnet.
+
+**Nota sobre el tokenizer**: Opus 4.7 cambió el tokenizer respecto a 4.6 y produce
+entre 1.0× y 1.35× más tokens para el mismo contenido. El default previo de 2000
+quedó corto — el mismo bloque de contexto ahora pesa 2300–2700 tokens reales.
+El default de 2500 restaura el margen útil.
+
+---
+
+## Configuración
+
+```js
+const { buildContext } = require('./hooks/lib/context-builder');
+
+const { contexto, tokensUsados, seccionesTruncadas } = buildContext(baseDir, {
+  tokenBudget:     2500,  // default: 2500 (era 2000 pre-4.7)
+  maxAprendizajes: 5,     // default: 5
+  maxInstintos:    5,     // default: 5
+});
+```
+
+---
+
+## Integración con inyeccion-contexto.js
+
+El hook `hooks/inyeccion-contexto.js` llama a `buildContext` en la primera
+invocación de cada sesión nueva. El flujo completo:
+
+```
+Nueva sesión
+  → inyeccion-contexto.js detecta primera invocación
+  → llama buildContext(cwd, opciones)
+  → escribe contexto en stdout
+  → Claude lo recibe como parte del primer turno
+  → marca como inyectado en bridge para no repetir
+```
+
+El Context Builder no escribe en stdout directamente — devuelve el string.
+La responsabilidad de emitirlo es del hook que lo invoca.
+
+---
+
+## Cuándo NO cargar
+
+- Se busca recuperar el historial de sesiones o aprendizajes anteriores; usar `memoria-busqueda` con las 3 capas (search/timeline/fetch).
+- El hook `inyeccion-contexto.js` ya inyectó contexto en esta sesión — re-invocar el Context Builder no modifica el contexto en curso.
+- Se necesita depurar un hook que no sea `inyeccion-contexto.js`; la lógica de este módulo es específica del ensamblado inicial.
+- Se quiere cambiar el presupuesto de tokens de la sesión actual ya iniciada; el budget se configura antes de la primera invocación del hook.
+
+## Gotchas / Errores comunes no obvios
+
+- **`seccionesTruncadas` ignorado cuando contiene secciones críticas**: el builder omite la sección 3 (sesión anterior) por presupuesto agotado y el agente no lo detecta, iniciando la sesión sin contexto de trabajo previo. Causa: no se verificó el campo `seccionesTruncadas` tras llamar a `buildContext`. Solución: si `seccionesTruncadas` no está vacío, ajustar `tokenBudget` hacia arriba o reducir `maxAprendizajes` hasta que las secciones 1-3 quepan completas — la sesión anterior es crítica.
+- **Sesión con `status: active` incluida como sesión anterior**: el builder lee `latest.json` y encuentra la sesión actual marcada como `active`, inyectando el contexto de sí mismo. Causa: el filtro de `status: active` no se aplicó. Solución: verificar que `buildContext` excluye sesiones con `status: active` antes de incluirlas en la Sección 3 — la documentación ya lo especifica pero la implementación debe verificarse.
+- **Budget de 2000 tokens sin recalibrar para Opus 4.7**: el mismo archivo de configuración que usaba 2000 en Opus 4.6 ahora satura el contexto porque el tokenizer produce 1.0-1.35× más tokens para el mismo contenido. Causa: no se actualizó la configuración al migrar de modelo. Solución: usar el default de 2500 que establece este skill para Opus 4.7; no asumir que el budget previo sigue siendo válido.
+- **Instintos con `confidence < 0.7` incluidos en la Sección 2**: el código no aplica el filtro de confianza y llena el budget con instintos en estado draft. Causa: el filtro `confidence >= 0.7` se omitió en la implementación. Solución: verificar que `buildContext` filtra por `status: active` Y `confidence >= 0.7` — un draft no debe consumir tokens en la inyección inicial.
+
+## Anti-patrones
+
+**Budget muy alto (> 5000 tokens)**
+Incluir todo el APRENDIZAJES.md en cada sesión satura el contexto útil.
+El modelo pierde foco cuando recibe demasiado contexto de baja relevancia.
+Usar `maxAprendizajes` bajo (3-5) y `tokenBudget` moderado (2000-3000).
+
+**Incluir todo sin priorizar**
+El valor del Context Builder está en la selección, no en la exhaustividad.
+Un header + 3 instintos relevantes > 50 aprendizajes sin estructura.
+Las secciones de mayor prioridad deben caber siempre en el budget.
+
+**Ignorar seccionesTruncadas**
+Si `seccionesTruncadas` no está vacío y el contenido truncado es importante,
+aumentar `tokenBudget` o reducir `maxAprendizajes`/`maxInstintos` para que
+las secciones de mayor prioridad quepan completas.

package/habilidades/control-profundidad/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: control-profundidad
+deprecated: true
+deprecated-since: "5.8.0"
+deprecated-reason: >
+  Opus 4.7 no soporta extended thinking con budget fijo — el modelo decide
+  dinámicamente cuándo invertir tokens de pensamiento. Los niveles nativos
+  de esfuerzo de Claude Code (high | xhigh | max) reemplazan el sistema de
+  porcentajes 25/50/75/100% de este skill. Programado para eliminación en
+  un release MAJOR futuro. Mantenido ahora por retrocompatibilidad.
+deprecated-replacement: >
+  Usar niveles de esfuerzo nativos de Claude Code via toggle Shift+Tab o
+  configuración de sesión. Para controlar verbosidad del output final,
+  usar la regla `brevedad-output.md` (obligatoria y siempre activa).
+description: >
+  [DEPRECATED — eliminar en próximo MAJOR] Permite al usuario controlar
+  la profundidad y extension de las respuestas de Claude. Ofrece 4 niveles
+  (25/50/75/100%) con estimacion heuristica de tokens. Cargar cuando el
+  usuario pide controlar longitud de respuesta, dice "version corta", "responde
+  breve", "dame el detalle completo", "token budget", o variantes similares.
+  Para nuevas invocaciones, preferir niveles de esfuerzo nativos de Claude Code.
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar en proyectos con Opus 4.7 — los niveles nativos `high/xhigh/max` de Claude Code reemplazan este skill; ver tabla de migración en el cuerpo."
+  - "No cargar para controlar la longitud del output entre agentes — eso lo hace `reglas/brevedad-output.md` que es obligatoria y siempre activa."
+  - "No cargar si el usuario no pidió explícitamente controlar profundidad — no interrumpir el flujo con un menú de niveles no solicitado."
+evolvable: true  # default para skill estandar
+---
+# Control de Profundidad de Respuesta
+
+> **⚠ DEPRECATED**: Opus 4.7 maneja el esfuerzo de razonamiento
+> de forma dinámica y no soporta extended thinking con budget fijo. Usar los
+> niveles nativos `high | xhigh | max` de Claude Code en lugar del sistema de
+> porcentajes. Para verbosidad del output final, aplica la regla
+> `brevedad-output.md` que ya es obligatoria. Este skill se mantiene por
+> retrocompatibilidad y se eliminará en un release MAJOR futuro.
+
+## Migración recomendada
+
+| Usuario pide | Antes (este skill) | Ahora (nativo) |
+|--------------|-------------------|----------------|
+| "breve", "tldr", "corto" | Nivel 25% | `brevedad-output.md` (siempre activa) |
+| "normal", "balanceado" | Nivel 50% | Default del modelo |
+| "detallado", "completo" | Nivel 75% | Effort `xhigh` (default en Claude Code) |
+| "exhaustivo", "a fondo" | Nivel 100% | Effort `max` (solo para análisis difíciles) |
+
+Los niveles de esfuerzo se controlan con Shift+Tab en Claude Code o via
+configuración por agente (`model: claude-opus-4-7` + el harness decide el
+esfuerzo según el contexto).
+
+## Cuándo NO cargar
+
+- El proyecto usa Opus 4.7 como modelo — los niveles nativos de esfuerzo (`high/xhigh/max` via `Shift+Tab`) son el mecanismo correcto; este skill está deprecated.
+- Se quiere controlar brevedad del output entre agentes; `brevedad-output.md` ya aplica globalmente, sin necesidad de este skill.
+- El usuario no pidió control de profundidad explícitamente — presentar el menú de niveles cuando no fue solicitado es ruido de UX.
+
+## Cuando activar
+
+- El usuario menciona "version corta", "breve", "resumido", "tldr"
+- El usuario pide "respuesta detallada", "completa", "exhaustiva"
+- El usuario dice "token budget", "cuantos tokens", "controlar longitud"
+- El usuario dice "al 25%", "al 50%", "dame la version corta"
+- NO activar si el usuario ya eligio un nivel en esta sesion (mantenerlo)
+- NO activar si la respuesta es trivial (1 linea)
+
+## Niveles de profundidad
+
+| Nivel | % | Que incluir | Que omitir |
+|-------|---|-------------|-----------|
+| Esencial | 25% | Respuesta directa, 2-4 oraciones max | Contexto, ejemplos, alternativas |
+| Moderado | 50% | Respuesta + contexto necesario + 1 ejemplo | Analisis profundo, edge cases |
+| Detallado | 75% | Respuesta estructurada, multiples ejemplos, pros/contras | Edge cases extremos |
+| Exhaustivo | 100% | Todo — analisis completo, todas las perspectivas | Nada |
+
+## Atajos — el usuario ya señala el nivel
+
+| Que dice el usuario | Nivel |
+|--------------------|-------|
+| "breve", "corto", "tldr", "version corta", "1" | 25% |
+| "normal", "moderado", "balanceado", "2" | 50% |
+| "detallado", "completo", "a fondo", "3" | 75% |
+| "exhaustivo", "todo", "sin limites", "4" | 100% |
+
+Si el usuario ya señala el nivel, responder directamente a ese nivel sin preguntar.
+
+## Estimacion heuristica de tokens
+
+Para estimar cuantos tokens usara cada nivel:
+
+- Prosa en español: `palabras x 1.5`
+- Codigo: `caracteres / 3.5`
+- Mixto: usar el tipo dominante
+
+| Complejidad | Multiplicador (sobre input) |
+|-------------|---------------------------|
+| Simple (que es X?) | 3x - 8x |
+| Media (como funciona X?) | 8x - 20x |
+| Alta (diseña/compara/analiza) | 15x - 40x |
+
+## Como presentar opciones
+
+Solo presentar cuando el usuario pide explicitamente controlar profundidad
+y NO ha indicado ya un nivel:
+
+```
+Profundidad de respuesta:
+
+[1] Esencial  (25%) — respuesta directa, sin contexto
+[2] Moderado  (50%) — respuesta + contexto + 1 ejemplo
+[3] Detallado (75%) — respuesta completa con alternativas
+[4] Exhaustivo(100%) — todo, sin limites
+
+Cual nivel? (1-4)
+```
+
+## Gotchas / Errores comunes no obvios
+
+- **Nivel aplicado a output entre agentes**: el agente aplica el nivel 25% al output de un checkpoint o reporte técnico entre agentes, perdiendo información necesaria para el siguiente agente. Causa: el skill dice "solo aplica a respuestas al usuario" pero no se verificó el destino del output. Solución: verificar siempre si el destinatario es el usuario (nivel aplica) o un agente (brevedad-output.md aplica en cambio).
+- **Nivel 100% en preguntas simples de diagnóstico**: el usuario pregunta "¿qué versión de Python usan?" con un nivel 100% activo de una sesión anterior y recibe 3 páginas de análisis del ecosistema. Causa: el nivel se mantuvo de la sesión anterior sin verificar si sigue siendo apropiado. Solución: al iniciar una nueva sesión o nueva tarea, verificar si el nivel persistido aplica al contexto actual — si la pregunta es trivial, responder a nivel Esencial independientemente del nivel activo.
+- **Estimación heurística de tokens usada como presupuesto real**: el agente estima "este response costará 1500 tokens" con la heurística `palabras × 1.5` y lo usa para tomar decisiones de API budget. Causa: la heurística es para orientar al usuario, no para cálculos de coste. Solución: para presupuesto real de tokens, usar el tokenizer o el callback de tokens del modelo — la heurística tiene margen de error del ±30%.
+
+## Reglas
+
+- Si el usuario eligio un nivel, mantenerlo para el resto de la sesion
+- El nivel aplica solo a respuestas al usuario, NO a output entre agentes
+  (ahi aplica `brevedad-output.md` siempre)
+- No preguntar en cada mensaje — solo cuando el usuario lo pide
+- Complementa, no reemplaza, la regla de brevedad de agentes

package/habilidades/csharp-experto/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: csharp-experto
+description: >
+  C# moderno con ASP.NET Core, EF Core async, async/await con CancellationToken,
+  LINQ avanzado, Minimal APIs, Options pattern y Background Services.
+  Cargar cuando se implementen APIs ASP.NET Core, entidades EF Core, migraciones,
+  servicios .NET 8+ o cualquier código C# de producción.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para escribir tests C# (xUnit, NSubstitute, FluentAssertions) — para testing cargar `csharp-testing`."
+  - "No cargar para diseñar patrones C# (CQRS, Result<T>, MediatR) — para diseño arquitectónico cargar `csharp-patrones`."
+  - "No cargar para errores de compilación C# o .csproj — para build errors cargar `build-errors-csharp`."
+  - "No cargar para lógica en F#, VB.NET u otro lenguaje .NET — este skill cubre C# específicamente con ASP.NET Core."
+evolvable: true  # default para skill estandar
+---
+# C# Experto — ASP.NET Core y .NET 8+
+
+## Cuándo NO cargar
+
+- La tarea es escribir tests C# con xUnit, NSubstitute o FluentAssertions — cargar `csharp-testing`.
+- La pregunta es sobre diseñar patrones C# (CQRS, Result<T>, MediatR, Unit of Work) — cargar `csharp-patrones`.
+- Los errores son de compilación C# o configuración de `.csproj` — cargar `build-errors-csharp`.
+- El proyecto usa F#, VB.NET u otro lenguaje .NET — este skill cubre C# con ASP.NET Core específicamente.
+
+## Estructura de proyecto recomendada
+
+```
+MiApi/
+├── MiApi.csproj
+├── Program.cs                   # App factory, DI, middleware pipeline
+├── appsettings.json
+├── Features/                    # Organizado por feature (Vertical Slice)
+│   └── Facturas/
+│       ├── FacturasEndpoints.cs
+│       ├── FacturasService.cs
+│       └── FacturaDto.cs
+├── Infrastructure/
+│   ├── Persistence/
+│   │   ├── AppDbContext.cs
+│   │   └── Migrations/
+│   └── BackgroundJobs/
+└── Domain/
+    └── Entities/
+```
+
+---
+
+## Minimal APIs vs Controllers
+
+Preferir Minimal APIs para servicios nuevos en .NET 8+. Controllers solo cuando se necesita herencia o filtros de acción complejos.
+
+```csharp
+// Program.cs — App factory
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddDbContext<AppDbContext>(o =>
+    o.UseNpgsql(builder.Configuration.GetConnectionString("Default")));
+builder.Services.AddScoped<IFacturasService, FacturasService>();
+builder.Services.Configure<EmailOptions>(
+    builder.Configuration.GetSection("Email"));
+
+var app = builder.Build();
+
+app.MapGroup("/api/v1/facturas")
+   .MapFacturasEndpoints()
+   .RequireAuthorization();
+
+app.Run();
+
+// FacturasEndpoints.cs
+public static class FacturasEndpoints
+{
+    public static RouteGroupBuilder MapFacturasEndpoints(
+        this RouteGroupBuilder group)
+    {
+        group.MapGet("/", ObtenerTodas);
+        group.MapGet("/{id:guid}", ObtenerPorId);   // parametrica DESPUÉS de estática
+        group.MapPost("/", Crear);
+        return group;
+    }
+
+    static async Task<Results<Ok<FacturaDto>, NotFound>> ObtenerPorId(
+        Guid id, IFacturasService svc, CancellationToken ct) =>
+        await svc.ObtenerAsync(id, ct) is { } dto
+            ? TypedResults.Ok(dto)
+            : TypedResults.NotFound();
+}
+```
+
+---
+
+## EF Core — DbContext Lifecycle
+
+```csharp
+// REGLA: DbContext siempre Scoped. Nunca Singleton ni Transient.
+builder.Services.AddDbContext<AppDbContext>(o =>
+    o.UseNpgsql(connectionString)
+     .EnableSensitiveDataLogging(app.Environment.IsDevelopment()));
+
+public class AppDbContext(DbContextOptions<AppDbContext> options)
+    : DbContext(options)
+{
+    public DbSet<Factura> Facturas => Set<Factura>();
+    public DbSet<Cliente> Clientes => Set<Cliente>();
+
+    protected override void OnModelCreating(ModelBuilder mb)
+    {
+        mb.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly);
+    }
+}
+
+// Configuración de entidad separada (nunca en OnModelCreating directamente)
+public class FacturaConfiguration : IEntityTypeConfiguration<Factura>
+{
+    public void Configure(EntityTypeBuilder<Factura> b)
+    {
+        b.HasKey(f => f.Id);
+        b.Property(f => f.Estatus)
+         .HasConversion<string>()
+         .HasMaxLength(20);
+        b.HasIndex(f => new { f.EmpresaId, f.Estatus });  // documentar qué query justifica el índice
+    }
+}
+```
+
+---
+
+## Async/Await con CancellationToken
+
+```csharp
+// SIEMPRE propagar CancellationToken hasta la BD
+public async Task<List<FacturaDto>> ObtenerTodasAsync(
+    Guid empresaId, CancellationToken ct = default)
+{
+    return await _db.Facturas
+        .Where(f => f.EmpresaId == empresaId)
+        .Select(f => new FacturaDto(f.Id, f.Folio, f.Total))
+        .AsNoTracking()          // SIEMPRE en queries de solo lectura
+        .ToListAsync(ct);        // ct llega hasta la BD
+}
+
+// NUNCA async void — solo async Task o async ValueTask
+// MAL:
+async void ProcesarEnBackground() { ... }
+
+// BIEN:
+async Task ProcesarEnBackgroundAsync(CancellationToken ct) { ... }
+```
+
+---
+
+## IHostedService y BackgroundService
+
+```csharp
+public class FacturasProcesadorService(
+    IServiceScopeFactory scopeFactory,
+    ILogger<FacturasProcesadorService> logger)
+    : BackgroundService
+{
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            try
+            {
+                // SIEMPRE crear scope — BackgroundService es Singleton
+                await using var scope = scopeFactory.CreateAsyncScope();
+                var svc = scope.ServiceProvider.GetRequiredService<IFacturasService>();
+                await svc.ProcesarPendientesAsync(stoppingToken);
+            }
+            catch (Exception ex) when (ex is not OperationCanceledException)
+            {
+                logger.LogError(ex, "Error en ciclo de procesamiento");
+            }
+            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
+        }
+    }
+}
+```
+
+---
+
+## Options Pattern
+
+```csharp
+// Validación en tiempo de inicio — no en runtime
+public class EmailOptions
+{
+    public const string Section = "Email";
+
+    [Required] public string SmtpHost { get; init; } = "";
+    [Range(1, 65535)] public int SmtpPort { get; init; } = 587;
+    [Required] public string ApiKey { get; init; } = "";
+}
+
+// Registro con validación
+builder.Services
+    .AddOptions<EmailOptions>()
+    .BindConfiguration(EmailOptions.Section)
+    .ValidateDataAnnotations()
+    .ValidateOnStart();              // Falla al arrancar si la config es inválida
+
+// Uso en servicio
+public class EmailService(IOptions<EmailOptions> opts)
+{
+    private readonly EmailOptions _config = opts.Value;
+}
+```
+
+---
+
+## Records e Init-Only Properties
+
+```csharp
+// Records para DTOs y Commands (inmutables por defecto)
+public record FacturaDto(Guid Id, string Folio, decimal Total);
+
+public record CrearFacturaCommand(
+    Guid EmpresaId,
+    string Folio,
+    List<ItemDto> Items);
+
+// Init-only para configuración mutable parcialmente
+public class ConfiguracionSistema
+{
+    public required string Nombre { get; init; }
+    public required string Version { get; init; }
+    public bool ModoDebug { get; set; }  // mutable post-construcción
+}
+```
+
+---
+
+## LINQ Method Syntax avanzado
+
+```csharp
+// Proyección con join — preferir Include/ThenInclude en EF Core
+var reporte = await _db.Facturas
+    .Where(f => f.EmpresaId == empresaId && f.FechaEmision >= desde)
+    .GroupBy(f => f.ClienteId)
+    .Select(g => new ReporteClienteDto(
+        ClienteId: g.Key,
+        TotalFacturas: g.Count(),
+        MontoTotal: g.Sum(f => f.Total),
+        UltimaFactura: g.Max(f => f.FechaEmision)
+    ))
+    .OrderByDescending(r => r.MontoTotal)
+    .Take(10)
+    .ToListAsync(ct);
+```
+
+---
+
+## Nullable Reference Types
+
+```csharp
+// <Nullable>enable</Nullable> en .csproj — OBLIGATORIO
+// Expresar intención de nulabilidad en el tipo
+public class Factura
+{
+    public Guid Id { get; set; }
+    public string Folio { get; set; } = "";      // nunca null
+    public string? Observaciones { get; set; }   // puede ser null
+    public Cliente Cliente { get; set; } = null!; // EF lo asigna, nunca null en runtime
+}
+```
+
+---
+
+## Anti-patrones críticos
+
+### DbContext como Singleton — NUNCA
+
+```csharp
+// MAL — DbContext no es thread-safe
+builder.Services.AddSingleton<AppDbContext>(...);
+
+// BIEN — siempre Scoped
+builder.Services.AddDbContext<AppDbContext>(...);
+```
+
+### SaveChanges en repositorios — NUNCA
+
+```csharp
+// MAL — el repositorio no sabe si hay otras operaciones en la misma transacción
+public async Task<Factura> CrearAsync(Factura factura)
+{
+    _db.Facturas.Add(factura);
+    await _db.SaveChangesAsync();   // NO aquí
+    return factura;
+}
+
+// BIEN — SaveChanges solo en el use case / endpoint
+public async Task<Factura> CrearAsync(Factura factura)
+{
+    _db.Facturas.Add(factura);
+    return factura;   // El llamador hace SaveChanges
+}
+```
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**`DbContext` registrado como `Singleton` causa `InvalidOperationException` en acceso concurrente**: EF Core `DbContext` no es thread-safe — si se registra como Singleton y múltiples requests lo usan simultáneamente, las queries se mezclan. Fix: registrar siempre como `Scoped` (`services.AddDbContext<AppDbContext>(...)`); para `BackgroundService` que vive como Singleton, usar `IServiceScopeFactory` para crear un scope por operación.
+
+**`async void` en event handlers de ASP.NET lanza excepciones que no se pueden capturar**: un método `async void` lanza su excepción en el SynchronizationContext del thread de UI (o en ThreadPool), sin que el llamador pueda atraparla con `try/catch`. En ASP.NET Core sin SynchronizationContext, la excepción mata el proceso. Fix: nunca usar `async void` excepto en event handlers de frameworks que lo requieren explícitamente; usar `async Task` siempre.
+
+**`IOptions<T>` registrado con `AddOptions<T>().ValidateDataAnnotations()` no valida al arranque**: la validación solo ocurre cuando se resuelve el servicio, no en el startup. Una configuración inválida no se detecta hasta que el primer request llega. Fix: encadenar `.ValidateOnStart()` para que la validación falle en `builder.Build()` si la configuración es inválida: `services.AddOptions<MiConfig>().Bind(config).ValidateDataAnnotations().ValidateOnStart()`.
+
+**LINQ `Select` sobre `IQueryable` con métodos no traducibles a SQL lanza en runtime**: `dbContext.Facturas.Select(f => new { Total = CalcularTotal(f) })` falla en runtime con `InvalidOperationException: Could not translate expression` si `CalcularTotal` no es una función que EF Core conoce. Fix: materializar primero con `AsEnumerable()` o `ToList()` para operaciones que requieren lógica C# no traducible, luego aplicar el `Select` en memoria — con cuidado de no traer más datos de los necesarios.
+
+## Checklist antes de merge
+
+- [ ] CancellationToken propagado hasta ToListAsync/SaveChangesAsync
+- [ ] AsNoTracking() en todos los queries de solo lectura
+- [ ] DbContext registrado como Scoped, nunca Singleton
+- [ ] No hay async void (solo async Task)
+- [ ] BackgroundService usa IServiceScopeFactory para resolver Scoped services
+- [ ] Nullable Reference Types habilitado en .csproj
+- [ ] Options validados con ValidateOnStart()