From 0deae9a47e48a3a4f9f9b742fbfafa0b5302f3ff Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Tue, 27 Jan 2026 06:08:02 -0600
Subject: [PATCH 1/2] docs: update cache-behavior with env_cache information

Updates the cache-behavior docs to document the env_cache setting which
provides advanced caching for dynamic environment providers like secret
managers.

Removes outdated advice to "submit a ticket" for dynamic exec-env scripts
since mise now has proper solutions for this use case.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/cache-behavior.md | 40 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 5 deletions(-)

diff --git a/docs/cache-behavior.md b/docs/cache-behavior.md
index bab5cebe74..9743bdd78d 100644
--- a/docs/cache-behavior.md
+++ b/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
 

From a80d1e96c180d4f389f7956266abcd3003e1ccf9 Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Tue, 27 Jan 2026 06:09:35 -0600
Subject: [PATCH 2/2] docs: clarify env_cache setting requirement for plugin
 caching

Adds notes to env-plugin-development.md explaining that users must
enable `env_cache = true` in their settings for plugin caching to work.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/env-plugin-development.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/env-plugin-development.md b/docs/env-plugin-development.md
index 436ffa6b06..c26b678349 100644
--- a/docs/env-plugin-development.md
+++ b/docs/env-plugin-development.md
@@ -126,6 +126,17 @@ When `cacheable = true`, mise will cache the environment variables and only re-e
 - The mise configuration changes
 - The cache TTL expires (configured via `env_cache_ttl` setting)
 
+::: tip
+For caching to work, users must enable the `env_cache` setting:
+
+```toml
+# ~/.config/mise/config.toml
+[settings]
+env_cache = true
+```
+
+:::
+
 ### hooks/mise_path.lua
 
 The `MisePath` hook returns directories to add to PATH (optional):
@@ -314,6 +325,8 @@ This is preferred over manual caching because:
 - Integrates with `mise cache clear` and `mise cache prune`
 - Respects the `env_cache_ttl` setting
 
+Note: Users must enable `env_cache = true` in their settings for caching to work.
+
 ### 5. Support Multiple Environments
 
 ```lua