diff --git a/.cursor/rules/dockprom-ai.mdc b/.cursor/rules/dockprom-ai.mdc
new file mode 100644
index 00000000..b9d3ba7b
--- /dev/null
+++ b/.cursor/rules/dockprom-ai.mdc
@@ -0,0 +1,22 @@
+# dockprom-ai (Cursor rules)
+
+## Context
+This repo is a Docker observability stack (Prometheus/Grafana/Loki/Tempo/OTel Collector) plus an Envoy `ollama-gateway` for request-level tracing/metrics.
+
+## Safety/quality guardrails
+- Never commit secrets (API keys, Slack webhook URLs, credentials). Use env vars or local `.env`.
+- Do not remove/weaken auth in `caddy/Caddyfile`.
+- Be mindful that Alloy ships Docker logs to Loki; avoid logging prompts/responses/secrets.
+- For `docker-compose.yml` changes: keep images pinned and avoid adding privileged access unless necessary.
+
+## Where to edit
+- Prometheus scrapes/alerts: `prometheus/prometheus.yml`, `prometheus/alert.rules`
+- OTel pipelines: `otel-collector/config.yml`
+- Logs shipping: `alloy/config.alloy`, `loki/loki.yml`
+- Traces backend: `tempo/tempo.yml`
+- Gateway: `envoy/envoy.yml`
+- Grafana: `grafana/provisioning/datasources/datasource.yml`, dashboards in `grafana/provisioning/dashboards/`
+
+## Definition of done (for infra changes)
+- Config files remain valid YAML/Alloy.
+- The existing endpoints still work and are not unintentionally exposed.
diff --git a/.cursorignore b/.cursorignore
new file mode 100644
index 00000000..3e2e4747
--- /dev/null
+++ b/.cursorignore
@@ -0,0 +1,9 @@
+.git/
+**/.env
+**/.env.*
+**/.opencode/
+# Local/IDE noise
+.vscode/
+.idea/
+.vs/
+.DS_Store
diff --git a/.geminiignore b/.geminiignore
new file mode 100644
index 00000000..e6b2af73
--- /dev/null
+++ b/.geminiignore
@@ -0,0 +1,8 @@
+.git/
+**/.env
+**/.env.*
+**/.opencode/
+.vscode/
+.idea/
+.vs/
+.DS_Store
diff --git a/.gitignore b/.gitignore
index 70c688df..c9358119 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,10 @@
 .vs/
 .vscode/
 .idea/
+
+# Local environment/secrets (do not commit)
+.env
+.env.*
+
+# Local agent state
+.opencode/
diff --git a/.opencode.json b/.opencode.json
new file mode 100644
index 00000000..0fee0690
--- /dev/null
+++ b/.opencode.json
@@ -0,0 +1,12 @@
+{
+  "data": {
+    "directory": ".opencode"
+  },
+  "shell": {
+    "path": "/bin/bash",
+    "args": ["-l"]
+  },
+  "debug": false,
+  "debugLSP": false,
+  "autoCompact": true
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..863e90bb
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,36 @@
+# dockprom-ai (project instructions)
+
+## What this repo is
+This repo is **Dockprom + AI observability**:
+- **Metrics**: Prometheus scrapes exporters, Envoy gateway, and the OTel collector Prometheus exporter.
+- **Logs**: Docker container logs → **Alloy** → **Loki**.
+- **Traces**: OTLP traces → **otel-collector** → **Tempo**.
+- **LLM gateway**: **Envoy** (`ollama-gateway`) proxies host Ollama and emits request metrics/traces.
+
+## How to run (dev)
+- Start stack: `docker compose up -d`
+- Core entrypoints:
+  - Grafana: `http://<host-ip>:3000`
+  - Prometheus: `http://<host-ip>:9090`
+  - OTel Collector (OTLP): `http://<host-ip>:4318` and `<host-ip>:4317`
+  - Ollama gateway: `http://<host-ip>:11435`
+
+## Guardrails (security + operability)
+- **No secrets in git**: never commit API keys, Slack webhooks, or credentials. Use environment variables or local `.env` (ignored).
+- **Do not remove auth**: do not weaken `caddy/Caddyfile` basic auth or expose new unauthenticated admin endpoints.
+- **Don’t widen ports casually**: be explicit if you bind services to `0.0.0.0` or add new published ports.
+- **Be careful with Docker logs**: Alloy ships Docker logs to Loki. Avoid logging prompts/responses or secrets from any agent tool.
+
+## Repo editing conventions
+- Prefer small, reviewable changes.
+- For config edits, keep existing formatting and comments.
+- If you change observability pipelines, keep the end-to-end flow working:
+  - OTLP → `otel-collector` → Tempo/Loki/Prometheus exporter.
+
+## Useful files
+- `docker-compose.yml`: service graph and ports
+- `otel-collector/config.yml`: OTLP ingest + export pipelines
+- `envoy/envoy.yml`: Ollama gateway proxy + tracing
+- `alloy/config.alloy`: Docker logs → Loki
+- `prometheus/prometheus.yml`: scrape targets
+- `grafana/provisioning/*`: dashboards and datasources
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..d231432c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,30 @@
+# dockprom-ai (Claude Code instructions)
+
+## Project summary
+This repo runs a Docker monitoring/observability stack:
+- Prometheus + Alertmanager
+- Grafana provisioning (datasources + dashboards)
+- Loki (logs) via Alloy (Docker log collection)
+- Tempo (traces)
+- OpenTelemetry Collector (OTLP ingest)
+- Envoy `ollama-gateway` (proxy to host Ollama + tracing/metrics)
+
+## Safety rules (must-follow)
+- Do **not** add or commit secrets (API keys, tokens, Slack webhook URLs). Use env vars or local `.env`.
+- Do **not** remove or weaken auth in `caddy/Caddyfile`.
+- Prefer least-privilege changes in `docker-compose.yml` (avoid privileged containers unless required).
+- Avoid printing sensitive data into logs; Alloy ships Docker logs to Loki.
+
+## How to verify changes
+- Config-only edits: ensure YAML/Alloy syntax remains valid.
+- When altering pipelines:
+  - OTel collector still exposes `:8889` for Prometheus scraping.
+  - Traces still reach Tempo; logs still reach Loki.
+
+## Key entrypoints
+- Grafana: `http://<host-ip>:3000`
+- Prometheus: `http://<host-ip>:9090`
+- OTLP HTTP: `http://<host-ip>:4318`
+- Ollama gateway: `http://<host-ip>:11435`
+
+(If you need broader repo guidance, also read `AGENTS.md`.)
diff --git a/GEMINI.md b/GEMINI.md
new file mode 100644
index 00000000..f1efc73d
--- /dev/null
+++ b/GEMINI.md
@@ -0,0 +1,19 @@
+# dockprom-ai (Gemini CLI context)
+
+## What this repo does
+Runs a Docker monitoring + AI/LLM observability stack (Prometheus/Grafana/Loki/Tempo/OTel Collector + Envoy Ollama gateway).
+
+## Non-negotiables
+- Never commit secrets (API keys, tokens, webhook URLs). Use env vars or local `.env`.
+- Don’t weaken or remove basic auth in `caddy/Caddyfile`.
+- Be careful with logs: Alloy ships Docker logs to Loki; avoid logging prompts/responses/secrets.
+
+## Common tasks
+- Update dashboards: edit JSON in `grafana/provisioning/dashboards/`.
+- Update scrape targets: edit `prometheus/prometheus.yml`.
+- Update OTLP routing: edit `otel-collector/config.yml`.
+- Update the Ollama gateway: edit `envoy/envoy.yml`.
+
+## Quick run
+- `docker compose up -d`
+- Grafana at `http://<host-ip>:3000`
diff --git a/OpenCode.md b/OpenCode.md
new file mode 100644
index 00000000..2c7a023d
--- /dev/null
+++ b/OpenCode.md
@@ -0,0 +1,19 @@
+# dockprom-ai (OpenCode / Crush memory)
+
+## Repo purpose
+Monitoring + observability stack for Docker, extended with AI/LLM observability:
+- OTLP ingest via `otel-collector` → Tempo/Loki/Prometheus
+- Docker logs via Alloy → Loki
+- Envoy `ollama-gateway` provides request traces + Prometheus metrics for Ollama traffic
+
+## Rules
+- Don’t add secrets to files or output. Keep API keys in environment variables.
+- Don’t weaken `caddy/Caddyfile` auth.
+- Treat `docker-compose.yml` as production-like infra: small diffs, explicit security tradeoffs.
+
+## Start/verify
+- Start: `docker compose up -d`
+- Grafana: `http://<host-ip>:3000`
+- Prometheus: `http://<host-ip>:9090`
+- OTLP HTTP: `http://<host-ip>:4318`
+- Gateway: `http://<host-ip>:11435`
diff --git a/README.md b/README.md
index 77368fd3..550645b7 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,20 @@ OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
 Notes:
 - The gateway gives you **transport-level observability** (latency/errors/throughput). Token/cost/quality metrics typically require **app-level instrumentation**.
 
+## AI coding tools (Claude Code, Codex CLI, Cursor, Gemini CLI, OpenCode)
+
+This repo includes minimal, repo-scoped instruction files so common coding agents behave consistently and safely:
+
+- **Claude Code**: `CLAUDE.md`
+- **OpenAI Codex CLI**: `AGENTS.md`
+- **Cursor**: `.cursor/rules/dockprom-ai.mdc` (also reads `AGENTS.md`)
+- **Gemini CLI**: `GEMINI.md` (respects `.geminiignore`)
+- **OpenCode / Crush**: `OpenCode.md` and `.opencode.json` (no API keys included)
+
+Security notes:
+- **Do not commit secrets** (API keys, tokens, Slack webhook URLs). Use environment variables or a local `.env` (ignored by git).
+- **Avoid logging sensitive data**: Docker logs are shipped to Loki via Alloy.
+
 ## Setup Grafana
 
 Navigate to `http://<host-ip>:3000` and login with user ***admin*** password ***admin***. You can change the credentials in the compose file or by supplying the `ADMIN_USER` and `ADMIN_PASSWORD` environment variables on compose up. The config file can be added directly in grafana part like this