diff --git a/README.md b/README.md
index f4d9d63..764c5d9 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,11 @@ brew install quicknode/tap/qn
 ```
 
 Homebrew installs shell completions automatically — open a new shell after
-install (zsh users may need one `compinit` refresh) and `qn <TAB>` works.
+install and `qn <TAB>` works. zsh users may have one extra requirement: zsh only
+autoloads a completion when its directory is on `$fpath` before `compinit` runs
+at shell startup. If `qn <TAB>` lists files instead of subcommands, the Homebrew
+completions directory is missing from `$fpath` — see the
+[zsh completion-system manual](https://zsh.sourceforge.io/Doc/Release/Completion-System.html).
 
 ### Scoop (Windows)
 
@@ -245,14 +249,57 @@ qn team list
 
 ## Shell completions
 
-Homebrew installs completions automatically (see above). For other install
-methods, generate them yourself:
+When installing qn through a package manager, it's possible that no additional
+shell configuration is necessary — Homebrew (see above) and distro packages
+place the script for you. To set up completions manually, follow the
+instructions below (`qn completions --help` prints the same). Exact config file
+locations may vary by system; restart your shell before testing.
+
+### bash
+
+Install `bash-completion` with your package manager, then add to `~/.bashrc`:
+
+```sh
+eval "$(qn completions bash)"
+```
+
+### zsh
+
+Homebrew already creates this `_qn` file for you on `brew install`. To set it up
+manually, generate the script into a directory on your `$fpath` (Apple Silicon
+shown; Intel brew uses `/usr/local/share/zsh/site-functions`):
+
+```sh
+qn completions zsh > /opt/homebrew/share/zsh/site-functions/_qn
+```
+
+Ensure that the following is present in your `~/.zshrc`:
+
+```sh
+autoload -U compinit
+compinit
+```
+
+See the [zsh completion-system manual](https://zsh.sourceforge.io/Doc/Release/Completion-System.html) for details.
+
+### fish
 
 ```sh
-qn completions zsh  > ~/.zfunc/_qn        # zsh
-qn completions bash > /etc/bash_completion.d/qn  # bash
 qn completions fish > ~/.config/fish/completions/qn.fish
-qn completions powershell > qn.ps1
+```
+
+### PowerShell
+
+Add this line to your profile script (`$PROFILE`):
+
+```powershell
+qn completions powershell | Out-String | Invoke-Expression
+```
+
+Or append the generated script so it loads each session:
+
+```powershell
+qn completions powershell >> $PROFILE
 ```
 
 ## Configuration via environment
diff --git a/src/cli.rs b/src/cli.rs
index daf6411..89fac6a 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -145,7 +145,39 @@ pub enum Command {
     /// Manage the Quicknode KV store (sets and lists).
     Kv(commands::kv::Args),
 
-    /// Generate shell completions.
+    /// Generate shell completion scripts.
+    ///
+    /// When installing qn through a package manager, it's possible that no
+    /// additional shell configuration is necessary to gain completion support.
+    /// Homebrew and distro packages place the script for you.
+    ///
+    /// If you need to set up completions manually, follow the instructions
+    /// below. The exact config file locations might vary based on your system.
+    /// Make sure to restart your shell before testing whether completions are
+    /// working.
+    #[command(after_long_help = "### bash\n\n  \
+        First, ensure that you install `bash-completion` using your package manager.\n\n  \
+        After, add this to your `~/.bashrc`:\n\n      \
+        eval \"$(qn completions bash)\"\n\n\
+        ### zsh\n\n  \
+        Homebrew already creates this `_qn` file for you on `brew install`. To\n  \
+        set it up manually, generate the script into a directory on your\n  \
+        `$fpath` (Apple Silicon shown; Intel brew uses\n  \
+        `/usr/local/share/zsh/site-functions`):\n\n      \
+        qn completions zsh > /opt/homebrew/share/zsh/site-functions/_qn\n\n  \
+        Ensure that the following is present in your `~/.zshrc`:\n\n      \
+        autoload -U compinit\n      \
+        compinit\n\n  \
+        See the zsh manual for details:\n  \
+        https://zsh.sourceforge.io/Doc/Release/Completion-System.html\n\n\
+        ### fish\n\n  \
+        Generate a `qn.fish` completion script:\n\n      \
+        qn completions fish > ~/.config/fish/completions/qn.fish\n\n\
+        ### PowerShell\n\n  \
+        Add the following line to your profile script (`$PROFILE`):\n\n      \
+        qn completions powershell | Out-String | Invoke-Expression\n\n  \
+        Or append the generated script so it loads each session:\n\n      \
+        qn completions powershell >> $PROFILE")]
     Completions {
         /// Shell to generate completions for.
         #[arg(value_enum)]