diff --git a/README.md b/README.md
index bf61ee6..0106bfd 100644
--- a/README.md
+++ b/README.md
@@ -62,6 +62,11 @@ On subsequent restarts, the credentials already exist, so you can use `docker co
 docker compose up -d
 ```
 
+> **Skipped `./start.sh`?** On a fresh checkout, running `docker compose up`
+> directly fails with `env file .../neo4j-auth.env not found`. That file is
+> generated by `./start.sh` (first run) — run it once, then `docker compose up -d`
+> works directly on every subsequent start.
+
 ### Services
 
 The stack runs 2 services:
diff --git a/docker-compose.yml b/docker-compose.yml
index ea96ff8..c955e39 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,3 +1,20 @@
+# ---------------------------------------------------------------------------
+# FIRST RUN: run ./start.sh — do NOT run `docker compose up` directly yet.
+#
+# start.sh generates the credentials this stack needs
+# (credentials.yaml + neo4j-auth.env) under
+# $HOME/amplifier-context-intelligence-server-data-store/, then brings the
+# stack up. The neo4j service reads its password from that generated
+# neo4j-auth.env via `env_file:` below — on a fresh checkout it does not exist
+# yet, so a bare `docker compose up` fails with:
+#
+#     env file .../neo4j-auth.env not found
+#
+# That error means you skipped the first-run step. Run ./start.sh once;
+# afterwards the credentials persist and `docker compose up -d` works directly.
+#
+# See README.md → "Running with Docker Compose".
+# ---------------------------------------------------------------------------
 services:
   context-intelligence-server:
     build: .