Document shell completion discovery

USER_GUIDE.md

@@ -144,15 +144,34 @@ file statuses. Use incremental refreshes after the first run; see
 ## Shell completion
 
 Generate completion scripts with `cdidx --completions <bash|zsh|fish|powershell>`.
+The same generator is also available as `cdidx completions <shell>`.
+Supported shells are Bash, Zsh, Fish, and PowerShell.
 The generated scripts complete subcommands, flags, and common flag values.
 `--lang` suggests supported languages, `--kind` suggests symbol/reference kinds,
 and path-like options such as `--db`, `--path`, and `--output` use shell file
 completion.
 
+Install the script in the startup file or completion directory for your shell:
+
+```bash
+# Bash: append to your interactive shell startup file
+cdidx --completions bash >> ~/.bashrc
+
+# Zsh: write an fpath entry, then enable compinit from your ~/.zshrc
+mkdir -p ~/.zfunc
+cdidx --completions zsh > ~/.zfunc/_cdidx
+printf '%s\n' 'fpath=(~/.zfunc $fpath)' 'autoload -Uz compinit && compinit' >> ~/.zshrc
+
+# Fish: write to the standard per-user completions directory
+mkdir -p ~/.config/fish/completions
+cdidx --completions fish > ~/.config/fish/completions/cdidx.fish
+```
+
 For PowerShell, add the generated `Register-ArgumentCompleter` script to your
 profile after installing `cdidx`:
 
 ```powershell
+New-Item -ItemType Directory -Force -Path (Split-Path -Parent $PROFILE)
 cdidx --completions powershell >> $PROFILE
 . $PROFILE
 ```
@@ -2375,6 +2394,40 @@ PATH追加後はターミナルを再起動してください。
 cdidx --version
 ```
 
+## シェル補完
+
+`cdidx --completions <bash|zsh|fish|powershell>` で補完スクリプトを生成できます。
+同じ generator は `cdidx completions <shell>` でも利用できます。対応シェルは
+Bash、Zsh、Fish、PowerShell です。生成されたスクリプトは subcommand、flag、
+よく使う flag value を補完し、`--lang` は対応言語、`--kind` は symbol/reference
+kind、`--db` / `--path` / `--output` のような path 系 option は shell の file
+completion を使います。
+
+使っている shell の startup file または completion directory に保存してください:
+
+```bash
+# Bash: interactive shell startup file に追記
+cdidx --completions bash >> ~/.bashrc
+
+# Zsh: fpath 用の directory に書き出し、~/.zshrc で compinit を有効化
+mkdir -p ~/.zfunc
+cdidx --completions zsh > ~/.zfunc/_cdidx
+printf '%s\n' 'fpath=(~/.zfunc $fpath)' 'autoload -Uz compinit && compinit' >> ~/.zshrc
+
+# Fish: ユーザー別 completion directory に書き出し
+mkdir -p ~/.config/fish/completions
+cdidx --completions fish > ~/.config/fish/completions/cdidx.fish
+```
+
+PowerShell では、`cdidx` のインストール後に生成された
+`Register-ArgumentCompleter` script を profile に追加します:
+
+```powershell
+New-Item -ItemType Directory -Force -Path (Split-Path -Parent $PROFILE)
+cdidx --completions powershell >> $PROFILE
+. $PROFILE
+```
+
 ## クイックスタート
 
 ### プロジェクトをインデックス

changelog.d/unreleased/1639.docs.md

@@ -0,0 +1,17 @@
+---
+category: docs
+issues:
+  - 1639
+affected:
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - USER_GUIDE.md
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+---
+
+## English
+
+- **Shell completions are now discoverable from help and the user guide (#1639)** — `cdidx --help` now advertises both completion entry points and all supported shells, while `USER_GUIDE.md` includes Bash, Zsh, Fish, and PowerShell install snippets.
+
+## 日本語
+
+- **シェル補完を help と user guide から見つけられるようにしました (#1639)** — `cdidx --help` が補完用 entry point と対応 shell を案内し、`USER_GUIDE.md` に Bash / Zsh / Fish / PowerShell の install 例を追加しました。

src/CodeIndex/Cli/ConsoleUi.cs

@@ -94,6 +94,7 @@ private static readonly (string Command, string Usage)[] CommandUsageLines =
         ("batch", "cdidx batch [--db <path>]  # reads JSON string arrays from stdin, one query command per line"),
         ("mcp", "cdidx mcp [--db <path>]"),
         ("completions", "cdidx completions <shell>"),
+        ("--completions", "cdidx --completions <shell>"),
         ("license", "cdidx license"),
     ];
 
@@ -647,6 +648,7 @@ public static void PrintUsage(bool showBanner = true)
         Console.WriteLine("  languages                  List supported languages and their capabilities");
         Console.WriteLine("  batch                      Run newline-delimited JSON query commands with one DB connection");
         Console.WriteLine("  mcp                        Start MCP server (for AI tools: Claude, Cursor, etc.)");
+        Console.WriteLine("  completions <shell>        Generate shell completions for bash, zsh, fish, or PowerShell");
         Console.WriteLine("  license                    Show licensing, trademark, and commercial-use summary");
         Console.WriteLine();
         Console.WriteLine("Index and update options:");
@@ -676,7 +678,7 @@ public static void PrintUsage(bool showBanner = true)
         Console.WriteLine("  --help, -h                 Show this help message");
         Console.WriteLine("  --version, -V              Show version information");
         Console.WriteLine("  --license                  Show licensing, trademark, and commercial-use summary");
-        Console.WriteLine("  --completions <shell>      Generate shell completions (bash, zsh, fish)");
+        Console.WriteLine("  --completions <shell>      Generate shell completions (bash, zsh, fish, powershell)");
         Console.WriteLine();
         Console.WriteLine("Update workflows:");
         Console.WriteLine("  Use --commits with a project path after normal commits; git diff sees rename/delete paths too.");
@@ -770,6 +772,7 @@ public static void PrintUsage(bool showBanner = true)
         Console.WriteLine("  cdidx files --since 2024-01-01                 Files modified since a date");
         Console.WriteLine("  cdidx status --json                            DB stats as JSON");
         Console.WriteLine("  cdidx languages                                Show supported languages");
+        Console.WriteLine("  cdidx --completions zsh > ~/.zfunc/_cdidx      Generate a zsh completion script");
         Console.WriteLine("  cdidx license                                  Show licensing and commercial-use terms");
     }
 

tests/CodeIndex.Tests/ConsoleUiTests.cs

@@ -64,6 +64,8 @@ public void PrintUsage_WithoutBanner_HidesAsciiArtAndEasterEggFlags()
         Assert.Contains("cdidx backfill-fold [--db <path>] [--json]", output);
         Assert.Contains("cdidx optimize [--db <path>] [--json]", output);
         Assert.Contains("cdidx license", output);
+        Assert.Contains("cdidx completions <shell>", output);
+        Assert.Contains("cdidx --completions <shell>", output);
         Assert.Contains("cdidx references <query>|--query <query>|-- <query>", output);
         Assert.Contains("cdidx callers <query>|--query <query>|-- <query>", output);
         Assert.Contains("cdidx callees <query>|--query <query>|-- <query>", output);
@@ -117,6 +119,9 @@ public void PrintUsage_WithoutBanner_HidesAsciiArtAndEasterEggFlags()
         Assert.Contains("cdidx impact FolderDiffService --json           Type query may return heuristic file-level dependency hints", output);
         Assert.Contains("license                    Show licensing, trademark, and commercial-use summary", output);
         Assert.Contains("--license                  Show licensing, trademark, and commercial-use summary", output);
+        Assert.Contains("completions <shell>        Generate shell completions for bash, zsh, fish, or PowerShell", output);
+        Assert.Contains("--completions <shell>      Generate shell completions (bash, zsh, fish, powershell)", output);
+        Assert.Contains("cdidx --completions zsh > ~/.zfunc/_cdidx      Generate a zsh completion script", output);
         Assert.Contains("cdidx license                                  Show licensing and commercial-use terms", output);
         Assert.DoesNotContain("Easter eggs", output);
         Assert.DoesNotContain("--sushi", output);
@@ -147,6 +152,8 @@ public void PrintUsage_QueryLinesMatchImplementedOptions()
         Assert.Contains("cdidx hotspots [--db <path>] [--json] [--verbose] [--limit <n>] [--kind <kind>] [--visibility <v[,v]>] [--exclude-visibility <v[,v]>] [--lang <lang>] [--path <glob>] [--exclude-path <glob>] [--exclude-tests] [--count]", output);
         Assert.Contains("cdidx unused [--db <path>] [--json] [--verbose] [--limit <n>] [--kind <kind>] [--visibility <v[,v]>] [--exclude-visibility <v[,v]>] [--lang <lang>] [--path <glob>] [--exclude-path <glob>] [--exclude-tests] [--count]", output);
         Assert.Contains("cdidx license", output);
+        Assert.Contains("cdidx completions <shell>", output);
+        Assert.Contains("cdidx --completions <shell>", output);
     }
 
     [Theory]