feat(cli): codegraph completions for zsh/bash/fish/powershell with auto-detected install paths

README.md

@@ -1,4 +1,4 @@
-<div align="center">
+  <div align="center">
 
 # CodeGraph
 
@@ -326,6 +326,7 @@ codegraph files [path]            # Show file structure (--format, --filter, --m
 codegraph context <task>          # Build context for AI (--format, --max-nodes)
 codegraph affected [files...]     # Find test files affected by changes (see below)
 codegraph serve --mcp             # Start MCP server
+codegraph completions <shell>     # Generate shell completions for zsh/bash/fish/powershell (see below)
 ```
 
 ### `codegraph affected`
@@ -356,6 +357,48 @@ if [ -n "$AFFECTED" ]; then
 fi
 ```
 
+### `codegraph completions`
+
+Generate a static completion script for your shell. Supported shells: `zsh`, `bash`, `fish`, `powershell` (aliases: `pwsh`, `ps`).
+
+```bash
+codegraph completions zsh        --install   # auto-detects best path
+codegraph completions bash       --install
+codegraph completions fish       --install
+codegraph completions powershell --install
+```
+
+With `--install`, codegraph picks the right location for your environment and writes there. The exact path is reported as `(detected: <tier>)` so you can see which rule fired. **Restart your shell** (or `exec $SHELL`) to pick up the new completions.
+
+| Shell | Detection priority |
+|---|---|
+| **zsh** | oh-my-zsh (`$ZSH/completions/`) → `<prefix>/share/zsh/site-functions/` if writable → `~/.zsh/completions/` (fallback; prints `fpath` hint) |
+| **bash** | `<homebrew>/etc/bash_completion.d/` if writable → XDG `~/.local/share/bash-completion/completions/` |
+| **fish** | `~/.config/fish/completions/` (auto-discovered) |
+| **powershell** | Standalone `.ps1` in `~/.config/powershell/` (`~/Documents/PowerShell/` on Windows) + idempotent dot-source line in `$PROFILE`. Re-running `--install` won't duplicate the line. |
+
+**Without `--install`** the script goes to stdout — pipe it wherever you want:
+
+```bash
+codegraph completions zsh        > ~/.zsh/completions/_codegraph
+codegraph completions bash       > ~/.local/share/bash-completion/completions/codegraph
+codegraph completions fish       > ~/.config/fish/completions/codegraph.fish
+codegraph completions powershell > ~/codegraph-completion.ps1   # then dot-source from $PROFILE
+```
+
+**Per-shell requirements:**
+- **bash**: needs the `bash-completion` package. macOS: `brew install bash-completion@2` (and follow its post-install instructions).
+- **zsh** (fallback tier only): if codegraph wrote to `~/.zsh/completions/_codegraph`, add this to `~/.zshrc` *before* `compinit`:
+  ```zsh
+  fpath=(~/.zsh/completions $fpath)
+  autoload -Uz compinit && compinit
+  ```
+  If the install reported `(detected: oh-my-zsh)` or `(detected: zsh-site-functions)`, this step is unnecessary.
+- **fish**: no extra config — auto-discovered.
+- **powershell**: works in PowerShell 7.x (`pwsh`). Windows PowerShell 5.1 also works but uses a different `$PROFILE` path; if our chosen path doesn't match yours, dot-source the `.ps1` manually.
+
+If you're on a shell we don't recognize (`nushell`, `xonsh`, etc.), the command exits non-zero with a hint and writes nothing.
+
 ---
 
 ## MCP Tools