diff --git a/CLAUDE.md b/CLAUDE.md
index 58295cac..e6a2c805 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -40,3 +40,15 @@ java -jar cameleer3-server-app/target/cameleer3-server-app-1.0-SNAPSHOT.jar
 - Maintains agent instance registry with states: LIVE → STALE → DEAD
 - Storage: ClickHouse for structured data, text index for full-text search
 - Security: JWT auth, Ed25519 config signing, bootstrap token for registration
+
+## CI/CD & Deployment
+
+- CI workflow: `.gitea/workflows/ci.yml` — build → docker → deploy on push to main
+- Build step skips integration tests (`-DskipITs`) — Testcontainers needs Docker daemon
+- Docker: multi-stage build (`Dockerfile`), `$BUILDPLATFORM` for native Maven on ARM64 runner, amd64 runtime
+- `REGISTRY_TOKEN` build arg required for `cameleer3-common` dependency resolution
+- Registry: `gitea.siegeln.net/cameleer/cameleer3-server` (container images)
+- K8s manifests in `deploy/` — ClickHouse StatefulSet + server Deployment + NodePort Service (30081)
+- Deployment target: k3s at 192.168.50.86, namespace `cameleer`
+- Secrets managed in CI deploy step (idempotent `--dry-run=client | kubectl apply`)
+- Docker build uses buildx registry cache + `--provenance=false` for Gitea compatibility
diff --git a/HOWTO.md b/HOWTO.md
index 2a5f6b2f..29d22be0 100644
--- a/HOWTO.md
+++ b/HOWTO.md
@@ -253,3 +253,46 @@ docker exec -it cameleer3-server-clickhouse-1 clickhouse-client \
   --user cameleer --password cameleer_dev -d cameleer3 \
   -q "SELECT count() FROM route_executions"
 ```
+
+## Kubernetes Deployment
+
+The full stack is deployed to k3s via CI/CD on push to `main`. K8s manifests are in `deploy/`.
+
+### Architecture
+
+```
+cameleer namespace:
+  ClickHouse (StatefulSet, 2Gi PVC) ← clickhouse:8123 (ClusterIP)
+  cameleer3-server (Deployment)     ← NodePort 30081
+  cameleer3-sample (Deployment)     ← NodePort 30080  (from cameleer3 repo)
+```
+
+### Access (from your network)
+
+| Service | URL |
+|---------|-----|
+| Server API | `http://192.168.50.86:30081/api/v1/health` |
+| Swagger UI | `http://192.168.50.86:30081/api/v1/swagger-ui.html` |
+| Sample App | `http://192.168.50.86:30080/api/orders` |
+
+### CI/CD Pipeline
+
+Push to `main` triggers: **build** (Maven, unit tests) → **docker** (buildx cross-compile amd64, push to Gitea registry) → **deploy** (kubectl apply + rolling update).
+
+Required Gitea org secrets: `REGISTRY_TOKEN`, `KUBECONFIG_BASE64`, `CAMELEER_AUTH_TOKEN`.
+
+### Manual K8s Commands
+
+```bash
+# Check pod status
+kubectl -n cameleer get pods
+
+# View server logs
+kubectl -n cameleer logs -f deploy/cameleer3-server
+
+# View ClickHouse logs
+kubectl -n cameleer logs -f statefulset/clickhouse
+
+# Restart server
+kubectl -n cameleer rollout restart deployment/cameleer3-server
+```