diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..f26957c
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,31 @@
+# Clarity — Copilot Instructions
+
+## What is Clarity?
+Clarity is the tenant-facing product in ClarityStack. Each tenant gets their own isolated Clarity instance, provisioned and managed by OPC (the ControlPlane).
+
+## Projects
+| Project | Role |
+|---------|------|
+| `Clarity.AppHost` | .NET Aspire host — owns Postgres, Keycloak, Redis, MinIO, frontend |
+| `Clarity.Server` | REST API — main backend, EF Core, Keycloak auth, MinIO, Redis output caching |
+| `Clarity.MigrationService` | Worker that runs EF Core migrations on startup before the server starts |
+| `Clarity.ServiceDefaults` | Shared Aspire service defaults (OTel, resilience, service discovery) |
+
+## Aspire-owned Infrastructure
+- `postgres` on port `5432` — databases: `postgresdb`, `authdb` (Keycloak)
+- Keycloak on port `8080` with realm imported from `KeycloakConfig/`
+- Redis cache
+- MinIO object storage
+- Vite React frontend at `../frontend`
+
+## Auth
+- Keycloak is the identity provider — realm per tenant in production, `clarity` realm in dev
+- `Clarity.Server` uses `Aspire.Keycloak.Authentication`
+
+## Conventions
+- Commit format: `OPC # XXXX: Description`
+- Target framework: .NET 10
+- Nullable and ImplicitUsings enabled globally via root `Directory.Build.props`
+- Central package management via root `Directory.Packages.props`
+- EF Core migrations are handled by `Clarity.MigrationService`, not inline in the server
+- Frontend is a Vite React app at `Clarity/frontend/`