diff --git a/docs/ENV_EXAMPLE_NOTES.md b/docs/ENV_EXAMPLE_NOTES.md
new file mode 100644
index 000000000000..d8be5fb478bf
--- /dev/null
+++ b/docs/ENV_EXAMPLE_NOTES.md
@@ -0,0 +1,13 @@
+# Environment example notes
+
+When updating `.env.example` (or similar templates):
+
+- Keep placeholders obvious (e.g., `YOUR_API_KEY_HERE`)
+- Never include real keys, tokens, or private endpoints
+- Group variables by feature area
+- Add brief inline comments for non-obvious fields
+
+If you introduce a new required variable, document:
+- where it is used
+- acceptable values
+- safe default (if any)