diff --git a/README.md b/README.md
index a23a025c..f745aa0d 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,8 @@ or install with mise:
 mise use -g herdr
 ```
 
+if mise reports `herdr not found in mise tool registry`, update mise and retry. older mise versions predate the herdr registry entry; `mise use -g github:ogulcancelik/herdr` works as a temporary fallback.
+
 or download the binary from [releases](https://github.com/ogulcancelik/herdr/releases). requires linux or macos.
 
 ## quick start
diff --git a/docs/next/README.md b/docs/next/README.md
index db3b43fb..af910ba3 100644
--- a/docs/next/README.md
+++ b/docs/next/README.md
@@ -43,6 +43,8 @@ or install with mise:
 mise use -g herdr
 ```
 
+if mise reports `herdr not found in mise tool registry`, update mise and retry. older mise versions predate the herdr registry entry; `mise use -g github:ogulcancelik/herdr` works as a temporary fallback.
+
 or download the stable Linux/macOS binary from [releases](https://github.com/ogulcancelik/herdr/releases). Native Windows binaries are preview-only beta builds.
 
 ## quick start
diff --git a/docs/next/website/src/content/docs/install.mdx b/docs/next/website/src/content/docs/install.mdx
index fd9b87c9..e64e9c7d 100644
--- a/docs/next/website/src/content/docs/install.mdx
+++ b/docs/next/website/src/content/docs/install.mdx
@@ -37,6 +37,8 @@ If you already use mise:
 mise use -g herdr
 ```
 
+If mise reports `herdr not found in mise tool registry`, update mise and retry. Older mise versions predate the Herdr registry entry; `mise use -g github:ogulcancelik/herdr` works as a temporary fallback.
+
 ## Verify
 
 Start Herdr:
diff --git a/website/src/content/docs/install.mdx b/website/src/content/docs/install.mdx
index 66203310..c23ffee8 100644
--- a/website/src/content/docs/install.mdx
+++ b/website/src/content/docs/install.mdx
@@ -31,6 +31,8 @@ If you already use mise:
 mise use -g herdr
 ```
 
+If mise reports `herdr not found in mise tool registry`, update mise and retry. Older mise versions predate the Herdr registry entry; `mise use -g github:ogulcancelik/herdr` works as a temporary fallback.
+
 ## Verify
 
 Start Herdr: