diff --git a/docs/cli/activate.md b/docs/cli/activate.md
index 9cd2334772..866d35e282 100644
--- a/docs/cli/activate.md
+++ b/docs/cli/activate.md
@@ -51,6 +51,9 @@ Effectively the same as:
 PATH="$HOME/.local/share/mise/shims:$PATH"
 ```
 
+`mise activate --shims` does not support all the features of `mise activate`.
+See <https://mise.jdx.dev/dev-tools/shims.html#shims-vs-path> for more information
+
 ### `-q --quiet`
 
 Suppress non-error messages
diff --git a/docs/dev-tools/shims.md b/docs/dev-tools/shims.md
index ca5a3a24be..67c9f2e0fd 100644
--- a/docs/dev-tools/shims.md
+++ b/docs/dev-tools/shims.md
@@ -4,6 +4,11 @@
 The [beginner's guide](https://dev.to/jdxcode/beginners-guide-to-rtx-ac4), and my [blog post](https://jdx.dev/posts/2024-04-13-shims-how-they-work-in-mise-en-place/) are helpful resources to dive deeper into shims.
 :::
 
+::: warning
+`mise activate --shims` does not support all the features of `mise activate`.<br>
+See [shims vs path](/dev-tools/shims.html#shims-vs-path) for more info.
+:::
+
 ## Introduction
 
 There are two ways for dev tools to be loaded into your shell: `mise activate` and `shims`.
@@ -77,6 +82,12 @@ but since this is only run once per shell session it's not a big deal.
 
 ## Shims vs PATH
 
+The following features are affected when shims are used **instead** of PATH activation:
+
+- Env vars defined in mise are only available to mise tools
+- Most hooks won't trigger
+- The unix `which` command points to the shim, obscuring the real executable
+
 In general, I recommend using PATH (`mise activate`) instead of shims for _interactive_ situations. The
 way activate works is every time the prompt is displayed, mise-en-place will determine what PATH and other
 env vars should be and export them. This is why it doesn't work well for non-interactive situations like
@@ -103,18 +114,6 @@ This may be fixable at least for some shells if they support a hook for director
 some investigation will need to be done. See [#1294](https://github.com/jdx/mise/issues/1294) for details.
 :::
 
-### `which`
-
-`which` is a command that I personally find great value in. shims effectively "break" `which` and
-cause it to show the location of the shim. Of course `mise which` will show the location but I prefer
-the "cleanliness" of running `which node` and getting back a real path with a version number inside of it.
-e.g:
-
-```sh
-$ which node
-/Users/jdx/.mise/installs/node/20/bin/node
-```
-
 ### Env vars and shims
 
 A downside of shims is the "mise environment" is only loaded when a shim is called. This means if you
@@ -151,6 +150,22 @@ In general, [tasks](/tasks/) are a good way to ensure that the mise environment
 this isn't a problem.
 :::
 
+### Hooks and shims
+
+The [hooks](/hooks.html) `cd`, `enter`, `exit`, and `watch_files` only trigger with `mise activate`. However `preinstall` and `postinstall` still work with shims because they don't require shell integration.
+
+### `which`
+
+`which` is a command that I personally find great value in. shims effectively "break" `which` and
+cause it to show the location of the shim. Of course `mise which` will show the location but I prefer
+the "cleanliness" of running `which node` and getting back a real path with a version number inside of it.
+e.g:
+
+```sh
+$ which node
+/Users/jdx/.mise/installs/node/20/bin/node
+```
+
 ## Hook on `cd`
 
 Some version managers modify the behavior of `cd`. That might seem like the ideal method of making a version
diff --git a/docs/getting-started.md b/docs/getting-started.md
index c51d6da875..facc568038 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -79,6 +79,11 @@ Now that `mise` is installed, you can optionally activate it or add its [shims](
 - [`mise activate`](/cli/activate) method updates your environment variable and `PATH` every time your prompt is run to ensure you use the correct versions.
 - [Shims](dev-tools/shims.md) are symlinks to the `mise` binary that intercept commands and load the appropriate environment
 
+::: warning
+Shims do not support all the features of `mise activate`.<br>
+See [shims vs path](/dev-tools/shims.html#shims-vs-path) for more info.
+:::
+
 For interactive shells, `mise activate` is recommended. In non-interactive sessions, like CI/CD, IDEs, and scripts, using `shims` might work best. You can also not use any and call `mise exec/run` directly instead.
 See [this guide](dev-tools/shims.md) for more information.
 
diff --git a/docs/ide-integration.md b/docs/ide-integration.md
index bf916bdf43..9dcde7e9fc 100644
--- a/docs/ide-integration.md
+++ b/docs/ide-integration.md
@@ -60,7 +60,7 @@ end
 :::
 
 This assumes that `mise` is on `PATH`. If it is not, you'll need to use the absolute path (
-e.g.: `eval "$($HOME/.local/bin/mise activate zsh)"`).
+e.g.: `eval "$($HOME/.local/bin/mise activate zsh --shims)"`).
 
 Here is an example showing that VSCode will use `node` provided by `mise`:
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 0f1527104c..3588b46d2d 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -13,6 +13,11 @@ however that
 will only setup the global tools. It won't modify the environment variables when entering into a
 different project.
 
+::: warning
+`mise activate --shims` does not support all the features of `mise activate`.<br>
+See [shims vs path](/dev-tools/shims.html#shims-vs-path) for more info.
+:::
+
 Also see the [shebang](/tips-and-tricks#shebang) example for a way to make scripts call mise to get
 the runtime.
 That is another way to use mise without activation.
diff --git a/mise.usage.kdl b/mise.usage.kdl
index c0a1ae1ebd..86607b0b9e 100644
--- a/mise.usage.kdl
+++ b/mise.usage.kdl
@@ -94,7 +94,7 @@ Customize status output with `status` settings."#
     }
     flag "--status" help="Show \"mise: <PLUGIN>@<VERSION>\" message when changing directories" hide=true
     flag "--shims" help="Use shims instead of modifying PATH\nEffectively the same as:" {
-        long_help "Use shims instead of modifying PATH\nEffectively the same as:\n\n    PATH=\"$HOME/.local/share/mise/shims:$PATH\""
+        long_help "Use shims instead of modifying PATH\nEffectively the same as:\n\n    PATH=\"$HOME/.local/share/mise/shims:$PATH\"\n\n`mise activate --shims` does not support all the features of `mise activate`.\nSee https://mise.jdx.dev/dev-tools/shims.html#shims-vs-path for more information"
     }
     flag "-q --quiet" help="Suppress non-error messages"
     flag "--no-hook-env" help="Do not automatically call hook-env" {
diff --git a/src/cli/activate.rs b/src/cli/activate.rs
index a52bda345c..5ff7acd5ef 100644
--- a/src/cli/activate.rs
+++ b/src/cli/activate.rs
@@ -43,6 +43,9 @@ pub struct Activate {
     /// Effectively the same as:
     ///
     ///     PATH="$HOME/.local/share/mise/shims:$PATH"
+    ///
+    /// `mise activate --shims` does not support all the features of `mise activate`.
+    /// See https://mise.jdx.dev/dev-tools/shims.html#shims-vs-path for more information
     #[clap(long, verbatim_doc_comment)]
     shims: bool,