docs: update cache-behavior with env_cache information

docs/cache-behavior.md

@@ -22,13 +22,43 @@ cat ~/$MISE_CACHE_DIR/node/remote_versions.msgpack.z | perl -e 'use Compress::Ra
 ```
 
 Note that the caching of `exec-env` may be problematic if the script isn't simply exporting
-static values. The vast majority of `exec-env` scripts only export static values, but if you're
-working with a plugin that has a dynamic `exec-env` submit
-a ticket and we can try to figure out what to do.
+static values. The vast majority of `exec-env` scripts only export static values.
 
 Caching `exec-env` massively improved the performance of mise since it requires calling bash
-every time mise is initialized. Ideally, we can keep this
-behavior.
+every time mise is initialized.
+
+## Environment Caching
+
+For more advanced caching needs (including dynamic environment providers like secret managers),
+mise provides the [`env_cache`](/configuration/settings.html#env_cache) setting. When enabled,
+mise caches the computed environment to disk with encryption.
+
+```toml
+# ~/.config/mise/config.toml
+[settings]
+env_cache = true
+env_cache_ttl = "1h"  # optional, default is 1h
+```
+
+Cache invalidation happens automatically when:
+
+- Any config file changes (mise.toml, .tool-versions, etc.)
+- Tool versions change
+- Settings change
+- mise version changes
+- TTL expires (configurable via `env_cache_ttl`)
+- Any watched files change (from modules or `_.source` directives)
+
+Env plugins (vfox modules) can declare themselves cacheable by returning `{cacheable = true, watch_files = [...]}`
+from their `MiseEnv` hook. See [Env Plugin Development](/env-plugin-development.html) for details.
+
+Directives can opt out of caching by setting `cacheable = false`:
+
+```toml
+[env]
+TIMESTAMP = { value = "{{ now() }}", cacheable = false }
+_.source = { file = "dynamic.sh", cacheable = false }
+```
 
 ## Cache auto-pruning