[codex] Fix inspect flags and help coverage

changelog.d/unreleased/3663.fixed.md

@@ -0,0 +1,16 @@
+---
+category: fixed
+issues:
+  - 3663
+affected:
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+---
+
+## English
+
+- List every implemented command in the top-level `cdidx --help` command summary, including navigation helpers such as `files`, `find`, `excerpt`, and `languages`.
+
+## 日本語
+
+- `cdidx --help` の top-level command summary に、`files`、`find`、`excerpt`、`languages` などを含む実装済みコマンドをすべて表示するようにしました。

changelog.d/unreleased/3665.fixed.md

@@ -0,0 +1,20 @@
+---
+category: fixed
+issues:
+  - 3665
+affected:
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - USER_GUIDE.md
+  - tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+---
+
+## English
+
+- **`inspect` accepts `--body-line-count` as a `--body-lines` alias (#3665)** — CLI parsing, help, and docs now recognize the natural body line count spelling.
+
+## 日本語
+
+- **`inspect` が `--body-lines` の alias として `--body-line-count` を受け付けるようになりました (#3665)** — CLI parser、help、docs が自然な body line count の綴りを認識します。

changelog.d/unreleased/3666.fixed.md

@@ -0,0 +1,21 @@
+---
+category: fixed
+issues:
+  - 3666
+affected:
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - src/CodeIndex/Database/DbSymbolReader.cs
+  - USER_GUIDE.md
+  - tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+---
+
+## English
+
+- Let `cdidx inspect --kind <kind>` filter definition candidates and prefer production source definitions over test definitions when both match the same query.
+
+## 日本語
+
+- `cdidx inspect --kind <kind>` で定義候補を絞り込み、同じクエリで本番ソースとテスト定義が両方一致する場合は本番ソース定義を優先するようにしました。

changelog.d/unreleased/3786.fixed.md

@@ -0,0 +1,20 @@
+---
+category: fixed
+issues:
+  - 3786
+affected:
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - USER_GUIDE.md
+  - tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+---
+
+## English
+
+- Add `inspect` source excerpts via `--line`, `--start-line`, `--end-line`, and context flags so JSON includes bounded `source_excerpt` metadata and human output shows numbered source lines.
+
+## 日本語
+
+- `inspect` に `--line`、`--start-line`、`--end-line`、context 系 flag による source excerpt を追加し、JSON では範囲付き `source_excerpt` metadata、人間向け出力では行番号付き source 行を表示するようにしました。

src/CodeIndex/Cli/CliFlagSchema.cs

@@ -116,7 +116,7 @@ internal static class CliFlagSchema
 
     private static readonly string[] KindCommands =
     [
-        "definition", "goto", "references", "callers", "callees", "symbols", "unused", "hotspots", "validate",
+        "definition", "goto", "references", "callers", "callees", "symbols", "inspect", "unused", "hotspots", "validate",
     ];
     private static readonly string[] SeverityCommands = ["validate"];
     private static readonly string[] VisibilityCommands =
@@ -161,6 +161,7 @@ internal static class CliFlagSchema
 
     private static readonly string[] BodyCommands = ["definition", "references", "callers", "callees", "impact", "inspect"];
     private static readonly string[] InspectFieldCommands = ["inspect"];
+    private static readonly string[] InspectSourceExcerptCommands = ["inspect"];
 
     private static readonly string[] MaxLineWidthCommands =
     [
@@ -300,7 +301,8 @@ private static IReadOnlyList<CliFlag> BuildAll()
             new() { Name = "--body", Description = "Include definition body snippets in JSON-capable result rows", Commands = Set(BodyCommands) },
             new() { Name = "--body-start", ValuePlaceholder = "<line>", Description = "Inspect: start definition body slice at this 1-based source line", Commands = Set(InspectFieldCommands) },
             new() { Name = "--body-lines", ValuePlaceholder = "<n>", Description = "Inspect: return at most this many definition body lines", Commands = Set(InspectFieldCommands) },
-            new() { Name = "--fields", ValuePlaceholder = "<file,workspace,graph,definitions,body,nearby_symbols,references,callers,callees,all>", Description = "Inspect: select top-level JSON evidence groups", Commands = Set(InspectFieldCommands) },
+            new() { Name = "--body-line-count", ValuePlaceholder = "<n>", Description = "Inspect: alias for --body-lines", Commands = Set(InspectFieldCommands) },
+            new() { Name = "--fields", ValuePlaceholder = "<file,workspace,graph,definitions,body,source_excerpt,nearby_symbols,references,callers,callees,all>", Description = "Inspect: select top-level JSON evidence groups", Commands = Set(InspectFieldCommands) },
             new() { Name = "--body-only", Description = "Inspect: body-focused JSON shorthand for --body --fields definitions", Commands = Set(InspectFieldCommands) },
             new() { Name = "--exact", Description = "Backward-compatible exact shorthand", Commands = Set(ExactCommands) },
             new() { Name = "--regex", Description = "Use regular expression matching", Commands = Set("find") },
@@ -334,12 +336,14 @@ private static IReadOnlyList<CliFlag> BuildAll()
             new() { Name = "--fts", Description = "Raw FTS5 syntax", Commands = Set("search") },
             new() { Name = "--no-dedup", Description = "Show duplicate chunks", Commands = Set("search") },
             new() { Name = "--no-visibility-rank", Description = "Keep legacy search ranking without symbol visibility weighting", Commands = Set("search") },
-            new() { Name = "--before", ValuePlaceholder = "<n>", Description = "Context lines before", Commands = Set("find", "excerpt") },
-            new() { Name = "--after", ValuePlaceholder = "<n>", Description = "Context lines after", Commands = Set("find", "excerpt") },
+            new() { Name = "--line", ValuePlaceholder = "<line>", Description = "Inspect: include one source line as source_excerpt", Commands = Set(InspectSourceExcerptCommands) },
+            new() { Name = "--context", ValuePlaceholder = "<n>", Description = "Inspect: source_excerpt context lines before and after", Commands = Set(InspectSourceExcerptCommands) },
+            new() { Name = "--before", ValuePlaceholder = "<n>", Description = "Context lines before", Commands = Set("find", "excerpt", "inspect") },
+            new() { Name = "--after", ValuePlaceholder = "<n>", Description = "Context lines after", Commands = Set("find", "excerpt", "inspect") },
             new() { Name = "--start", ValuePlaceholder = "<line>", Description = "Start line", Commands = Set("excerpt") },
-            new() { Name = "--start-line", ValuePlaceholder = "<line>", Description = "Alias for --start", Commands = Set("excerpt") },
+            new() { Name = "--start-line", ValuePlaceholder = "<line>", Description = "Alias for --start; inspect source_excerpt start line", Commands = Set("excerpt", "inspect") },
             new() { Name = "--end", ValuePlaceholder = "<line>", Description = "End line", Commands = Set("excerpt") },
-            new() { Name = "--end-line", ValuePlaceholder = "<line>", Description = "Alias for --end", Commands = Set("excerpt") },
+            new() { Name = "--end-line", ValuePlaceholder = "<line>", Description = "Alias for --end; inspect source_excerpt end line", Commands = Set("excerpt", "inspect") },
             new() { Name = "--focus-line", ValuePlaceholder = "<line>", Description = "Focused line to keep visible when clamping", Commands = Set("find", "excerpt") },
             new() { Name = "--focus-column", ValuePlaceholder = "<n>", Description = "Focused column to keep visible when clamping", Commands = Set("find", "excerpt") },
             new() { Name = "--focus-length", ValuePlaceholder = "<n>", Description = "Focused span width when clamping", Commands = Set("excerpt") },

src/CodeIndex/Cli/ConsoleUi.cs

@@ -99,7 +99,7 @@ private static readonly (string Command, string Usage)[] CommandUsageLines =
         ("find", "cdidx find <query> (--path <glob>|--all) [--db <path>] [--json] [--format <text|json|count|compact|csv|tsv|lsp|qf|sarif>] [--verbose] [--limit <n>|--top <n>] [--lang <lang>] [--exclude-path <glob>] [--exclude-tests] [--before <n>] [--after <n>] [--snippet-lines <n>] [--focus-line <line>] [--focus-column <n>] [--max-line-width <n>] [--exact] [--regex] [--count]"),
         ("excerpt", "cdidx excerpt <path> --start <line> [--end <line>] [--before <n>] [--after <n>] [--max-line-width <n>] [--focus-line <line>] [--focus-column <n>] [--focus-length <n>] [--db <path>] [--json] [--verbose]"),
         ("map", "cdidx map [--db <path>] [--json] [--format <text|json|compact>] [--pretty] [--compact] [--summary-only] [--verbose] [--limit <n>|--top <n>] [--lang <lang>] [--path <glob>] [--exclude-path <glob>] [--exclude-tests] [--bytes] [--sections <tree,languages,hotspots,metrics>] [--depth <n>] [--min-entrypoint-confidence <0.0..1.0>]"),
-        ("inspect", "cdidx inspect <query>|--query <query>|-- <query> [--db <path>] [--json] [--format <text|json|compact>] [--pretty] [--compact] [--fields <csv>] [--body-only] [--verbose] [--limit <n>|--top <n>] [--lang <lang>] [--path <glob>] [--exclude-path <glob>] [--exclude-tests] [--body] [--body-start <line>] [--body-lines <n>] [--max-line-width <n>] [--exact|--exact-name]"),
+        ("inspect", "cdidx inspect <query>|--query <query>|-- <query>|--path <file> --line <line> [--db <path>] [--json] [--format <text|json|compact>] [--pretty] [--compact] [--fields <csv>] [--body-only] [--verbose] [--limit <n>|--top <n>] [--lang <lang>] [--kind <kind>] [--path <glob>] [--exclude-path <glob>] [--exclude-tests] [--body] [--body-start <line>] [--body-lines <n>|--body-line-count <n>] [--line <line>|--start-line <line>] [--end-line <line>] [--context <n>|--before <n>|--after <n>] [--max-line-width <n>] [--exact|--exact-name]"),
         ("outline", "cdidx outline <path> [--db <path>] [--json] [--pretty] [--compact] [--verbose] [--limit <n>|--top <n>]"),
         ("status", "cdidx status [--db <path>] [--json] [--verbose] [--check[=workspace,fold,graph,issues,hotspot,csharp,sql,newer]] [--stale-after <duration>] [--explain <field>] [--log-path] [--config] [--check-updates]"),
         ("workspace", "cdidx workspace <list|status|use|current> [name] [--json]"),
@@ -833,29 +833,7 @@ public static void PrintUsageBrief(bool showBanner = true)
         Console.WriteLine("  cdidx --help-all");
         Console.WriteLine("  cdidx --help-flags");
         Console.WriteLine();
-        Console.WriteLine("Commands:");
-        Console.WriteLine("  index <projectPath>        Build or update the index for a project");
-        Console.WriteLine("  search <query>             Full-text search across indexed chunks");
-        Console.WriteLine("  definition <query>         Resolve symbol definitions with extracted ranges");
-        Console.WriteLine("  references <query>         Find indexed references for a symbol (--kind uses reference kind)");
-        Console.WriteLine("  callers <query>            Find callers of a symbol (--kind uses reference kind)");
-        Console.WriteLine("  callees <query>            Find callees used by a caller (--kind uses reference kind)");
-        Console.WriteLine("  symbols [query]            Search symbols (functions, classes, imports)");
-        Console.WriteLine("  map                        Show a repo-level overview for AI orientation");
-        Console.WriteLine("  inspect <query>            Bundle definition, graph, and nearby symbol context");
-        Console.WriteLine("  status                     Show database statistics, freshness, config, and logs");
-        Console.WriteLine("  doctor                     Print a redacted environment summary for bug reports");
-        Console.WriteLine("  validate                   Report encoding issues (U+FFFD origin/severity, BOM, null bytes, mixed line endings, UTF-16 BOM, likely non-UTF8)");
-        Console.WriteLine("  impact <query>             Show transitive callers; type queries may return heuristic file-level dependency hints");
-        Console.WriteLine("  deps                       Show file-level dependency edges from the reference graph");
-        Console.WriteLine("  unused                     Find symbols defined but never referenced (dead code)");
-        Console.WriteLine("  hotspots                   Find high-impact symbols; duplicate-name families may fall back conservatively");
-        Console.WriteLine("  export                     Export ctags or a portable CodeIndex archive");
-        Console.WriteLine("  import                     Import a portable CodeIndex archive");
-        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("  lsp                        Start LSP server over stdio (for LSP-native editors)");
-        Console.WriteLine("  completions <shell>        Generate shell completions for bash, zsh, fish, or PowerShell");
+        PrintCommandSummary();
         Console.WriteLine();
         Console.WriteLine("Run `cdidx --help-all` for every command and option, `cdidx --help-flags` for shared flags, or `cdidx <command> --help` for one command.");
         Console.WriteLine();
@@ -929,6 +907,7 @@ private static void PrintCommandSummary()
     {
         Console.WriteLine("Commands:");
         Console.WriteLine("  index <projectPath>        Build or update the index for a project");
+        Console.WriteLine("  hooks                      Install, uninstall, or inspect git hook integration");
         Console.WriteLine("  backfill-fold              Upgrade folded-name columns in an existing index DB");
         Console.WriteLine("  optimize                   Optimize FTS5 segments in an existing index DB");
         Console.WriteLine("  vacuum                     Reclaim free SQLite pages from an existing index DB");