✨ Adds project guidelines and conventions for Github Copilot

Introduces detailed instructions for ASP.NET API, C#, Docker, MSBuild,
testing, and library creation. These guidelines aim to standardize
development practices and improve code quality across the project.

.github/instructions/aspnet-api.instructions.md

@@ -0,0 +1,32 @@
+---
+description: "Use when writing API endpoints, routing, middleware, request/response handling, OpenAPI configuration, or HTTP pipeline setup in ASP.NET. Covers Minimal API conventions, error handling, and endpoint organisation."
+---
+# ASP.NET API Conventions
+
+## Routing
+
+- All endpoints live under `/api/v{apiVersion}/{resource}`.
+- Default to `/api/v1` for projects without explicit API versioning.
+
+## Endpoints
+
+- Prefer **Minimal APIs**; use Controllers only when the added structure is justified.
+- Group related endpoints using `MapGroup()` with a shared prefix and tag.
+- Use **typed results** (`TypedResults.Ok()`, `TypedResults.NotFound()`) over untyped `Results` for OpenAPI metadata inference.
+- Return **`ProblemDetails`** (RFC 9457) for all error responses — configure via `AddProblemDetails()`.
+
+## Request Handling
+
+- Bind request data with **`[AsParameters]`** for complex parameter sets.
+- Validate input at the endpoint boundary — use **filters** or **`IValidatableObject`** to fail fast.
+- Use **`CancellationToken`** on all async endpoints.
+
+## Endpoint Organisation
+
+- One file per resource or feature area (e.g., `UserEndpoints.cs`, `OrderEndpoints.cs`).
+- Register via extension methods on `IEndpointRouteBuilder`: `MapUserEndpoints()`.
+- Keep endpoint lambdas thin — delegate business logic to injected services.
+
+## OpenAPI
+
+- Annotate endpoints with `.WithTags()` for grouping in the generated spec.

.github/instructions/csharp.instructions.md

@@ -0,0 +1,17 @@
+---
+description: "Use when writing or modifying C# source code. Covers non-obvious defaults not caught by analyzers."
+applyTo: "**/*.cs"
+---
+# C# Conventions
+
+Code style is enforced by `.editorconfig`, `.globalconfig`, and StyleCop analyzers — do not restate their rules.
+
+## Non-Obvious Defaults
+
+- XML doc comments required on public API in `src/` (suppressed in `tests/` and `samples/`).
+- Avoid `null!` (null-forgiving operator) — fix the nullability flow instead of suppressing the warning.
+
+## Patterns
+
+- Prefer **records** for DTOs, value objects, and other immutable data carriers.
+- Use `LoggerMessage`-generated `partial` methods on a `partial class` — never log inline (e.g., `logger.LogInformation(…)`).

.github/instructions/docker.instructions.md

@@ -0,0 +1,31 @@
+---
+description: "Use when editing Dockerfile, compose files, or Docker-related configuration. Covers guardrails for the multi-stage build and runtime image selection."
+applyTo: "docker/**,compose*.yaml"
+---
+# Docker Conventions
+
+`docker/Dockerfile` is a multi-stage pipeline — stage names and purposes are visible in the file itself.
+
+## Guardrails
+
+- **Build context** is always the repo root, not `docker/`.
+- **`COPY --link`** is used intentionally for layer cache — do not replace with plain `COPY`.
+- **Cache mounts** (`--mount=type=cache,target=/root/.nuget/packages`) must stay on restore, build, test, and publish steps.
+- **Stage dependency chain** must be preserved (e.g., `build` → `restore`, `test` → `build`, `publish` → `test`).
+- New stages should follow the existing pattern: `FROM <parent> AS <name>`.
+
+## Build Args
+
+- `RUNTIME_BASE`: `web` (ASP.NET), `app` (console), or `self-contained`
+- `CONFIGURATION`: `Release` (default) or `Debug`
+- `PUBLISHED_PROJECT`: Project name to publish (without path or extension)
+- `DATABASE_PROJECT`: EF Core project for migration bundles
+- `DBCONTEXT`: Optional DbContext name for migrations
+
+## Image Selection
+
+| Use Case | `RUNTIME_BASE` | Base Image |
+|----------|----------------|------------|
+| ASP.NET web apps | `web` | `aspnet:*-alpine-composite-extra` |
+| Console / worker | `app` | `runtime:*-alpine-extra` |
+| Self-contained | `self-contained` | `runtime-deps:*-alpine-extra` |

.github/instructions/msbuild.instructions.md

@@ -0,0 +1,39 @@
+---
+description: "Use when editing MSBuild files (.csproj, .props, .targets). Covers central package management, artifacts layout, and property inheritance."
+applyTo: "**/*.{csproj,props,targets}"
+---
+# MSBuild Conventions
+
+## Central Package Management
+
+All package versions are declared in `Directory.Packages.props` at the repo root. In `.csproj` files:
+
+```xml
+<!-- Correct -->
+<PackageReference Include="Newtonsoft.Json" />
+
+<!-- Wrong — never specify Version -->
+<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
+```
+
+To add or update a version, edit `Directory.Packages.props`:
+
+```xml
+<PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
+```
+
+## Properties Set Centrally (Do Not Override)
+
+These are configured in the root `Directory.Build.props` — do **not** set them in individual projects:
+
+`LangVersion`, `Nullable`, `ImplicitUsings`.
+
+## InternalsVisibleTo
+
+Handled automatically via `<InternalsVisibleToSuffix>` in the root props. Default suffixes are `.Tests` and `Tests`. To add custom visibility:
+
+<parameter name="newString">```xml
+<ItemGroup>
+  <InternalsVisibleTo Include="MyProject.IntegrationTests" />
+</ItemGroup>
+```

.github/instructions/testing.instructions.md

@@ -0,0 +1,23 @@
+---
+description: "Use when creating or modifying test projects under the tests/ folder. Covers naming conventions and structural guardrails."
+applyTo: "tests/**"
+---
+# Test Project Conventions
+
+Build configuration is handled by `tests/Directory.Build.props` — do not restate its settings.
+
+## Framework
+
+- **Testing**: TUnit.
+- **Mocking**: NSubstitute (analyzers auto-added when referenced).
+
+## Naming
+
+- Test project: `<ProjectUnderTest>.Tests` (matches InternalsVisibleTo default).
+- Test classes: `<ClassUnderTest>Tests`.
+- Test methods: descriptive names — `MethodName_Condition_ExpectedResult` or similar.
+
+## Structure
+
+- Follow **Arrange / Act / Assert**.
+- Always propose a set of basic tests for new or changed code.