@atlashub/smartstack-cli 4.32.0 → 4.34.0

package/templates/skills/apex/references/smartstack-api.md

@@ -1,7 +1,8 @@
 # SmartStack Domain API Reference
 
 > **Source of truth:** `SmartStack.app/src/SmartStack.Domain/Common/`
-> **Loaded by:** step-01 (analyze), step-03 (execute)
+> **Loaded by:** step-01 (analyze), step-03a/03b/03c (execute). Released after Layer 2.
+> **MCP generates complete implementations** — this file provides guard rails and conventions only.
 
 ---
 
@@ -43,7 +44,7 @@ public interface IAuditableEntity
 }
 ```
 
-### IOptionalTenantEntity (nullable tenant)
+### IOptionalTenantEntity (nullable tenant — cross-tenant)
 
 ```csharp
 public interface IOptionalTenantEntity
@@ -89,23 +90,18 @@ Verify in `Program.cs`: `JsonSerializerOptions.Converters.Add(new JsonStringEnum
 
 ---
 
-## Entity Pattern (tenant-scoped, most common)
+## Entity Patterns
 
-```csharp
-using SmartStack.Domain.Common;
-
-namespace {ProjectName}.Domain.Entities.{App}.{Module};
+### Tenant-scoped (most common)
 
+```csharp
 public class {Name} : BaseEntity, ITenantEntity, IAuditableEntity
 {
-    // ITenantEntity
     public Guid TenantId { get; private set; }
-
-    // IAuditableEntity
     public string? CreatedBy { get; set; }
     public string? UpdatedBy { get; set; }
 
-    // Business properties (add your own)
+    // Business properties
     public string Code { get; private set; } = null!;
     public string Name { get; private set; } = null!;
     public string? Description { get; private set; }
@@ -137,184 +133,60 @@ public class {Name} : BaseEntity, ITenantEntity, IAuditableEntity
 }
 ```
 
----
-
-## Entity Pattern (platform-level, no tenant)
+### Platform-level (no tenant)
 
 ```csharp
 public class {Name} : BaseEntity, IAuditableEntity
 {
+    // No TenantId — platform-wide entity
     public string? CreatedBy { get; set; }
     public string? UpdatedBy { get; set; }
-
-    // Business properties
     public string Code { get; private set; } = null!;
     public string Name { get; private set; } = null!;
-
     private {Name}() { }
-
-    public static {Name} Create(string code, string name)
-    {
-        return new {Name}
-        {
-            Id = Guid.NewGuid(),
-            Code = code.ToLowerInvariant(),
-            Name = name,
-            CreatedAt = DateTime.UtcNow
-        };
-    }
+    // Create(): no tenantId parameter, no Guid.Empty guard
 }
 ```
 
-### Entity Pattern — Cross-Tenant (IOptionalTenantEntity)
-
-For entities that can be shared across tenants (e.g., Department, Currency). TenantId is nullable — null means shared, Guid means tenant-specific. The user decides the scope at creation time.
+### Cross-Tenant (IOptionalTenantEntity) — key differences
 
 ```csharp
 public class {Name} : BaseEntity, IOptionalTenantEntity, IAuditableEntity
 {
-    // TenantId nullable — null = shared across all tenants
-    public Guid? TenantId { get; private set; }
-
-    public string? CreatedBy { get; set; }
-    public string? UpdatedBy { get; set; }
-
-    // Business properties
-    public string Code { get; private set; } = string.Empty;
-    public string Name { get; private set; } = string.Empty;
-
-    private {Name}() { }
-
-    /// <param name="tenantId">null = shared (cross-tenant), Guid = tenant-specific</param>
-    public static {Name} Create(Guid? tenantId = null, string code, string name)
-    {
-        return new {Name}
-        {
-            Id = Guid.NewGuid(),
-            TenantId = tenantId,
-            Code = code.ToLowerInvariant(),
-            Name = name,
-            CreatedAt = DateTime.UtcNow
-        };
-    }
+    public Guid? TenantId { get; private set; }  // nullable — null = shared
+    // Create(Guid? tenantId = null, ...) — tenantId nullable
 }
 ```
 
-**EF Core global query filter (already in SmartStack.app CoreDbContext):**
-```csharp
-builder.HasQueryFilter(e => !ShouldFilterByTenant || e.TenantId == null || e.TenantId == CurrentTenantId);
-```
-This automatically includes shared (null) + current tenant data in all queries.
-
-**Service pattern for optional tenant:**
-```csharp
-// No guard clause — tenantId is nullable
-var tenantId = _currentTenant.TenantId; // null = creating shared data
-var entity = Department.Create(tenantId, dto.Code, dto.Name);
-```
-
-### Entity Pattern — Scoped (IScopedTenantEntity)
+EF query filter (in CoreDbContext): `builder.HasQueryFilter(e => !ShouldFilterByTenant || e.TenantId == null || e.TenantId == CurrentTenantId);`
+Service: no guard clause — `var tenantId = _currentTenant.TenantId;` (null = creating shared data).
 
-For entities with explicit visibility control via EntityScope enum (Tenant, Shared, Platform).
+### Scoped (IScopedTenantEntity) — key differences
 
 ```csharp
 public class {Name} : BaseEntity, IScopedTenantEntity, IAuditableEntity
 {
     public Guid? TenantId { get; private set; }
     public EntityScope Scope { get; private set; }
-
-    public string? CreatedBy { get; set; }
-    public string? UpdatedBy { get; set; }
-
-    private {Name}() { }
-
-    public static {Name} Create(Guid? tenantId = null, EntityScope scope = EntityScope.Tenant)
-    {
-        if (scope == EntityScope.Tenant && tenantId == null)
-            throw new ArgumentException("TenantId is required when scope is Tenant");
-
-        return new {Name}
-        {
-            Id = Guid.NewGuid(),
-            TenantId = tenantId,
-            Scope = scope,
-            CreatedAt = DateTime.UtcNow
-        };
-    }
+    // Create: if scope == Tenant && tenantId == null → throw
 }
 ```
 
-### Entity Pattern — Person Extension (User-linked roles)
-
-For entities representing a "person role" of a User (Employee, Customer, Contact). Links entity to User instead of duplicating personal data.
-
-> **Full reference:** See `references/person-extension-pattern.md` for complete entity, config, service, DTO, and frontend patterns with C# templates, decision guide, and examples.
+### Person Extension (User-linked)
 
-**Two variants:**
+> **Full reference:** See `references/person-extension-pattern.md` for complete patterns.
 
 | Variant | UserId | Use case |
 |---------|--------|----------|
 | **Mandatory** | `Guid UserId` | Employee, Manager — always a User |
 | **Optional** | `Guid? UserId` | Customer, Contact — may or may not have account |
 
-**IPersonExtension interface:**
-```csharp
-public interface IPersonExtension
-{
-    Guid? UserId { get; }
-    User? User { get; }
-}
-```
-
-**Mandatory variant (entity):**
-```csharp
-public class Employee : BaseEntity, ITenantEntity, IAuditableEntity, IPersonExtension
-{
-    public Guid TenantId { get; private set; }
-    public string? CreatedBy { get; set; }
-    public string? UpdatedBy { get; set; }
-
-    // Person Extension — mandatory UserId
-    public Guid UserId { get; private set; }
-    public User? User { get; private set; }
-
-    // Business properties ONLY — no duplicate person fields
-    public string Code { get; private set; } = null!;
-    public DateOnly HireDate { get; private set; }
-}
-```
-
-**Optional variant (entity):**
-```csharp
-public class Customer : BaseEntity, ITenantEntity, IAuditableEntity, IPersonExtension
-{
-    public Guid TenantId { get; private set; }
-    public string? CreatedBy { get; set; }
-    public string? UpdatedBy { get; set; }
-
-    // Person Extension — optional UserId
-    public Guid? UserId { get; private set; }
-    public User? User { get; private set; }
-
-    // Person fields (used only when UserId is null)
-    public string FirstName { get; private set; } = null!;
-    public string LastName { get; private set; } = null!;
-    public string? Email { get; private set; }
-
-    // Computed — resolve from User if linked, else own fields
-    public string DisplayFirstName => User?.FirstName ?? FirstName;
-    public string DisplayLastName => User?.LastName ?? LastName;
-    public string? DisplayEmail => User?.Email ?? Email;
-}
-```
-
-**Key rules:**
-- **EF Config (mandatory):** Unique index on `(TenantId, UserId)` without filter
-- **EF Config (optional):** Unique index on `(TenantId, UserId)` with `.HasFilter("[UserId] IS NOT NULL")`
-- **Service:** Include User on all queries. Verify User exists and no duplicate on CreateAsync.
-- **DTO:** Mandatory CreateDto requires `UserId`. Optional CreateDto requires person fields when `UserId` is null.
-
----
+Key rules:
+- **Mandatory:** Unique index on `(TenantId, UserId)` without filter. No person fields on entity.
+- **Optional:** Unique index on `(TenantId, UserId)` with `.HasFilter("[UserId] IS NOT NULL")`. Add own `FirstName`/`LastName`/`Email` + `Display*` computed properties.
+- **Service:** Always Include User. Verify User exists + no duplicate on CreateAsync.
+- **DTO (mandatory):** CreateDto requires `UserId`.
+- **DTO (optional):** CreateDto requires person fields when `UserId` is null.
 
 ### MCP tenantMode Parameter
 
@@ -331,15 +203,11 @@ The old `isSystemEntity: true` still works and maps to `tenantMode: 'none'`.
 ## EF Configuration Pattern
 
 ```csharp
-using Microsoft.EntityFrameworkCore;
-using Microsoft.EntityFrameworkCore.Metadata.Builders;
-
 public class {Name}Configuration : IEntityTypeConfiguration<{Name}>
 {
     public void Configure(EntityTypeBuilder<{Name}> builder)
     {
         builder.ToTable("{prefix}{Name}s", "{schema}");
-
         builder.HasKey(x => x.Id);
 
         // Tenant (if ITenantEntity)
@@ -361,223 +229,20 @@ public class {Name}Configuration : IEntityTypeConfiguration<{Name}>
             .IsUnique()
             .HasDatabaseName("IX_{prefix}{Name}s_Tenant_Code");
 
-        // Relationships
-        // builder.HasMany(x => x.Children)
-        //     .WithOne(x => x.Parent)
-        //     .HasForeignKey(x => x.ParentId)
-        //     .OnDelete(DeleteBehavior.Restrict);
-
-        // Seed data (if applicable)
-        // builder.HasData({Name}SeedData.GetSeedData());
+        // Relationships — use .OnDelete(DeleteBehavior.Restrict)
     }
 }
 ```
 
 ---
 
-## Service Pattern (tenant-scoped, required)
-
-> All services must inject `ICurrentUserService` + `ICurrentTenantService` and filter by `TenantId`. Missing TenantId is an OWASP A01 vulnerability.
-
-```csharp
-using Microsoft.EntityFrameworkCore;
-using Microsoft.Extensions.Logging;
-using SmartStack.Application.Common.Interfaces.Identity;
-using SmartStack.Application.Common.Interfaces.Tenants;
-using SmartStack.Application.Common.Interfaces.Persistence;
-
-namespace {ProjectName}.Infrastructure.Services.{App}.{Module};
-
-public class {Name}Service : I{Name}Service
-{
-    private readonly IExtensionsDbContext _db;
-    private readonly ICurrentUserService _currentUser;
-    private readonly ICurrentTenantService _currentTenant;
-    private readonly ILogger<{Name}Service> _logger;
-
-    public {Name}Service(
-        IExtensionsDbContext db,
-        ICurrentUserService currentUser,
-        ICurrentTenantService currentTenant,
-        ILogger<{Name}Service> logger)
-    {
-        _db = db;
-        _currentUser = currentUser;
-        _currentTenant = currentTenant;
-        _logger = logger;
-    }
-
-    public async Task<PaginatedResult<{Name}ResponseDto>> GetAllAsync(
-        string? search = null,
-        int page = 1,
-        int pageSize = 20,
-        CancellationToken ct = default)
-    {
-        // Guard clause — throws 400 if no tenant context (e.g., missing X-Tenant-Slug header)
-        var tenantId = _currentTenant.TenantId
-            ?? throw new TenantContextRequiredException();
-
-        var query = _db.{Name}s
-            .Where(x => x.TenantId == tenantId)  // Required tenant filter
-            .AsNoTracking();
-
-        // Search filter — enables EntityLookup on frontend
-        if (!string.IsNullOrWhiteSpace(search))
-        {
-            query = query.Where(x =>
-                x.Name.Contains(search) ||
-                x.Code.Contains(search));
-        }
-
-        var totalCount = await query.CountAsync(ct);
-        var items = await query
-            .OrderBy(x => x.Name)
-            .Skip((page - 1) * pageSize)
-            .Take(pageSize)
-            .Select(x => new {Name}ResponseDto(x.Id, x.Code, x.Name, x.CreatedAt))
-            .ToListAsync(ct);
-
-        return new PaginatedResult<{Name}ResponseDto>(items, totalCount, page, pageSize);
-    }
-
-    public async Task<{Name}ResponseDto?> GetByIdAsync(Guid id, CancellationToken ct)
-    {
-        var tenantId = _currentTenant.TenantId
-            ?? throw new TenantContextRequiredException();
-
-        return await _db.{Name}s
-            .Where(x => x.Id == id && x.TenantId == tenantId)  // Required
-            .AsNoTracking()
-            .Select(x => new {Name}ResponseDto(x.Id, x.Code, x.Name, x.CreatedAt))
-            .FirstOrDefaultAsync(ct);
-    }
-
-    public async Task<{Name}ResponseDto> CreateAsync(Create{Name}Dto dto, CancellationToken ct)
-    {
-        var tenantId = _currentTenant.TenantId
-            ?? throw new TenantContextRequiredException();
-
-        var entity = {Name}.Create(
-            tenantId: tenantId,  // Required — never Guid.Empty
-            code: dto.Code,
-            name: dto.Name);
-
-        entity.CreatedBy = _currentUser.UserId?.ToString();
-
-        _db.{Name}s.Add(entity);
-        await _db.SaveChangesAsync(ct);
-
-        _logger.LogInformation("Created {Entity} {Id} for tenant {TenantId}",
-            nameof({Name}), entity.Id, tenantId);
-
-        return new {Name}ResponseDto(entity.Id, entity.Code, entity.Name, entity.CreatedAt);
-    }
-
-    public async Task DeleteAsync(Guid id, CancellationToken ct)
-    {
-        var tenantId = _currentTenant.TenantId
-            ?? throw new TenantContextRequiredException();
-
-        var entity = await _db.{Name}s
-            .FirstOrDefaultAsync(x => x.Id == id && x.TenantId == tenantId, ct)
-            ?? throw new KeyNotFoundException($"{Name} {id} not found");
-
-        _db.{Name}s.Remove(entity);
-        await _db.SaveChangesAsync(ct);
-    }
-}
-```
-
-### Service Pattern — Entity with FK to another business entity
-
-When an entity has a FK to another business entity (e.g., `Absence.EmployeeId → Employee`), use navigation properties **directly inside `.Select()`**. EF Core translates navigation access to SQL JOINs automatically — `.Include()` is NOT needed when using `.Select()`.
-
-```csharp
-// Example: Absence has FK EmployeeId → Employee
-public async Task<PaginatedResult<AbsenceResponseDto>> GetAllAsync(
-    string? search = null, int page = 1, int pageSize = 20, CancellationToken ct = default)
-{
-    var tenantId = _currentTenant.TenantId
-        ?? throw new TenantContextRequiredException();
-
-    var query = _db.Absences
-        .Where(x => x.TenantId == tenantId)
-        .AsNoTracking();
-
-    if (!string.IsNullOrWhiteSpace(search))
-    {
-        query = query.Where(x =>
-            x.Employee.Code.Contains(search) ||       // Navigate FK in Where — EF translates to JOIN
-            x.Employee.User!.LastName.Contains(search));
-    }
-
-    // CORRECT: Inline construction — access FK navigation directly in Select()
-    // EF Core generates the JOIN automatically. Do NOT use .Include() here.
-    return await query
-        .OrderByDescending(x => x.StartDate)
-        .Select(x => new AbsenceResponseDto(
-            x.Id, x.StartDate, x.EndDate, x.Type,
-            x.EmployeeId, x.Employee.Code,
-            x.Employee.User!.FirstName, x.Employee.User!.LastName))
-        .ToPaginatedResultAsync(page, pageSize, ct);
-}
-
-// GetByIdAsync — same inline Select pattern
-public async Task<AbsenceResponseDto?> GetByIdAsync(Guid id, CancellationToken ct)
-{
-    var tenantId = _currentTenant.TenantId
-        ?? throw new TenantContextRequiredException();
-
-    return await _db.Absences
-        .Where(x => x.Id == id && x.TenantId == tenantId)
-        .AsNoTracking()
-        .Select(x => new AbsenceResponseDto(
-            x.Id, x.StartDate, x.EndDate, x.Type,
-            x.EmployeeId, x.Employee.Code,
-            x.Employee.User!.FirstName, x.Employee.User!.LastName))
-        .FirstOrDefaultAsync(ct);
-}
-
-// CreateAsync — use .Include() AFTER materialization (need full entity for response)
-public async Task<AbsenceResponseDto> CreateAsync(CreateAbsenceDto dto, CancellationToken ct)
-{
-    var tenantId = _currentTenant.TenantId
-        ?? throw new TenantContextRequiredException();
-
-    // Verify FK target exists in same tenant
-    var employeeExists = await _db.Employees
-        .AnyAsync(e => e.Id == dto.EmployeeId && e.TenantId == tenantId, ct);
-    if (!employeeExists)
-        throw new KeyNotFoundException($"Employee {dto.EmployeeId} not found");
-
-    var entity = Absence.Create(tenantId, dto.EmployeeId, dto.StartDate, dto.EndDate, dto.Type);
-    entity.CreatedBy = _currentUser.UserId?.ToString();
-
-    _db.Absences.Add(entity);
-    await _db.SaveChangesAsync(ct);
-
-    // Reload with FK navigation for response
-    var created = await _db.Absences
-        .Include(x => x.Employee).ThenInclude(e => e.User)
-        .FirstAsync(x => x.Id == entity.Id, ct);
-
-    return new AbsenceResponseDto(
-        created.Id, created.StartDate, created.EndDate, created.Type,
-        created.EmployeeId, created.Employee.Code,
-        created.Employee.User!.FirstName, created.Employee.User!.LastName);
-}
-```
+## Service Pattern (guard rails)
 
-> **Rules for FK inter-entity services:**
-> - **GetAllAsync / GetByIdAsync:** Use `.Select()` with inline navigation access (e.g., `x.Employee.Code`). Do NOT use `.Include()` — it is ignored when `.Select()` is present. EF Core generates the JOIN from the navigation path.
-> - **CreateAsync / UpdateAsync:** Use `.Include()` AFTER `SaveChangesAsync()` to reload the entity with its FK navigation for the response DTO.
-> - **FK validation:** Always verify the FK target exists in the same tenant before creating/updating.
-> - **Navigation depth:** Limit to 1-2 levels (e.g., `x.Employee.User.LastName`). Deeper navigation generates complex JOINs — consider denormalization if needed.
-> - **Search:** Include FK display fields in the search filter (e.g., `x.Employee.Code.Contains(search)`).
+> MCP `scaffold_extension` generates complete services. These are the mandatory conventions.
 
-**Key interfaces (from SmartStack NuGet package):**
-- `ICurrentUserService` (from `SmartStack.Application.Common.Interfaces.Identity`): provides `UserId` (Guid?), `Email` (string?), `IsAuthenticated` (bool)
-- `ICurrentTenantService` (from `SmartStack.Application.Common.Interfaces.Tenants`): provides `TenantId` (Guid?), `HasTenant` (bool), `TenantSlug` (string?)
+**Key interfaces:**
+- `ICurrentUserService` (`SmartStack.Application.Common.Interfaces.Identity`): `UserId` (Guid?), `Email` (string?), `IsAuthenticated` (bool)
+- `ICurrentTenantService` (`SmartStack.Application.Common.Interfaces.Tenants`): `TenantId` (Guid?), `HasTenant` (bool), `TenantSlug` (string?)
 - `IExtensionsDbContext` (for client extensions) or `ICoreDbContext` (for platform)
 
 **Guard clause (first line of every method):**
@@ -585,273 +250,136 @@ public async Task<AbsenceResponseDto> CreateAsync(CreateAbsenceDto dto, Cancella
 var tenantId = _currentTenant.TenantId
     ?? throw new TenantContextRequiredException();
 ```
-This converts a null TenantId into a clean 400 Bad Request response via `GlobalExceptionHandlerMiddleware`.
-**IMPORTANT:** Uses `TenantContextRequiredException` (400), NOT `UnauthorizedAccessException` (401). A missing tenant is a bad request, not an auth failure — the JWT is valid, `[Authorize]` passed.
-
-Do not use in services:
-- `_currentTenant.TenantId!.Value` — throws `InvalidOperationException` (500) instead of clean 400
-- `UnauthorizedAccessException("Tenant context is required")` — throws 401, triggers frontend token clearing
-- `tenantId: Guid.Empty` — always use validated tenantId from guard clause
-- Queries WITHOUT `.Where(x => x.TenantId == tenantId)` — data leak
+Returns clean 400 Bad Request via `GlobalExceptionHandlerMiddleware`.
+Uses `TenantContextRequiredException` (400), NOT `UnauthorizedAccessException` (401 — clears frontend token).
+
+**Do NOT use in services:**
+- `_currentTenant.TenantId!.Value` — throws 500 instead of clean 400
+- `UnauthorizedAccessException("Tenant context is required")` — returns 401, triggers frontend token clearing
+- `tenantId: Guid.Empty` — always use validated `_currentTenant.TenantId`
+- Queries WITHOUT `.Where(x => x.TenantId == tenantId)` — data leak (OWASP A01)
+- `ICurrentUser` (does NOT exist) — use `ICurrentUserService` + `ICurrentTenantService`
 - Missing `ILogger<T>` — undiagnosable in production
-- Using `ICurrentUser` (does NOT exist) — use `ICurrentUserService` + `ICurrentTenantService`
+
+### FK Inter-Entity Service Rules
+
+When an entity has a FK to another business entity (e.g., `Absence.EmployeeId → Employee`):
+
+- **GetAllAsync / GetByIdAsync:** Use `.Select()` with inline navigation access (e.g., `x.Employee.Code`). Do NOT use `.Include()` — it is ignored when `.Select()` is present. EF Core generates JOINs from navigation paths.
+- **CreateAsync / UpdateAsync:** Use `.Include()` AFTER `SaveChangesAsync()` to reload entity with FK navigation for response DTO.
+- **FK validation:** Always verify FK target exists in same tenant before create/update.
+- **Search:** Include FK display fields in search filter (e.g., `x.Employee.Code.Contains(search)`).
+- **Navigation depth:** Limit to 1-2 levels (e.g., `x.Employee.User!.LastName`). Deeper = complex JOINs.
+
+> **IQueryable .Select() constraint:** NEVER call helper methods (e.g., `MapToDto(x)`) inside `.Select()` on IQueryable — EF Core cannot translate to SQL → runtime `InvalidOperationException`. Use inline DTO construction only. Helpers are fine AFTER materialization (`ToListAsync`).
+
+> **FK navigation in `.Select()` is safe:** `.Select(x => new Dto(x.Id, x.Employee.Code, x.Employee.User!.LastName))` — EF Core translates to SQL JOINs.
 
 ---
 
 ## Controller Pattern (NavRoute)
 
-```csharp
-using Microsoft.AspNetCore.Authorization;
-using Microsoft.AspNetCore.Mvc;
-using SmartStack.Api.Routing;
-using SmartStack.Api.Authorization;
-
-namespace {ProjectName}.Api.Controllers.{App};
+> `/controller` skill or MCP generates complete controllers. These are the mandatory conventions.
 
+```csharp
 [ApiController]
-[NavRoute("{app}.{module}")]
-[Authorize]
+[NavRoute("{app}.{module}")]  // ONLY route attribute — resolves from DB at startup
+[Microsoft.AspNetCore.Authorization.Authorize]
+[Produces("application/json")]
+[Tags("{NamePlural}")]
 public class {Name}Controller : ControllerBase
 {
-    private readonly I{Name}Service _service;
-    private readonly ILogger<{Name}Controller> _logger;
+    private readonly ISender _mediator;  // MediatR — NOT I{Name}Service
 
-    public {Name}Controller(I{Name}Service service, ILogger<{Name}Controller> logger)
-    {
-        _service = service;
-        _logger = logger;
-    }
+    public {Name}Controller(ISender mediator) => _mediator = mediator;
 
     [HttpGet]
-    [RequirePermission(Permissions.{Module}.Read)]
-    public async Task<ActionResult<PaginatedResult<{Name}ResponseDto>>> GetAll(
-        [FromQuery] string? search = null,
-        [FromQuery] int page = 1,
-        [FromQuery] int pageSize = 20,
-        CancellationToken ct = default)
-        => Ok(await _service.GetAllAsync(search, page, pageSize, ct));
-
-    [HttpGet("{id:guid}")]
-    [RequirePermission(Permissions.{Module}.Read)]
-    public async Task<ActionResult<{Name}ResponseDto>> GetById(Guid id, CancellationToken ct)
-    {
-        var result = await _service.GetByIdAsync(id, ct);
-        return result is null ? NotFound() : Ok(result);
-    }
+    [RequirePermission(Permissions.{Module}.{NamePlural}.View)]
+    [ProducesResponseType(typeof(List<{Name}ListDto>), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
+    public async Task<ActionResult<List<{Name}ListDto>>> GetAll(CancellationToken ct)
+        => Ok(await _mediator.Send(new Get{NamePlural}Query(), ct));
 
-    [HttpPost]
-    [RequirePermission(Permissions.{Module}.Create)]
-    public async Task<ActionResult<{Name}ResponseDto>> Create([FromBody] Create{Name}Dto dto, CancellationToken ct)
-    {
-        var result = await _service.CreateAsync(dto, ct);
-        return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
-    }
-
-    [HttpPut("{id:guid}")]
-    [RequirePermission(Permissions.{Module}.Update)]
-    public async Task<ActionResult<{Name}ResponseDto>> Update(Guid id, [FromBody] Update{Name}Dto dto, CancellationToken ct)
-    {
-        var result = await _service.UpdateAsync(id, dto, ct);
-        return result is null ? NotFound() : Ok(result);
-    }
-
-    [HttpDelete("{id:guid}")]
-    [RequirePermission(Permissions.{Module}.Delete)]
-    public async Task<ActionResult> Delete(Guid id, CancellationToken ct)
-    {
-        await _service.DeleteAsync(id, ct);
-        return NoContent();
-    }
+    // GetById, Create (CreatedAtAction), Update, Delete (NoContent)
 }
 ```
 
-Route attribute rules:
-- `[NavRoute]` is the ONLY route attribute needed — it resolves routes dynamically from Navigation entities at startup
-- Do not use `[Route("api/...")]` alongside `[NavRoute]` — causes route conflicts and 404s at runtime
-- Do not use `[Route("api/[controller]")]` — this is standard ASP.NET Core, NOT SmartStack
-- If a controller has `[NavRoute]`, there must be NO `[Route]` attribute on the class
-
-Use `[RequirePermission(Permissions.{Module}.{Action})]` on every endpoint — do not use `[Authorize]` alone (no RBAC enforcement).
-
-Permission paths must use identical segments to NavRoute codes (kebab-case):
-- NavRoute: `human-resources.employees` → Permission: `human-resources.employees.read`
-- NavRoute: `human-resources.employees.leaves` → Permission: `human-resources.employees.leaves.read`
-- Do not use: `humanresources.employees.read` (no kebab-case — mismatches NavRoute)
-- SmartStack.app convention: `support-client.my-tickets.read` (always kebab-case)
-
-### Section-Level Controller (NavRoute with 3 segments)
+**Key conventions:**
+- `ISender _mediator` (MediatR) — NOT `I{Name}Service` or `IApplicationDbContext`
+- `[Microsoft.AspNetCore.Authorization.Authorize]` — fully qualified (not `[Authorize]` with using)
+- `[Tags("...")]` and `[Produces("application/json")]` — always present
+- `[RequirePermission(Permissions.{Module}.{Resource}.View)]` — permission constants, not string literals
+- `[ProducesResponseType]` with `StatusCodes.*` constants — always include 401/403
+- Return types: `List<ListDto>` (GetAll), `DetailDto` (GetById/Create/Update), `IActionResult` (Delete)
 
-When a module has sections, each section gets its own controller with a 3-segment navRoute:
+**NavRoute rules:**
+- `[NavRoute]` is the ONLY route attribute — do NOT combine with `[Route("api/...")]` (causes 404s)
+- `[RequirePermission]` on every endpoint — `[Authorize]` alone has no RBAC
+- Permission paths must match NavRoute kebab-case: `human-resources.employees.read`
+- Namespace: `SmartStack.Api.Routing` (NOT `SmartStack.Api.Core.Routing`)
+- NavRoute resolves at startup from DB: `administration.users` → `api/administration/users`
+- `CustomSegment` support: `[NavRoute("...", CustomSegment = "user/dashboard")]` for custom URL segments
 
-```csharp
-// Section-level controller: navRoute has 3 segments
-[ApiController]
-[NavRoute("{app}.{module}.{section}")]
-[Authorize]
-public class {Section}Controller : ControllerBase
-{
-    // Example: human-resources.employees.departments
-    [HttpGet]
-    [RequirePermission(Permissions.{Section}.Read)]
-    public async Task<ActionResult<PaginatedResult<{Section}ResponseDto>>> GetAll(
-        [FromQuery] string? search = null,
-        [FromQuery] int page = 1,
-        [FromQuery] int pageSize = 20,
-        CancellationToken ct = default)
-        => Ok(await _service.GetAllAsync(search, page, pageSize, ct));
-}
-```
+**NavRoute segment rules:**
 
-**NavRoute segment rules (minimum 2 segments):**
-| Level | NavRoute format | Example |
-|-------|----------------|---------|
+| Level | Format | Example |
+|-------|--------|---------|
 | Module | `{app}.{module}` (2 segments) | `administration.users` |
 | Section | `{app}.{module}.{section}` (3 segments) | `administration.users.groups` |
-| Sub-resource (Suffix) | `{app}.{module}` + Suffix | `administration.ai` + `Suffix = "prompts"` |
-
-> **POST-CONTEXT REMOVAL:** The old "context" level (1st segment) has been removed.
-> Before: `platform.administration.users` (3 segments). After: `administration.users` (2 segments).
-> The NavigationRouteRegistryBuilder builds 2-segment paths from DB (application.module).
-> Controllers with 3+ segments use the fallback route generator (dots → slashes).
-
-**Namespace:** `SmartStack.Api.Routing` (NOT `SmartStack.Api.Core.Routing`)
-
-**NavRoute resolves at startup from DB:** `administration.users` → `api/administration/users`
-
-### Sub-Resource Pattern (NavRoute Suffix)
-
-When an entity is a child of another entity (e.g., AiPrompts under AI), use `[NavRoute(..., Suffix = "...")]`:
+| Sub-resource | `{app}.{module}` + `Suffix` | `[NavRoute("administration.ai", Suffix = "prompts")]` |
 
-```csharp
-// Sub-resource controller: prompts are nested under AI module
-[ApiController]
-[NavRoute("administration.ai", Suffix = "prompts")]
-[Authorize]
-public class AiPromptsController : ControllerBase
-{
-    [HttpGet]
-    [RequirePermission(Permissions.Ai.Prompts.Read)]
-    public async Task<ActionResult<PaginatedResult<AiPromptResponseDto>>> GetAll(...)
-        => Ok(await _service.GetAllAsync(search, page, pageSize, ct));
-}
-```
+> POST-CONTEXT REMOVAL: Old "context" level removed. 2-segment minimum. `NavigationRouteRegistryBuilder` builds 2-segment paths from DB. 3+ segments use fallback route generator.
 
-**Alternative pattern** (sub-resource endpoints within parent controller):
-```csharp
-// LeaveTypes as endpoints within LeavesController
-[HttpGet("types")]
-[RequirePermission(Permissions.Leaves.Read)]
-public async Task<ActionResult<PaginatedResult<LeaveTypeResponseDto>>> GetAllLeaveTypes(...)
-```
-
-> Sub-resource frontend completeness:
-> If a parent page has a button (e.g., "Manage Leave Types") that `navigate()`s to a sub-resource route,
-> the frontend must include a page component for that route. Otherwise → dead link → white screen.
-> - Either create a dedicated sub-resource ListPage (e.g., `LeaveTypesPage.tsx`)
-> - Or do not include the navigate() button if pages won't be created
-> - Prefer separate controllers (with Suffix) over sub-endpoints in parent controller — easier to route
+**Sub-resource completeness:** If a parent page has a navigate() to a sub-resource route, the frontend MUST include a page for that route. Otherwise → dead link → white screen. Prefer separate controllers (with Suffix) over sub-endpoints in parent controller.
 
 ---
 
-## Navigation Seed Data Pattern (routes must be full paths)
-
-> **The navigation seed data defines menu routes stored in DB. These routes MUST be full paths starting with `/`.**
-> Short routes (e.g., `humanresources`) cause 400 Bad Request on application-tracking.
-
-### Route Convention
+## Navigation Seed Data (routes must be full paths)
 
 | Level | Route Format | Example |
 |-------|-------------|---------|
 | Application | `/{app-kebab}` | `/human-resources` |
 | Module | `/{app-kebab}/{module-kebab}` | `/human-resources/employees` |
 | Section | `/{app-kebab}/{module-kebab}/{section-kebab}` | `/human-resources/employees/departments` |
-| Resource | `/{app-kebab}/{module-kebab}/{section-kebab}/{resource-kebab}` | `/human-resources/employees/departments/export` |
 
-**Route special cases (list and detail sections):**
-> The `list` and `detail` sections are NOT functional sub-areas — they are view modes of the module itself.
-> Their navigation routes must NOT add extra segments:
-> - `list` section route = module route (e.g., `/human-resources/employees`)
-> - `detail` section route = module route + `/:id` (e.g., `/human-resources/employees/:id`)
-> - Do not use: `/employees/list`, `/employees/detail/:id`
-> - Other sections (dashboard, approve, import, etc.) = module route + `/{section-kebab}` (normal behavior)
+**Route special cases:** `list` and `detail` sections are view modes, NOT sub-areas:
+- `list` route = module route (e.g., `/human-resources/employees`)
+- `detail` route = module route + `/:id`
+- Do NOT use: `/employees/list`, `/employees/detail/:id`
 
 **Rules:**
-- Routes ALWAYS start with `/`
-- Routes ALWAYS include the full hierarchy from application to current level
-- Routes ALWAYS use kebab-case (NOT PascalCase, NOT camelCase)
-- Code identifiers stay PascalCase in C# (`HumanResources`) but routes are kebab-case (`human-resources`)
-
-### ToKebabCase Helper (include in SeedConstants or SeedDataProvider)
+- Routes ALWAYS start with `/`, include full hierarchy, use kebab-case
+- Code identifiers: PascalCase in C# (`HumanResources`), kebab-case in routes (`human-resources`)
 
+**ToKebabCase helper:**
 ```csharp
 private static string ToKebabCase(string value)
-    => System.Text.RegularExpressions.Regex
-        .Replace(value, "([a-z])([A-Z])", "$1-$2")
-        .ToLowerInvariant();
+    => Regex.Replace(value, "([a-z])([A-Z])", "$1-$2").ToLowerInvariant();
 ```
 
-### GUID Generation Rule
-
-```csharp
-// ALWAYS use Guid.NewGuid() for ALL seed data IDs
-// Avoids conflicts between projects/tenants/environments
-// Idempotence is handled by Code-based lookups at runtime
-// Navigation entities are resolved by Code, not by fixed GUIDs
-```
-
-### Navigation Seed Data Example
-
-```csharp
-// Application: /human-resources
-var app = NavigationApplication.Create(
-    "human-resources", "Human Resources", "HR Management",
-    "Users", IconType.Lucide,
-    "/human-resources",  // FULL PATH — starts with /, kebab-case
-    10);
-
-// Module: /human-resources/employees
-var module = NavigationModule.Create(
-    app.Id, "employees", "Employees", "Employee management",
-    "UserCheck", IconType.Lucide,
-    "/human-resources/employees",  // FULL PATH — includes parent
-    10);
-
-// Section: /human-resources/employees/departments
-var section = NavigationSection.Create(
-    module.Id, "departments", "Departments", "Manage departments",
-    "Building2", IconType.Lucide,
-    "/human-resources/employees/departments",  // FULL PATH
-    10);
-```
-
-### Avoid in Seed Data
+**GUID rule:** Always `Guid.NewGuid()` for seed data IDs. Idempotence via Code-based lookups at runtime.
 
 | Mistake | Reality |
 |---------|---------|
 | `"humanresources"` as route | Must be `"/human-resources"` (full path, kebab-case) |
 | `"employees"` as route | Must be `"/human-resources/employees"` (includes parent) |
-| Deterministic/sequential/fixed GUIDs in seed data | Use `Guid.NewGuid()` instead |
+| Fixed/sequential GUIDs | Use `Guid.NewGuid()` |
 | Missing translations | Must have 4 languages: fr, en, it, de |
 | Missing NavigationApplicationSeedData | Menu invisible without Application level |
 
 ---
 
-## DbContext Pattern (extensions)
+## DbContext Pattern
 
 ```csharp
-// In IExtensionsDbContext.cs:
-public DbSet<{Name}> {Name}s => Set<{Name}>();
-
-// In ExtensionsDbContext.cs (same line):
+// In IExtensionsDbContext.cs AND ExtensionsDbContext.cs:
 public DbSet<{Name}> {Name}s => Set<{Name}>();
 ```
 
----
-
-## DI Registration Pattern
+## DI Registration
 
 ```csharp
-// In DependencyInjection.cs or ServiceCollectionExtensions.cs:
 services.AddScoped<I{Name}Service, {Name}Service>();
 services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 ```
@@ -860,418 +388,93 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 
 ## DTO Type Mapping
 
-> **Use the correct .NET type for each property.** Incorrect types cause runtime parsing errors.
-
 | Property Pattern | .NET Type | JSON Format | Example |
 |-----------------|-----------|-------------|---------|
-| `*Date`, `StartDate`, `EndDate`, `BirthDate` | `DateOnly` | `"2025-03-15"` | `public DateOnly Date { get; set; }` |
+| `*Date`, `StartDate`, `BirthDate` | `DateOnly` | `"2025-03-15"` | `public DateOnly Date { get; set; }` |
 | `CreatedAt`, `UpdatedAt` | `DateTime` | `"2025-03-15T10:30:00Z"` | `public DateTime CreatedAt { get; set; }` |
 | `*Time`, `StartTime` | `TimeOnly` | `"14:30:00"` | `public TimeOnly StartTime { get; set; }` |
 | Duration, hours | `decimal` | `8.5` | `public decimal HoursWorked { get; set; }` |
 | FK reference | `Guid` | `"uuid-string"` | `public Guid EmployeeId { get; set; }` |
 
-Do not use in DTOs:
-- `string Date` / `string StartDate` — use `DateOnly`
-- `string Time` — use `TimeOnly`
-- `DateTime BirthDate` — use `DateOnly` (no time component needed)
-- `int` for hours/duration — use `decimal` for fractional values
-
----
-
-## Common Mistakes to Avoid
-
-| Mistake | Reality |
-|---------|---------|
-| `entity.SoftDelete()` | Does NOT exist — no soft delete in BaseEntity |
-| `entity.Code` inherited | Code is a business property — add it yourself |
-| `e.RowVersion` in config | Does NOT exist in BaseEntity |
-| `e.IsDeleted` filter | Does NOT exist — no soft delete |
-| `SmartStack.Api.Core.Routing` | Wrong — use `SmartStack.Api.Routing` |
-| `SystemEntity` base class | Does NOT exist — use `BaseEntity` for all |
-| `[Route("api/...")] + [NavRoute]` | Do not combine — causes 404s. Only `[NavRoute]` needed (resolves route from DB at startup). Remove `[Route]` when `[NavRoute]` is present. |
-| `SmartStack.Domain.Common.Interfaces` | Wrong — interfaces are in `SmartStack.Domain.Common` directly |
-| `[Authorize]` without `[RequirePermission]` | No RBAC enforcement — always use `[RequirePermission]` |
-| `tenantId: Guid.Empty` in services | OWASP A01 — always use validated `_currentTenant.TenantId` |
-| Service without `ICurrentTenantService` | All tenant data leaks — inject `ICurrentTenantService` |
-| `ICurrentUser` in service code | Does NOT exist — use `ICurrentUserService` + `ICurrentTenantService` |
-| `_currentTenant.TenantId!.Value` | Crashes with 500 — use `?? throw new TenantContextRequiredException()` |
-| `UnauthorizedAccessException("Tenant context is required")` | Returns 401 → clears frontend token. Use `TenantContextRequiredException()` (400) |
-| Route `"humanresources"` in seed data | Must be full path `"/human-resources"` |
-| Route without leading `/` | All routes must start with `/` |
-| `humanresources.employees.read` in permissions | Permission segments MUST match NavRoute kebab-case: `human-resources.employees.read` |
-| `Permission.Create()` | Does NOT exist — use `CreateForModule()`, `CreateForSection()`, etc. |
-| `GetAllAsync()` without search param | ALL GetAll endpoints MUST support `?search=` for EntityLookup |
-| `string Date` in DTO | Date-only fields must use `DateOnly`, not `string` |
-| `DateTime` for date-only | Use `DateOnly` when no time component needed |
-| FK field as plain text input | Frontend MUST use `EntityLookup` component for Guid FK fields |
-| `PagedResult<T>` / `PaginatedResultDto<T>` | Use `PaginatedResult<T>` instead |
-| Controller injects `DbContext` | Create an Application service and inject it instead (Clean Architecture) |
-| Domain entity has `[Table]` attribute | Infrastructure concern in Domain — move to `IEntityTypeConfiguration<T>` in Infrastructure |
-| `using Microsoft.EntityFrameworkCore` in Domain | EF Core belongs in Infrastructure, not Domain — Domain must be persistence-ignorant |
-| Controller returns `Employee` entity | Domain leak in API response — return `EmployeeResponseDto` instead |
-| `IEmployeeService.cs` in Infrastructure | Interface belongs in Application — move to `Application/Interfaces/` |
-| Service implementation in Application layer | Implementations belong in Infrastructure — Application only contains interfaces |
-| Controller injects `IRepository<T>` directly | Controllers use Application services, not repositories — add a service layer |
-| `FirstName`/`LastName`/`Email` on mandatory person extension entity | These come from User — use `Display*` computed properties from the User join |
-| Missing `Include(x => x.User)` on person extension service | Person extension entities MUST always include User for display fields |
-| Missing unique index on `(TenantId, UserId)` for person extension | One person-role per User per Tenant — add unique constraint in EF config |
-
----
-
-## External Application & Data Export Pattern
-
-### Entities
-
-| Entity | Table | Description |
-|--------|-------|-------------|
-| `ExternalApplication` | `auth_ExternalApplications` | Machine-to-machine API account (ClientId, ClientSecret, IsActive, IP whitelist) |
-| `ExternalApplicationRole` | `auth_ExternalApplicationRoles` | Role assignment per app (AppId, RoleId, optional TenantId) |
-| `ExternalApplicationExportAccess` | `auth_ExternalApplicationExportAccesses` | Per-app access to specific export endpoint (IsEnabled, RateLimitPerMinute, MaxPageSize) |
-| `DataExportEndpoint` | `auth_DataExportEndpoints` | Registry of available export APIs (Code, RouteTemplate, RequiredPermission, EntityType) |
-| `ExternalAppAuditLog` | `auth_ExternalAppAuditLogs` | Audit trail for all API calls (Authentication, DataExport actions) |
-
-### Architecture (3-layer security)
-
-1. **Authentication** — JWT assertion signed with ClientSecret → ExternalApplicationAuthService validates → generates SmartStack JWT with permissions resolved via ExternalApplicationRole → Role → RolePermission chain
-2. **Authorization** — RequirePermissionFilter checks JWT claims (e.g., `administration.users.export`)
-3. **Access Control** — DataExportAccessMiddleware verifies per-app endpoint access in ExternalApplicationExportAccess table
-
-### Rate Limiting
-
-ExternalAppRateLimitPolicy resolves limits: app override → endpoint default → 60/min fallback.
-Partition key: `{clientId}:{endpointCode}`.
-
-### Seed Data
-
-DataExportEndpoints are seeded in DataExportEndpointConfiguration.cs with FK to NavigationApplication and NavigationModule. Each endpoint maps to a controller in `Controllers/DataExport/v1/`.
-
-### Controller Pattern
-
-Export controllers: `[Route("api/v1/export")]` + `[RequirePermission]` + `[EnableRateLimiting]`
-
-**Query Parameters (all export endpoints except Navigation):**
-- `tenantId` (UUID, required) — Scopes the export to the specified tenant's data
-
-Example: `GET /api/v1/export/users?tenantId=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=50`
-
-Management controllers: `[NavRoute("api.accounts")]` with CustomSegment
+Do NOT use: `string Date` (use `DateOnly`), `DateTime BirthDate` (use `DateOnly`), `int` for hours (use `decimal`).
 
 ---
 
-## PaginatedResult Pattern
-
-> **Canonical type for ALL paginated responses.** One name, one contract, everywhere.
+## PaginatedResult
 
-### Definition (Backend — `SmartStack.Application.Common.Models`)
+> **Canonical type — one name, one contract, everywhere.**
 
 ```csharp
-namespace SmartStack.Application.Common.Models;
-
-public record PaginatedResult<T>(
-    List<T> Items,
-    int TotalCount,
-    int Page,
-    int PageSize)
+// SmartStack.Application.Common.Models
+public record PaginatedResult<T>(List<T> Items, int TotalCount, int Page, int PageSize)
 {
-    public int TotalPages => PageSize > 0
-        ? (int)Math.Ceiling((double)TotalCount / PageSize) : 0;
+    public int TotalPages => PageSize > 0 ? (int)Math.Ceiling((double)TotalCount / PageSize) : 0;
     public bool HasPreviousPage => Page > 1;
     public bool HasNextPage => Page < TotalPages;
-
-    public static PaginatedResult<T> Empty(int page = 1, int pageSize = 20)
-        => new([], 0, page, pageSize);
+    public static PaginatedResult<T> Empty(int page = 1, int pageSize = 20) => new([], 0, page, pageSize);
 }
-```
 
-### Extension Method
-
-```csharp
-namespace SmartStack.Application.Common.Extensions;
-
-public static class QueryableExtensions
-{
-    public const int MaxPageSize = 100;
-
-    public static async Task<PaginatedResult<T>> ToPaginatedResultAsync<T>(
-        this IQueryable<T> query,
-        int page = 1,
-        int pageSize = 20,
-        CancellationToken ct = default)
-    {
-        page = Math.Max(1, page);
-        pageSize = Math.Clamp(pageSize, 1, MaxPageSize);
-
-        var totalCount = await query.CountAsync(ct);
-        var items = await query
-            .Skip((page - 1) * pageSize)
-            .Take(pageSize)
-            .ToListAsync(ct);
-
-        return new PaginatedResult<T>(items, totalCount, page, pageSize);
-    }
-}
+// Extension method — SmartStack.Application.Common.Extensions
+public static Task<PaginatedResult<T>> ToPaginatedResultAsync<T>(
+    this IQueryable<T> query, int page = 1, int pageSize = 20, CancellationToken ct = default)
+// Implementation: Math.Max(1, page), Math.Clamp(pageSize, 1, 100), CountAsync, Skip/Take, ToListAsync
 ```
 
-### Usage in Service (with search + extension method)
-
-```csharp
-public async Task<PaginatedResult<{Name}ResponseDto>> GetAllAsync(
-    string? search = null, int page = 1, int pageSize = 20, CancellationToken ct = default)
-{
-    var tenantId = _currentTenant.TenantId
-        ?? throw new TenantContextRequiredException();
-
-    var query = _db.{Name}s
-        .Where(x => x.TenantId == tenantId)
-        .AsNoTracking();
-
-    if (!string.IsNullOrWhiteSpace(search))
-        query = query.Where(x => x.Name.Contains(search) || x.Code.Contains(search));
-
-    return await query
-        .OrderBy(x => x.Name)
-        .Select(x => new {Name}ResponseDto(x.Id, x.Code, x.Name, x.CreatedAt))
-        .ToPaginatedResultAsync(page, pageSize, ct);
-}
-```
-
-> **WARNING — IQueryable .Select() constraints:**
-> Inside `.Select()` on an `IQueryable` (before `ToListAsync`/`FirstAsync`), use ONLY inline DTO construction:
-> `.Select(x => new ResponseDto(x.Id, x.Code, x.Name))`
->
-> NEVER call a helper method (e.g., `MapToDto(x)`) inside `.Select()` — EF Core cannot translate method calls to SQL → runtime `InvalidOperationException`.
-> Helper methods are fine AFTER materialization (`ToListAsync`, `FirstAsync`, `SaveChangesAsync`).
->
-> **FK navigation in `.Select()` is safe:** `.Select(x => new Dto(x.Id, x.Employee.Code, x.Employee.User!.LastName))` — EF Core translates navigation property access to SQL JOINs. `.Include()` is NOT needed and is ignored when `.Select()` is used.
-
-### Frontend Types (`@/types/pagination.ts`)
-
-```typescript
-export interface PaginatedResult<T> {
-  items: T[];
-  totalCount: number;
-  page: number;
-  pageSize: number;
-  totalPages: number;
-  hasPreviousPage: boolean;
-  hasNextPage: boolean;
-}
-
-export interface PaginationParams {
-  page?: number;
-  pageSize?: number;
-  search?: string;
-  sortBy?: string;
-  sortDirection?: 'asc' | 'desc';
-}
-```
-
-### Type Names to Avoid
+**Frontend type:** `PaginatedResult<T>` with `items`, `totalCount`, `page`, `pageSize`, `totalPages`, `hasPreviousPage`, `hasNextPage`.
 
 | Avoid | Use Instead |
 |-------|------------|
-| `PagedResult<T>` | `PaginatedResult<T>` |
-| `PaginatedResultDto<T>` | `PaginatedResult<T>` |
-| `PaginatedResponse<T>` | `PaginatedResult<T>` |
-| `PageResultDto<T>` | `PaginatedResult<T>` |
-| `PaginatedRequest` | `PaginationParams` |
-| `QueryParameters` | `PaginationParams` |
+| `PagedResult<T>` / `PaginatedResultDto<T>` / `PaginatedResponse<T>` | `PaginatedResult<T>` |
 | `currentPage` (property) | `page` |
-| `HasPrevious` (property) | `HasPreviousPage` |
-| `HasNext` (property) | `HasNextPage` |
-
-### Rules
-
-- **Max pageSize = 100** — enforced via `Math.Clamp(pageSize, 1, 100)` or extension method
-- **Default page = 1, pageSize = 20** — all GetAll endpoints
-- **Search param mandatory** — enables `EntityLookup` on frontend
-- **POST-CHECK C12** blocks `List<T>` returns on GetAll
-- **POST-CHECK C28** blocks non-canonical pagination type names
-
----
-
-## Critical Anti-Patterns (with code examples)
-
-> **These are the most common and dangerous mistakes.** Each one has been observed in production code generation.
-
-### Anti-Pattern 1: HasQueryFilter with `!= Guid.Empty` (Security vulnerability)
-
-The `HasQueryFilter` in EF Core should use **runtime tenant resolution**, NOT a static comparison against `Guid.Empty`.
-
-**INCORRECT — Does NOT isolate tenants:**
-```csharp
-// WRONG: This only excludes empty GUIDs — ALL tenant data is still visible to everyone!
-public void Configure(EntityTypeBuilder<MyEntity> builder)
-{
-    builder.HasQueryFilter(e => e.TenantId != Guid.Empty);
-}
-```
-
-**CORRECT — Tenant isolation via service:**
-```csharp
-// Correct: In SmartStack, tenant filtering is done in the SERVICE layer, not via HasQueryFilter.
-public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(...)
-{
-    var query = _db.MyEntities
-        .Where(x => x.TenantId == _currentUser.TenantId)  // Required runtime filter
-        .AsNoTracking();
-    // ...
-}
-```
-
-**Why it's wrong:** `HasQueryFilter(e => e.TenantId != Guid.Empty)` is a **static filter** — it only removes records with empty GUIDs. It does NOT restrict data to the current tenant. This is an **OWASP A01 Broken Access Control** vulnerability.
-
----
-
-### Anti-Pattern 2: `List<T>` instead of `PaginatedResult<T>` for GetAll
-
-**INCORRECT — No pagination:**
-```csharp
-// WRONG: Returns all records at once — no pagination, no totalCount
-public async Task<List<MyEntityDto>> GetAllAsync(CancellationToken ct)
-{
-    return await _db.MyEntities
-        .Where(x => x.TenantId == _currentUser.TenantId)
-        .Select(x => new MyEntityDto(x.Id, x.Code, x.Name))
-        .ToListAsync(ct);
-}
-```
-
-**CORRECT — Paginated with search:**
-```csharp
-// Correct: Returns PaginatedResult<T> with search, page, pageSize
-public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(
-    string? search = null, int page = 1, int pageSize = 20, CancellationToken ct = default)
-{
-    var query = _db.MyEntities.Where(x => x.TenantId == _currentUser.TenantId).AsNoTracking();
-    if (!string.IsNullOrWhiteSpace(search))
-        query = query.Where(x => x.Name.Contains(search) || x.Code.Contains(search));
-    var totalCount = await query.CountAsync(ct);
-    var items = await query.OrderBy(x => x.Name).Skip((page - 1) * pageSize).Take(pageSize)
-        .Select(x => new MyEntityDto(x.Id, x.Code, x.Name, x.CreatedAt)).ToListAsync(ct);
-    return new PaginatedResult<MyEntityDto>(items, totalCount, page, pageSize);
-}
-```
-
-**Why it's wrong:** `List<T>` loads ALL records into memory. It also breaks `EntityLookup` which requires `{ items, totalCount }` response format.
-
----
-
-### Anti-Pattern 3: Missing `IAuditableEntity` on tenant entities
-
-**INCORRECT — No audit trail:**
-```csharp
-// WRONG: Tenant entity without IAuditableEntity
-public class MyEntity : BaseEntity, ITenantEntity
-{
-    public Guid TenantId { get; private set; }
-    public string Code { get; private set; } = null!;
-}
-```
-
-**CORRECT — Always pair ITenantEntity with IAuditableEntity:**
-```csharp
-public class MyEntity : BaseEntity, ITenantEntity, IAuditableEntity
-{
-    public Guid TenantId { get; private set; }
-    public string? CreatedBy { get; set; }
-    public string? UpdatedBy { get; set; }
-    public string Code { get; private set; } = null!;
-}
-```
-
-**Why it's wrong:** Without `IAuditableEntity`, there is no record of who created or modified data. Mandatory for compliance in multi-tenant environments.
-
----
-
-### Anti-Pattern 4: Code auto-generation with `Count() + 1`
-
-**INCORRECT — Race condition:**
-```csharp
-// WRONG: Two concurrent requests get the same count
-var count = await _db.MyEntities.Where(x => x.TenantId == tenantId).CountAsync(ct);
-return $"emp-{(count + 1):D5}";
-```
-
-**CORRECT — Use `ICodeGenerator<T>.NextCodeAsync()` (atomic with retry):**
-```csharp
-private readonly ICodeGenerator<MyEntity> _codeGenerator;
-
-// In CreateAsync:
-var code = await _codeGenerator.NextCodeAsync(ct);
-var entity = MyEntity.Create(tenantId, code, dto.Name, createdBy: null);
-```
+| `HasPrevious` / `HasNext` | `HasPreviousPage` / `HasNextPage` |
 
-**Why it's wrong:** `Count() + 1` causes **race conditions** — concurrent requests generate duplicate codes. `ICodeGenerator<T>` uses `OrderByDescending` on existing codes + retry on unique constraint violation for safe concurrency.
-
-**Key rules when using auto-generated codes:**
-- **REMOVE** `Code` from `CreateDto` (auto-generated, not user-provided)
-- **KEEP** `Code` in `ResponseDto` (returned to frontend)
-- Register `ICodeGenerator<T>` in DI with `CodePatternConfig`
-- Code regex in validators: `^[a-z0-9_-]+$` (supports hyphens)
-
-**Full reference:** See `references/code-generation.md` for strategies (sequential, timestamp, yearly, UUID), volume-to-digits calculation, and complete implementation patterns.
+**Rules:** Max pageSize = 100. Default page = 1, pageSize = 20. Search param mandatory (enables EntityLookup). POST-CHECK C12 blocks `List<T>` returns. POST-CHECK C28 blocks non-canonical type names.
 
 ---
 
-### Anti-Pattern 5: Missing Update validator
-
-**INCORRECT — Only CreateValidator:**
-```csharp
-public class CreateMyEntityDtoValidator : AbstractValidator<CreateMyEntityDto>
-{
-    public CreateMyEntityDtoValidator()
-    {
-        RuleFor(x => x.Code).NotEmpty().MaximumLength(100);
-        RuleFor(x => x.Name).NotEmpty().MaximumLength(200);
-    }
-}
-// No UpdateMyEntityDtoValidator exists!
-```
-
-**CORRECT — Always create validators in pairs:**
-```csharp
-public class CreateMyEntityDtoValidator : AbstractValidator<CreateMyEntityDto> { /* ... */ }
-public class UpdateMyEntityDtoValidator : AbstractValidator<UpdateMyEntityDto>
-{
-    public UpdateMyEntityDtoValidator()
-    {
-        RuleFor(x => x.Name).NotEmpty().MaximumLength(200);
-    }
-}
-```
+## Common Mistakes to Avoid
 
-**Why it's wrong:** Without an `UpdateValidator`, the Update endpoint accepts **any data without validation**.
+| Mistake | Reality |
+|---------|---------|
+| `entity.SoftDelete()` | Does NOT exist — no soft delete in BaseEntity |
+| `entity.Code` inherited | Code is a business property — add it yourself |
+| `e.RowVersion` / `e.IsDeleted` in config | Does NOT exist in BaseEntity |
+| `SmartStack.Api.Core.Routing` | Wrong — use `SmartStack.Api.Routing` |
+| `SystemEntity` base class | Does NOT exist — use `BaseEntity` for all |
+| `[Route("api/...")] + [NavRoute]` | Do not combine — causes 404s. Only `[NavRoute]` needed. |
+| `SmartStack.Domain.Common.Interfaces` | Interfaces are in `SmartStack.Domain.Common` directly |
+| `[Authorize]` without `[RequirePermission]` | No RBAC enforcement |
+| `tenantId: Guid.Empty` | OWASP A01 — use validated `_currentTenant.TenantId` |
+| `ICurrentUser` | Does NOT exist — use `ICurrentUserService` + `ICurrentTenantService` |
+| `_currentTenant.TenantId!.Value` | Throws 500 — use `?? throw new TenantContextRequiredException()` |
+| `UnauthorizedAccessException` for tenant | Returns 401 → clears token. Use `TenantContextRequiredException` (400) |
+| `Permission.Create()` | Does NOT exist — use `CreateForModule()`, `CreateForSection()`, etc. |
+| `GetAllAsync()` without search param | ALL GetAll MUST support `?search=` for EntityLookup |
+| `PagedResult<T>` | Use `PaginatedResult<T>` |
+| Controller injects `DbContext` | Controllers use `ISender _mediator` (MediatR) |
+| Controller injects `I{Name}Service` | Use `ISender _mediator` — MediatR dispatches to handlers |
+| `[Authorize]` with using statement | Use `[Microsoft.AspNetCore.Authorization.Authorize]` (fully qualified) |
+| Missing `[Tags]` / `[Produces]` | Always add `[Tags("...")]` and `[Produces("application/json")]` |
+| `[ProducesResponseType(200)]` integer literal | Use `StatusCodes.Status200OK` constants |
+| Missing 401/403 ProducesResponseType | Always include `StatusCodes.Status401Unauthorized` and `Status403Forbidden` |
+| `[Table]` attribute in Domain entity | Infrastructure concern — move to `IEntityTypeConfiguration<T>` |
+| `using Microsoft.EntityFrameworkCore` in Domain | EF Core belongs in Infrastructure — Domain must be persistence-ignorant |
+| Controller returns entity | Domain leak — return `ResponseDto` instead |
+| `IEmployeeService.cs` in Infrastructure | Interface → Application. Implementation → Infrastructure |
+| Service implementation in Application | Implementations → Infrastructure. Application = interfaces only |
+| Duplicate person fields on mandatory extension | Use `Display*` from User join |
+| Missing `Include(User)` on person extension | Always include User for display fields |
+| Missing unique index `(TenantId, UserId)` | Required for person extension entities |
 
 ---
 
-### Anti-Pattern 6: `TenantId!.Value` null-forgiving operator
-
-The `!` (null-forgiving) operator followed by `.Value` on a `Guid?` suppresses compiler warnings but **throws `InvalidOperationException` at runtime** when TenantId is null.
-
-**INCORRECT — Crashes with 500 Internal Server Error:**
-```csharp
-// Wrong: Throws InvalidOperationException("Nullable object must have a value") → 500 error
-public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(...)
-{
-    var tenantId = _currentTenant.TenantId!.Value;  // Crashes if no tenant context
-    var query = _db.MyEntities.Where(x => x.TenantId == tenantId);
-    // ...
-}
-```
-
-**CORRECT — Clean 400 via GlobalExceptionHandlerMiddleware:**
-```csharp
-// Correct: Throws TenantContextRequiredException → middleware converts to 400 Bad Request
-public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(...)
-{
-    var tenantId = _currentTenant.TenantId
-        ?? throw new TenantContextRequiredException();
-    var query = _db.MyEntities.Where(x => x.TenantId == tenantId);
-    // ...
-}
-```
-
-**Why `!.Value` is wrong:** When a user hits an API via Swagger with a valid JWT but no tenant context (missing `X-Tenant-Slug` header), `TenantId` is null. The `!.Value` pattern produces an opaque `500 Internal Server Error` instead of a clear `400 Bad Request` with an actionable message.
+## Critical Anti-Patterns (summary)
 
-**Why `UnauthorizedAccessException` is wrong:** A missing tenant is NOT an auth failure — the JWT is valid, `[Authorize]` passed. Using `UnauthorizedAccessException` returns 401, which triggers the frontend interceptor to clear the token and redirect to login. Use `TenantContextRequiredException` instead (returns 400, does not clear the token).
+| # | Anti-Pattern | Risk | Correct Approach |
+|---|-------------|------|-----------------|
+| 1 | `HasQueryFilter(e => e.TenantId != Guid.Empty)` | OWASP A01 — does NOT isolate tenants | Tenant filter in SERVICE: `.Where(x => x.TenantId == tenantId)` |
+| 2 | `List<T>` return on GetAll | No pagination, breaks EntityLookup | `PaginatedResult<T>` with search + page + pageSize |
+| 3 | `ITenantEntity` without `IAuditableEntity` | No audit trail | Always pair: `BaseEntity, ITenantEntity, IAuditableEntity` |
+| 4 | Code generation via `Count() + 1` | Race condition — duplicate codes | `ICodeGenerator<T>.NextCodeAsync()` (see `references/code-generation.md`) |
+| 5 | Only Create validator, no Update | Update accepts invalid data | Always create validators in pairs |
+| 6 | `TenantId!.Value` null-forgiving | 500 instead of 400 | `?? throw new TenantContextRequiredException()` |