diff --git a/umbraco-cloud/begin-your-cloud-journey/project-features/secrets-management.md b/umbraco-cloud/begin-your-cloud-journey/project-features/secrets-management.md
index 1d1fed02fd1..82ada5efd1b 100644
--- a/umbraco-cloud/begin-your-cloud-journey/project-features/secrets-management.md
+++ b/umbraco-cloud/begin-your-cloud-journey/project-features/secrets-management.md
@@ -34,10 +34,23 @@ Starter Plans have a limit of 5 secrets per environment, whereas higher-tiered p
 ## How to add secrets
 
 {% hint style="warning" %}
-When adding a secret to your environment it will restart.
+
+## Important
+
+When adding a secret to your environment, it will restart.
+
+Secrets are stored as environment variables.
+The underlying platform has a maximum size limit for all environment variables combined.
+If too many secrets are added, or if secret values are too large, your environment may fail to start.
+
+It is recommended to:
+
+- Keep secrets small and concise.
+- Store only sensitive values as secrets (for example: API keys, connection strings).
+- Use `appsettings.json` for general configuration values.
 {% endhint %}
 
-To add a secret to your environment follow these steps:
+To add a secret to your environment, follow these steps:
 
 1. Go to your Umbraco Cloud project
 2. Go to the Settings section and go to Secret Management