docs(console): update shell completion documentation

Author: xHeaven

docs/1-essentials/04-console-commands.md

@@ -240,7 +240,9 @@ Interactive components are only supported on Mac and Linux. On Windows, Tempest
 
 ## Shell completion
 
-Tempest provides shell completion for Zsh and Bash. This allows you to press `Tab` to autocomplete command names and options.
+Tempest provides shell completion for Zsh and Bash on Linux and macOS. This allows you to press `Tab` to autocomplete command names and options. On Windows, use WSL.
+
+Completion relies on two things: a **completion script** sourced by your shell, and a **helper binary** that performs the actual matching. The helper binary is not bundled with Tempest. It is downloaded from the GitHub release matching your installed Tempest version.
 
 ### Installing completions
 
@@ -250,28 +252,46 @@ Run the install command and follow the prompts:
 <dim>./</dim>tempest completion:install
 ```
 
-The installer will detect your current shell, copy the completion script to the appropriate location, and provide instructions for enabling it.
+This will:
+
+1. Detect your shell (or use `--shell=zsh` / `--shell=bash`).
+2. Generate completion metadata (`commands.json`) for all registered commands.
+3. Download the platform-specific helper binary from the matching Tempest release.
+4. Install the completion script to the appropriate location.
 
-For Zsh, you'll need to ensure the completions directory is in your `fpath` and reload completions:
+After installation, add the following line to your shell configuration file and restart your terminal:
 
-```zsh
-# Add to ~/.zshrc
-fpath=(~/.zsh/completions $fpath)
-autoload -Uz compinit && compinit
+```bash
+# Zsh: add to ~/.zshrc
+source ~/.tempest/completion/tempest.zsh
+
+# Bash: add to ~/.bashrc
+source ~/.tempest/completion/tempest.bash
 ```
 
-For Bash, source the completion file in your `~/.bashrc`:
+### Keeping completions up to date
 
-```bash
-source ~/.bash_completion.d/tempest.bash
+After adding or removing commands, regenerate the metadata:
+
+```console
+<dim>./</dim>tempest completion:generate
 ```
 
-### Additional commands
+After updating Tempest to a new version, update the helper binary:
+
+```console
+<dim>./</dim>tempest completion:update-bin
+```
 
-You may also use these related commands:
+### Available commands
 
-- `completion:show` — Output the completion script to stdout (useful for custom installation)
-- `completion:uninstall` — Remove the installed completion script
+| Command                 | Description                                                              |
+|-------------------------|--------------------------------------------------------------------------|
+| `completion:install`    | Install the completion script and download the helper binary.            |
+| `completion:generate`   | Regenerate the completion metadata JSON.                                 |
+| `completion:update-bin` | Re-download the helper binary for the current Tempest version.           |
+| `completion:show`       | Output the completion script to stdout (useful for custom installation). |
+| `completion:uninstall`  | Remove the installed completion script.                                  |
 
 ## Middleware