diff --git a/src/content/docs/platform/secrets.mdx b/src/content/docs/platform/secrets.mdx
index 76bf48a5..115fc626 100644
--- a/src/content/docs/platform/secrets.mdx
+++ b/src/content/docs/platform/secrets.mdx
@@ -211,6 +211,14 @@ Today, secrets are provided as environment variables using the secret name as th
 METABASE_API_KEY=********
 ```
 
+#### Secret size limit
+
+Because secrets are injected as environment variables, each one has to fit inside the operating system's per-variable limit of 128 KiB (131,072 bytes). Warp counts the full `NAME=value` string against that limit, so the usable value length is 128 KiB minus the secret's name, the `=` sign, and the terminating null byte.
+
+Warp validates the size when you create or update a secret, so an oversized value is rejected up front rather than failing partway through a run. Secrets that expand into several environment variables, such as AWS credentials, are validated per variable.
+
+If you hit the limit, store the large payload somewhere the agent can fetch it at run time (an object store or a secrets manager the agent can call) and keep only the fetch credential in the Warp-managed secret.
+
 ---
 
 ### Secret availability by trigger type