docs: add a warning about caching and updates

Updates tailscale/corp#22445

docs/README.md

@@ -485,6 +485,21 @@ the program's secret values to local storage, which means they can be read by
 program can start up immediately using cached data, even if the secrets server
 is not reachable when it launches.
 
+> [!WARNING]
+> When you enable a cache for a program, new secret values may not immediately
+> become available even if the program is restarted. By design, if a cached
+> value is available at startup, the store does not wait for the secrets
+> service to respond before delivering the initial (cached) value.
+>
+> The store will see the new value (and update the cache) the next time it
+> successfully polls.  If the program only looks at the initial value of the
+> secret, however, it will not see the new value until it is restarted _after_
+> the next update.
+>
+> As a general rule, we recommend you not a cache unless the program cannot
+> tolerate any delay at startup.  Otherwise, if you must use a cache, we advise
+> you structure your program to automatically handle new secret values, and not
+> to "lock in" the initial value of a secret when the program starts up.
 
 ## Self-Contained Operation