diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..4d98fc7
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,20 @@
+# gateway — Copilot Instructions
+
+## What is gateway?
+The shared ingress layer for ClarityStack. Routes all `*.clarity.test` traffic to the correct tenant Clarity instance and platform services.
+
+## Components
+| Component | Purpose |
+|-----------|---------|
+| `nginx/` | Reverse proxy — routes subdomains to tenant containers and platform services |
+| `dnsmasq/` | DNS — resolves `*.clarity.test` locally in dev |
+
+## How it fits in
+- OPC (ControlPlane) writes tenant-specific Nginx config files into `nginx/conf.d/` when provisioning a new tenant
+- Each file in `nginx/conf.d/` corresponds to one tenant or platform service
+- Dnsmasq makes `*.clarity.test` resolve to localhost in dev so the browser hits Nginx
+
+## Conventions
+- Commit format: `OPC # XXXX: Description`
+- Nginx tenant config files are named by tenant ID and generated by OPC — do not hand-edit them
+- Platform service configs (Keycloak, Gitea etc.) are static and live in `nginx/conf.d/`