diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..4efdb52
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,37 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+A Docker image: Apache HTTPD acting as a **reverse proxy with OpenID Connect authentication**, built on Ubuntu 20.04 using `mod_auth_openidc`. There is no application code, build system, or test suite — the repository is the Dockerfile plus the Apache configuration files baked into the image. Work here means editing config and the Dockerfile, then rebuilding the image.
+
+## Build & run
+
+```bash
+# Build locally
+docker build -t apacheoidc .
+
+# Run (override env vars to point at your OIDC provider / backend)
+docker run -p 80:80 -p 443:443 \
+  -e SERVER_NAME=localhost \
+  -e OIDC_PROVIDER_URL=http://id.example.ch \
+  apacheoidc
+```
+
+Multi-platform CI builds (`linux/arm64,linux/amd64`) run via `docker buildx` and push to a Gitea registry. The pipeline is defined in [.gitea/workflows/docker.yml](.gitea/workflows/docker.yml) (active, triggers on push to `main`). [.space.kts](.space.kts) is a legacy JetBrains Space pipeline kept for reference.
+
+## Architecture & configuration
+
+- **[Dockerfile](Dockerfile)** — Installs Apache + `libapache2-mod-auth-openidc`, enables modules (`auth_openidc`, `proxy`, `proxy_http`, `proxy_http2`, `proxy_wstunnel`, `ssl`, `rewrite`, `headers`, …), and defines all runtime configuration as `ENV` variables. The `OIDC_*` / `KC_*` env vars and `SERVER_NAME` are the primary knobs for a deployment; they are meant to be overridden at `docker run` time, not edited in the image.
+- **[apache2.conf](apache2.conf)** — Main server config: security headers (HttpOnly/Secure cookies, X-Frame-Options, HSTS-style settings), `OIDCCacheType file` cache setup, logging to stdout/stderr, and `IncludeOptional sites-enabled/*` for vhosts.
+- **[ssl.conf](ssl.conf)** — Copied over `mods-enabled/ssl.conf`; defines TLS protocols/ciphers (TLS, SSLv3 disabled) and session cache.
+- **[httpd-foreground](httpd-foreground)** — Container entrypoint; runs `apache2 -DFOREGROUND`.
+- **`/config/{global.d,vhost-80.d,vhost-443.d}`** and `sites-enabled` — Directories created in the image for the actual reverse-proxy vhost definitions. These are **not committed**; the concrete proxy/OIDC vhost config is expected to be mounted in at runtime. The default `000-default.conf` is removed during build.
+- **[index.html](index.html)** — Placeholder landing page served at `/var/www/html/app` after login.
+
+## Important notes
+
+- The `OIDC_CLIENT_SECRET`, `OIDC_CRYPTO_PASSPHRASE`, and similar values in the Dockerfile are **development defaults only** — always override them in real deployments.
+- `LogLevel debug` (in apache2.conf) and `APACHE_DEBUG_LEVEL` log OIDC tokens. As the Dockerfile comment warns, **debug logging must never be used in production**.
+- `STOPSIGNAL WINCH` is used for Apache graceful stop.