diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index 832b1de..d8f4448 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -1,4 +1,9 @@
 services:
+  # ── Required environment variables (see .env.example) ───────────────────────
+  # APP_BOLT_URL, USER_NEO4J, PASSWORD_NEO4J — Neo4j connection
+  # SUPABASE_URL, SERVICE_ROLE_KEY — Supabase project
+  # REDIS_HOST, REDIS_PORT, REDIS_PASSWORD — Redis (optional auth)
+  # FASTAPI_SECRET_KEY, ADMIN_EMAIL — API config
   redis-dev:
     image: redis:7-alpine
     container_name: cc-redis-dev
@@ -15,12 +20,28 @@ services:
       timeout: 3s
       retries: 5
 
+  init:
+    image: cc-api-dev:latest
+    container_name: api-init-dev
+    env_file:
+      - .env.dev
+    environment:
+      - REDIS_HOST=redis-dev
+      - RUN_INIT=true
+      - INIT_MODE=${INIT_MODE:-infra}
+      - INIT_ONLY=true
+    command: ["./docker-entrypoint.sh", "init-only"]
+    depends_on:
+      redis-dev:
+        condition: service_healthy
+    networks:
+      - kevlarai-network
+    profiles:
+      - init
+
   backend-dev:
     container_name: cc-api-dev
     image: cc-api-dev:latest
-    build:
-      context: .
-      dockerfile: Dockerfile
     env_file:
       - .env.dev
     environment:
@@ -45,9 +66,6 @@ services:
 
   backend-test:
     image: cc-api-dev:latest
-    build:
-      context: .
-      dockerfile: Dockerfile
     env_file:
       - .env.dev
     environment:
diff --git a/docker-compose.yml b/docker-compose.yml
index e378a32..95fe058 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,4 +1,9 @@
 services:
+  # ── Required environment variables (see .env.example) ───────────────────────
+  # APP_BOLT_URL, USER_NEO4J, PASSWORD_NEO4J — Neo4j connection
+  # SUPABASE_URL, SERVICE_ROLE_KEY — Supabase project
+  # REDIS_HOST, REDIS_PORT, REDIS_PASSWORD — Redis (optional auth)
+  # FASTAPI_SECRET_KEY, ADMIN_EMAIL — API config
   redis:
     image: redis:7-alpine
     container_name: classroomcopilot-redis