# Copilot Instructions for Lutra

Use these standards when generating or modifying code in this repository.

## Project overview

- Target framework: .NET 10 (`net10.0`)
- Architecture: Clean Architecture
- Solution layers:
  - `Lutra.Domain`
  - `Lutra.Application`
  - `Lutra.Infrastructure.Sql`
  - `Lutra.API`
  - `Lutra.AppHost`
  - `Lutra.Infrastructure.Migrator`
- Database: PostgreSQL via EF Core
- Orchestration: .NET Aspire
- Messaging pattern: `Cortex.Mediator` for CQRS handling

## General standards

- Prefer small, focused changes.
- Follow existing naming, formatting, and folder conventions.
- Keep dependencies pointing inward:
  - Domain depends on nothing
  - Application depends on Domain
  - Infrastructure depends on Application and Domain
  - API depends on Application and Infrastructure
  - AppHost and Migrator are host projects only
- Use nullable reference types correctly and keep implicit usings compatible with the project style.

## Clean Architecture guidance

Use Jason Taylor’s CleanArchitecture project as a reference for intent and structure, but adapt to this codebase’s actual implementation.

Where the reference template uses MediatR, this project uses `Cortex.Mediator`.
Add FluentValidation, AutoMapper, NUnit, Shouldly, Moq, or Respawn only if the repository already uses them or the change clearly requires them.

## Domain layer rules

- Keep entities simple and focused on business state.
- Use `BaseEntity` as the shared base type when appropriate.
- Preserve the current entity style:
  - `Id` as `Guid`
  - audit fields like `CreatedAt`, `ModifiedAt`, `DeletedAt`
  - `IsDeleted` as a derived property
- Keep validation and persistence concerns out of Domain unless they are intrinsic business rules.

## Application layer rules

- Put use cases in feature folders.
- Follow the existing CQRS split:
  - `FeatureName.cs` as the partial entry point
  - `FeatureName.Query.cs` or `FeatureName.Command.cs`
  - `FeatureName.Handler.cs`
  - `FeatureName.Response.cs`
- Use `Cortex.Mediator` request and handler interfaces.
- Keep handlers focused on orchestration and application logic.
- Use `ILutraDbContext` rather than referencing the concrete DbContext directly when possible.

## Infrastructure rules

- Put EF Core implementation, migrations, and database wiring in `Lutra.Infrastructure.Sql`.
- Keep the DbContext implementation aligned with `ILutraDbContext`.
- If package versions must be pinned for runtime compatibility, pin them explicitly in the infrastructure project.
- Be cautious with `PrivateAssets="all"` on design-time packages because they do not flow dependency constraints to downstream projects.

## API layer rules

- Keep controllers thin.
- Controllers should delegate to Application use cases through `IMediator`.
- Keep `Program.cs` focused on DI and middleware setup.

## Aspire and migration rules

- Keep `Lutra.AppHost` responsible for orchestration only.
- Preserve the persistent PostgreSQL container setup unless a change explicitly requires otherwise.
- Keep the migrator as a one-shot project that applies migrations on startup.
- Ensure migration-related changes do not break runtime assembly/version consistency.

## Naming and code style

- Match the existing language of the codebase; this project uses Dutch domain names in places such as `Verspakketten`, `Supermarkt`, and `Beoordeling`.
- Keep class and file names consistent with the feature name.
- Use sealed types where the project already does.
- Prefer explicit `required` members where the current codebase uses them.
- Preserve current indentation and brace style in each file.

## Testing guidance

- If tests exist, update or add tests alongside behavior changes.
- Follow the reference template’s intent for test coverage:
  - unit tests for business logic
  - integration tests for infrastructure and data access
  - functional tests for API behavior
- Keep tests readable and focused on behavior.

## When making changes

- Read the relevant file before editing.
- Make the smallest change that solves the problem.
- Reuse existing patterns from the repo instead of inventing new ones.
- Run or request a build/test verification after changes when appropriate.
- Avoid broad refactors unless the user asks for them.

## Available agents

Specialist agents for common tasks are in `.github/agents/`. Invoke them when the task matches:

| Agent file | When to use |
|---|---|
| `csharp-expert.agent.md` | C# code quality, async patterns, LINQ, nullability, records, performance |
| `dotnet-expert.agent.md` | .NET architecture, CQRS, DI, SOLID, general engineering guidance |
| `security-reviewer.agent.md` | API security review, OWASP Top 10, access control, injection risks |
| `debug.agent.md` | Diagnosing and fixing bugs systematically |
| `postgresql-dba.agent.md` | PostgreSQL queries, schema, migrations, performance |
| `test-generator.agent.md` | Generating unit, integration, or functional tests for any layer |