diff --git a/docs/deploy.md b/docs/deploy.md
index 8e34e9e..d924762 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -7,6 +7,18 @@
 !!! tip "What can run here"
     APIs, websites, applets, bots, monitors.
 
+!!! danger "One name everywhere — repo = container = volumes"
+    The **repo name is the name.** Your service (the compose service key), the
+    container, and every named volume **must all use that same name**. If your repo
+    is `myrepo`:
+
+    - service → `myrepo`
+    - container → `myrepo`
+    - volumes → `myrepo-data`, `myrepo-cache`, … (the repo name, then a suffix)
+
+    Mismatched names break our deploy, monitoring, and log scraping — they key off
+    the repo name. **Do not** name the service one thing and the repo another.
+
 ## Docker — the services account
 
 Every service runs containerized as the shared **`services`** account:
@@ -66,28 +78,35 @@ CMD ["python", "-m", "yourapp"]
     3.  `--system` installs into the image's Python (no venv needed — the container
         *is* the isolation); reads `pyproject.toml`, no `uv.lock` required.
 
+The service key, `container_name`, and volume names below are all **`myrepo`** —
+the repo name. Match yours to your repo.
+
 ```yaml
 services:
-  yourapp:
+  myrepo:                                      # (1)!
     build: .
-    user: "1337:1337"                          # (1)!
+    container_name: myrepo                     # (2)!
+    user: "1337:1337"                          # (3)!
     environment:
       HOME: /tmp
     volumes:
-      - /srv/config/<workspace>/<project>:/app/config:ro  # (2)!
-      - /srv/logs/<workspace>/<project>:/app/logs          # (3)!
-      - yourapp-data:/app/data                             # (4)!
+      - /srv/config/<workspace>/<project>:/app/config:ro  # (4)!
+      - /srv/logs/<workspace>/<project>:/app/logs          # (5)!
+      - myrepo-data:/app/data                              # (6)!
 
 volumes:
-  yourapp-data:
+  myrepo-data:                                 # (7)!
 ```
 
-1.  Run as the shared account. **No** in-container `user`/`useradd` — don't bake a
+1.  Service key = **the repo name**.
+2.  Container name = **the repo name** — same as the service.
+3.  Run as the shared account. **No** in-container `user`/`useradd` — don't bake a
     user into the image; set it here.
-2.  Configs: host-managed bind mount, mounted **read-only**.
-3.  Logs: bind mount — live and rolled, scraped for monitoring.
-4.  Everything else: a **named volume**. Docker owns it, so there are no host
-    permissions to fiddle with.
+4.  Config: host-managed bind mount, mounted **read-only**.
+5.  Logs: bind mount — live and rolled, scraped for monitoring.
+6.  Named volume = **repo name + suffix** (`myrepo-data`). Docker owns it, so there
+    are no host permissions to fiddle with.
+7.  Declare the volume under the same **repo-name-prefixed** key.
 
 ## Paths and mounts