docs(completions): document zsh fpath requirement for tab-completion (DX-5783)

Brew installs the completion files, but zsh only autoloads a completion
when its directory is on $fpath before compinit runs — so `qn <TAB>`
still fell back to filename completion for many zsh users.

Document the requirement in the README (both completions sections, linking
the zsh manual) and make `qn completions --help` self-documenting with a
long_about explaining install-path and zsh nuances plus per-shell install
examples. No behavior change to the command itself.

Author: johnpmitsch

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 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,16 +249,30 @@ qn team list
 
 ## Shell completions
 
-Homebrew installs completions automatically (see above). For other install
-methods, generate them yourself:
+Some installs place the completion file for you — Homebrew (see above) and
+distro packages drop it in the shell's standard directory. Other install methods
+(`cargo install`, a downloaded binary or tarball, Scoop) do not, so generate the
+script yourself and write it where your shell loads completions from:
 
 ```sh
-qn completions zsh  > ~/.zfunc/_qn        # zsh
-qn completions bash > /etc/bash_completion.d/qn  # bash
+# zsh — write into a dir on your $fpath, then run compinit
+mkdir -p ~/.zfunc
+qn completions zsh > ~/.zfunc/_qn
+
+# bash — source it from ~/.bashrc (needs bash-completion)
+echo 'source <(qn completions bash)' >> ~/.bashrc
+
+# fish — write into fish's completions dir
 qn completions fish > ~/.config/fish/completions/qn.fish
-qn completions powershell > qn.ps1
+
+# powershell — add to your $PROFILE
+qn completions powershell | Out-String | Invoke-Expression
 ```
 
+For zsh, the completion file's directory must be on `$fpath` before `compinit`
+runs — see the
+[zsh completion-system manual](https://zsh.sourceforge.io/Doc/Release/Completion-System.html).
+
 ## Configuration via environment
 
 The conventional variables are honored: `NO_COLOR` and `TERM=dumb` disable color,

src/cli.rs

@@ -146,6 +146,28 @@ pub enum Command {
     Kv(commands::kv::Args),
 
     /// Generate shell completions.
+    ///
+    /// Some installs place the completion file for you (Homebrew and distro
+    /// packages drop it in the shell's standard directory); others
+    /// (`cargo install`, a downloaded binary or tarball, Scoop) do not — for
+    /// those, generate the script with this command and write it where your
+    /// shell loads completions from (see the examples below).
+    ///
+    /// zsh has one extra requirement even once the file is installed: it only
+    /// autoloads a completion when that file's directory is on `$fpath` before
+    /// `compinit` runs during shell startup. If `qn <TAB>` falls back to
+    /// listing files, that directory is missing from `$fpath`. See the zsh
+    /// manual: https://zsh.sourceforge.io/Doc/Release/Completion-System.html
+    #[command(after_help = "Examples:\n  \
+        # zsh — write into a dir on your $fpath, then run compinit (see above)\n  \
+        mkdir -p ~/.zfunc\n  \
+        qn completions zsh > ~/.zfunc/_qn\n\n  \
+        # bash — source it from ~/.bashrc (needs bash-completion)\n  \
+        echo 'source <(qn completions bash)' >> ~/.bashrc\n\n  \
+        # fish — write into fish's completions dir (loaded on next shell)\n  \
+        qn completions fish > ~/.config/fish/completions/qn.fish\n\n  \
+        # powershell — add to your $PROFILE\n  \
+        qn completions powershell | Out-String | Invoke-Expression")]
     Completions {
         /// Shell to generate completions for.
         #[arg(value_enum)]