diff --git a/ai/ai.yaml b/ai/ai.yaml
index ed9fa52..416b49c 100644
--- a/ai/ai.yaml
+++ b/ai/ai.yaml
@@ -1,3 +1,8 @@
+# NOTE: litellm's AWS/DB/master-key secrets, open-webui's secret key/DB URL,
+# and the OAuth client secret are provisioned into ai/ai.env at deploy time
+# from Woodpecker secrets (see PRs #4, #6, #7) -- not committed here.
+# MCPO_API_KEY (used by mcpo and mcpo-critical) is NOT yet migrated; it
+# remains manually managed in ai/ai.env by design (see PR #4 discussion).
 services:
   open-webui:
     image: ghcr.io/open-webui/open-webui:0.11.1