diff --git a/docs/maintainers/handbook.md b/docs/maintainers/handbook.md
index 07e15a07..979f1356 100644
--- a/docs/maintainers/handbook.md
+++ b/docs/maintainers/handbook.md
@@ -323,6 +323,21 @@ Sometimes the containers don't even have Bash installed on them. You had better
 
 When referencing an `app` service in a config file, you should prefix with the `STACK_NAME` to avoid namespace conflicts (because all these containers sit on the traefik overlay network). You might want to do something like this `{{ env "STACK_NAME" }}_app` (using  the often obscure dark magic of the Golang templating language). You can find examples of this approach used in the [Peertube recipe](https://git.coopcloud.tech/coop-cloud/peertube/src/commit/d1b297c5a6a23a06bf97bb954104ddfd7f736568/nginx.conf.tmpl#L9).
 
+!!! warning "Here be timing dragons 🐉"
+
+    Due to how `STACK_NAME` as an environment variable is initialized within `abra`, it won't be available *early enough* for use within config templates (`*.tmpl`) unless you **use it as an environment variable for one of your compose services**.
+    Ideally this is addressed in a newer version of `abra`, but for now, this workaround suffices ✅
+
+    E.g.
+    ```
+      services:
+        web:
+          image: nginx:1.29.3
+          environment:
+            - ...
+            - STACK_NAME
+    ```
+
 ## How are recipes versioned?
 
 We'll use an example to work through this. Let's use [Gitea](https://hub.docker.com/r/gitea/gitea).