From 472b563d4788c2248760d34f195b843da3177e5e Mon Sep 17 00:00:00 2001
From: Satvik Mishra <satvikmishra.ipu146183@maims.ac.in>
Date: Sat, 19 Sep 2026 09:39:32 +0000
Subject: [PATCH] docs: add a shell completions installation guide

---
 docs/src/SUMMARY.md               |  1 +
 docs/src/getting-started.md       |  2 +
 docs/src/reference/completions.md | 63 +++++++++++++++++++++++++++++++
 3 files changed, 66 insertions(+)
 create mode 100644 docs/src/reference/completions.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index e56db41..12943c4 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -15,6 +15,7 @@
   - [Value Buffer Protocol](reference/value-buffers.md)
   - [Memory & Error Model](reference/memory-error.md)
   - [Naming and Package Conventions](reference/naming.md)
+  - [Shell Completions](reference/completions.md)
 - [Generators](generators/README.md)
   - [Kotlin](generators/kotlin.md)
   - [C](generators/c.md)
diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md
index a24ba3b..30927c7 100644
--- a/docs/src/getting-started.md
+++ b/docs/src/getting-started.md
@@ -34,6 +34,8 @@ cargo install weaveffi-cli
 
 This puts the `weaveffi` binary on your `PATH`.
 
+For tab completion in your shell, see [Shell Completions](reference/completions.md).
+
 ## 2) Define your API as an IDL
 
 Describe the API once in a language-neutral IDL. Create `math.yml` with a
diff --git a/docs/src/reference/completions.md b/docs/src/reference/completions.md
new file mode 100644
index 0000000..1a7362d
--- /dev/null
+++ b/docs/src/reference/completions.md
@@ -0,0 +1,63 @@
+# Shell Completions
+
+`weaveffi completions <shell>` prints a completion script for bash, zsh, fish, powershell, or elvish. Generate one with:
+
+```bash
+weaveffi completions bash
+```
+
+Replace `bash` with your shell name. Install the script using the matching section below.
+
+## bash
+
+```bash
+mkdir -p ~/.local/share/bash-completion/completions
+weaveffi completions bash > ~/.local/share/bash-completion/completions/weaveffi
+```
+
+On systems that load `/etc/bash_completion.d`:
+
+```bash
+sudo weaveffi completions bash > /etc/bash_completion.d/weaveffi
+```
+
+## zsh
+
+Write the script as `_weaveffi` in a directory on your `$fpath`:
+
+```bash
+mkdir -p ~/.zfunc
+weaveffi completions zsh > ~/.zfunc/_weaveffi
+```
+
+Then in `~/.zshrc` (run `compinit` after updating `fpath`):
+
+```zsh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit && compinit
+```
+
+## fish
+
+```bash
+mkdir -p ~/.config/fish/completions
+weaveffi completions fish > ~/.config/fish/completions/weaveffi.fish
+```
+
+## PowerShell
+
+Append the script to your profile:
+
+```powershell
+weaveffi completions powershell >> $PROFILE
+```
+
+Reload the profile or open a new session.
+
+## elvish
+
+Evaluate the script from `rc.elv` (for example):
+
+```elvish
+eval (weaveffi completions elvish | slurp)
+```