diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..120e32d
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,71 @@
+# GitHub Copilot Instructions
+
+This repository contains a small Go-based Traefik ForwardAuth service for `gitea-mcp` access control. Keep changes minimal, infrastructure-aware, and aligned with the deployment and CI conventions below.
+
+## Project Purpose
+
+- This service validates `Authorization: Bearer <token>` for Traefik ForwardAuth.
+- The service is intentionally small and should prefer the Go standard library over additional frameworks.
+- Authentication is hash-only: the service stores and loads only SHA-256 token hashes, never plaintext tokens.
+
+## Go and Build Conventions
+
+- Use Go `1.26` unless the repository is explicitly updated to a newer version.
+- Keep the module path aligned with the self-hosted Gitea instance: `gitea.nehmer.net/torben/gitea-mcp-forward-auth`.
+- Prefer standard library packages such as `net/http`, `log/slog`, and `crypto/subtle`.
+- Keep code testable: separate token validation logic from HTTP handler behavior.
+
+## Security Requirements
+
+- Never log plaintext bearer tokens.
+- Only log a short token fingerprint or derived identifier that does not reveal the original token.
+- Token comparisons must remain constant-time.
+- Token configuration must stay hash-based:
+  - `AUTH_PROXY_TOKEN_HASHES_DIR`
+  - `AUTH_PROXY_TOKEN_HASHES`
+- Do not reintroduce plaintext token configuration or examples.
+- `/healthz` does not need to be world-readable. Prefer internal-only exposure for k3s probes and Prometheus.
+
+## Kubernetes and Deployment Assumptions
+
+- Kubernetes manifests under `deploy/k3s/` are reference examples only.
+- Actual cluster deployment and rollout automation happen in a separate FluxCD repository.
+- Do not add FluxCD deployment logic to this repository unless explicitly requested.
+- Keep the Service internal (`ClusterIP`) unless the user explicitly asks otherwise.
+- NetworkPolicy changes must preserve the assumption that only trusted in-cluster components should reach this service.
+- If labels or namespaces for Traefik or Prometheus are assumed, mark them explicitly as assumptions in comments or docs.
+
+## CI/CD Conventions
+
+- Gitea Actions are the target, not GitHub Actions cloud defaults.
+- Container build jobs must use:
+  - `runs-on: container-builder`
+  - `container.image: debian:trixie-slim`
+- If a workflow uses Node-based actions such as `actions/checkout` or `actions/setup-go`, install required tools first inside the runner container.
+- Prefer Debian Trixie package names and behavior when editing workflows.
+- The Go package registry is the self-hosted Gitea registry:
+  - `https://gitea.nehmer.net/api/packages/torben/go`
+- Preserve `GOPROXY` usage with the Gitea registry first, then public fallback if already used by the repo.
+
+## Container Release Conventions
+
+- Release images are published to `gitea.nehmer.net/torben`.
+- The image name is `gitea-mcp-auth-proxy` unless the user changes it explicitly.
+- Release builds use a remote BuildKit daemon, not a local Docker daemon.
+- Preserve the remote builder pattern:
+  - determine host IP from the default route
+  - connect to `tcp://$HOST_IP:1234`
+- Keep the 1Password secret-loading pattern for registry credentials.
+- Stable tags (`vX.Y.Z`) may publish `latest`; prerelease tags must not publish `latest`.
+
+## Repo Hygiene
+
+- Ignore only the root build artifact `/authproxy`; do not ignore `cmd/authproxy`.
+- When changing workflows, prefer explicit artifact paths like `dist/...` over implicit binary output in the repo root.
+- Check `README.md` on updates and expand usage instructions where necessary. The file should be targeted for using the proxy, not for developing it.
+
+## Documentation Style
+
+- Call out infrastructure-specific behavior as `Assumption:` when it depends on the user's environment.
+- Keep examples consistent with the current security model, especially hash-only token configuration.
+- Do not describe this repository as the deployment source of truth; it only builds the service and related reference manifests.