feat(cli): add shell completions

.changeset/cli-completions.md

@@ -0,0 +1,6 @@
+---
+"caplets": minor
+"@caplets/core": minor
+---
+
+Add Bash, Zsh, Fish, PowerShell, and cmd shell completion generation plus config-aware and cache-backed downstream completion suggestions for the Caplets CLI.

README.md

@@ -89,6 +89,38 @@ caplets complete docs --resource-template 'file:///repo/{path}' --argument path
 
 Direct CLI operation commands print Markdown summaries by default. Add `--format plain` for plain text or `--format json` for machine-readable JSON (`md` is accepted as an alias for `markdown`). If a downstream tool returns `isError: true`, Caplets still exits with status code 1.
 
+### Shell completions
+
+The npm package ships shell completion generators for Bash, Zsh, Fish, PowerShell, and cmd. Installation is explicit: `npm install -g caplets` does not modify shell startup files or system completion directories.
+
+```sh
+# Bash
+mkdir -p ~/.local/share/bash-completion/completions
+caplets completion bash > ~/.local/share/bash-completion/completions/caplets
+
+# Zsh
+mkdir -p ~/.zsh/completions
+caplets completion zsh > ~/.zsh/completions/_caplets
+# Ensure ~/.zsh/completions is on fpath before compinit, then reload your shell:
+# echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
+# echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
+
+# Fish
+mkdir -p ~/.config/fish/completions
+caplets completion fish > ~/.config/fish/completions/caplets.fish
+
+# PowerShell
+caplets completion powershell | Out-String | Invoke-Expression
+
+# cmd.exe
+caplets completion cmd > %USERPROFILE%\caplets-completion.cmd
+%USERPROFILE%\caplets-completion.cmd
+```
+
+Completions include command names, options, common enum values, configured Caplet IDs, and cache-backed downstream names for qualified targets such as `caplets call-tool repo.<TAB>`. Downstream discovery is bounded by the `completion` config timeouts and a platform-native cache directory. Generated shell scripts suppress completion stderr; run the underlying CLI command directly when debugging completion behavior.
+
+Backends that require OAuth or token auth may need `caplets auth login <server>` before live downstream completions can return richer results. Completion never starts interactive login flows.
+
 ## Agent Plugins
 
 Use Caplets as a normal MCP server everywhere, or install a native agent integration when
@@ -297,6 +329,12 @@ you want Caplets to expose:
   "version": 1,
   "defaultSearchLimit": 20,
   "maxSearchLimit": 50,
+  "completion": {
+    "discoveryTimeoutMs": 750,
+    "overallTimeoutMs": 1500,
+    "cacheTtlMs": 300000,
+    "negativeCacheTtlMs": 30000
+  },
   "mcpServers": {
     "filesystem": {
       "name": "Project Files",