diff --git a/docs/configuration.md b/docs/configuration.md
index eb0a21be03..523392a77b 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -321,8 +321,8 @@ python = ['3.10', '3.11']
 # for example, .nvmrc in the case of node's nvm
 idiomatic_version_file_enable_tools = ['node']
 
-# configure `mise install` to always keep the downloaded archive
-always_keep_download = false        # deleted after install by default
+# keep downloaded archive/source files for debugging
+always_keep_download = false        # deleted after install; not a cache
 always_keep_install = false         # deleted on failure by default
 
 # configure how frequently (in minutes) to fetch updated plugin repository changes
diff --git a/docs/directories.md b/docs/directories.md
index 5092afc473..3eedfb01d8 100644
--- a/docs/directories.md
+++ b/docs/directories.md
@@ -47,8 +47,11 @@ doing so.
 
 ### `~/.local/share/mise/downloads`
 
-This is where plugins may optionally cache downloaded assets such as tarballs. Use the
-`always_keep_downloads` setting to prevent mise from removing files from here.
+This is where plugins may write downloaded assets such as tarballs during installation. mise removes these files by
+default after install/uninstall; set `always_keep_download` to keep them for debugging backend/plugin install behavior.
+This directory is not a supported download cache. Some backends may skip a download when the expected file already exists,
+but that behavior is backend-specific and not guaranteed. Cache `~/.local/share/mise/installs` instead if you want to
+avoid reinstalling tools in CI or offline workflows.
 
 ### `~/.local/share/mise/plugins`
 
diff --git a/schema/mise.json b/schema/mise.json
index 4ebd640d37..8dfab10db1 100644
--- a/schema/mise.json
+++ b/schema/mise.json
@@ -515,7 +515,7 @@
           "type": "boolean"
         },
         "always_keep_download": {
-          "description": "should mise keep downloaded files after installation",
+          "description": "keep downloaded files after installation for debugging",
           "type": "boolean"
         },
         "always_keep_install": {
diff --git a/settings.toml b/settings.toml
index 753a934000..03ed49a51b 100644
--- a/settings.toml
+++ b/settings.toml
@@ -72,7 +72,15 @@ env = "MISE_ALL_COMPILE"
 type = "Bool"
 
 [always_keep_download]
-description = "should mise keep downloaded files after installation"
+description = "keep downloaded files after installation for debugging"
+docs = """
+Keeps downloaded archive/source files under `~/.local/share/mise/downloads` after install/uninstall so you can inspect them
+while debugging backend/plugin install behavior.
+
+This is not a supported download cache. Some backends may skip a download when the expected file already exists, but that
+behavior is backend-specific and not guaranteed. Cache `~/.local/share/mise/installs` instead if you want to avoid
+reinstalling tools in CI or offline workflows.
+"""
 env = "MISE_ALWAYS_KEEP_DOWNLOAD"
 type = "Bool"