diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6af1cd7
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,30 @@
+# AGENTS.md
+
+## 1. Overview
+
+Lightweight PHP micro-service that returns the client's public IP address as JSON. Containerized with Docker and deployed on Kubernetes.
+
+## 2. Folder Structure
+
+- `root/`: Application source code served by Apache.
+    - `index.php`: Single endpoint returning `REMOTE_ADDR` as JSON.
+- `.gitea/workflows/`: Gitea Actions CI pipelines.
+    - `docker-build.yaml`: Build and push Docker image to Docker Hub on push/PR to master + daily cron.
+- `Dockerfile`: Multi-stage build extending `jcabillot/phpapache` base image, copies `root/` into `/var/www/html`.
+- `.gitlab-ci.yml`: Legacy GitLab CI config (deprecated, replaced by Gitea Actions).
+- `Jenkinsfile`: Legacy Jenkins pipeline (deprecated, replaced by Gitea Actions).
+
+## 3. Core Behaviors & Patterns
+
+- **Request/Response Flow**: Single PHP endpoint sets `Content-Type: application/json` header and returns `$_SERVER['REMOTE_ADDR']` encoded as JSON string. No routing, no framework, no state.
+- **Container Base Image Pattern**: `Dockerfile` uses `ARG VERSION="latest"` to allow version pinning at build time, extends `jcabillot/phpapache` which provides PHP + Apache pre-configured. Application code is layered on top via `COPY root /var/www/html`.
+- **Traefik IngressRoute with HTTPS Redirect**: Two IngressRoute resources handle traffic — `ip-websecure` serves HTTPS on the `websecure` entrypoint, `ip-web` catches HTTP on `web` entrypoint and applies a `redirectScheme` middleware for permanent HTTPS redirect. The Service reference in the HTTP IngressRoute is required by Traefik even though the middleware intercepts before reaching it.
+- **Health Probes**: Deployment defines both `livenessProbe` and `readinessProbe` using `httpGet` on `/` at the named `http` port (8080). Kubernetes uses these to restart unhealthy pods and exclude unready pods from the Service endpoints.
+- **Security Hardening**: Pod spec sets `automountServiceAccountToken: false` to prevent unnecessary Kubernetes API access from the container.
+
+## 4. Conventions
+
+- **Kubernetes Labels**: Pods use `app: "front"` for Service selector matching and `owner: "jcabillot"` for resource attribution. Deployment-level labels use `app: "front"`.
+- **Named Ports**: Container port is named `http` (8080) and referenced by name in probes and Service targetPort, avoiding hardcoded port numbers.
+- **Docker Image Tagging**: CI uses `docker/metadata-action` to generate tags — `latest` for master branch pushes, branch/PR/SHA tags for other events. Push is skipped on pull requests.
+- **CI Secrets**: Docker Hub credentials are stored as Gitea Actions secrets (`DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`), never hardcoded.