[codex] Add AI-focused JSON controls

USER_GUIDE.md

@@ -302,11 +302,24 @@ Most query commands emit one complete JSON value when `--json` is set. `search
 per line as newline-delimited JSON (ndjson), then a final `{"done":true,...}`
 line. Stream consumers can parse each line as it arrives; array-oriented tools
 can use `jq -s '.'` or pass `--json=array` to `search` to emit the result set as
-one JSON array.
+one JSON array. Add `--pretty` with `--json` to indent single-document JSON
+responses; for `search`, use `--json=array --pretty` when the result set itself
+should be indented because default `search --json` stays newline-delimited.
+For AI-oriented bounded payloads, `map`, `inspect`, and `outline` accept
+`--compact`. It implies JSON output, caps list sections to 5 items by default
+(or the explicit `--limit` / `--top` value), and adds `compact`,
+`compact_limit`, and `truncation.sections.*` metadata.
+For narrower `inspect` evidence, `--fields <csv>` implies JSON and selects
+top-level groups such as `definitions`, `file`, `graph`, `references`,
+`callers`, and `callees`; `--body-only` is shorthand for `--body --fields
+definitions`.
 
 ```bash
 cdidx search authenticate --json          # ndjson stream, one result per line
 cdidx search authenticate --json=array    # single JSON array
+cdidx inspect QueryCommandRunner --json --pretty
+cdidx map --compact                       # capped JSON with truncation metadata
+cdidx inspect Compute --body-only         # definitions with body_content only
 ```
 
 For `cdidx find --count --json`, `files` is the canonical matched-file count.
@@ -1194,6 +1207,10 @@ same source location.
 |---|---|---|
 | `--db <path>` | All commands except `languages`; for `mcp`, only `--db` is supported | Database file path. `index` defaults to `<projectPath>/.cdidx/codeindex.db`; query commands default to `.cdidx/codeindex.db` in the current directory. Query commands without `--db` keep trusting that default `.cdidx/codeindex.db` sibling path, so moving or renaming the current repo does not leave stale workspace metadata behind. For explicit query DBs, workspace metadata such as `project_root`, `git_head`, and `git_is_dirty` comes from the persisted `indexed_project_root` stored in that DB when available. Legacy explicit DBs created before that metadata existed may return those fields as `null` / absent until you rerun `cdidx index <projectPath> --db <path>` or a scoped update that actually commits at least one file delete/update against the intended project, even if the explicit path itself looks like `.../.cdidx/codeindex.db`. |
 | `--json` | All commands except `mcp` | JSON output (for AI/machine use). `search --json` writes newline-delimited result objects followed by a final `{"done":true,"count":N,"interrupted":false}` sentinel, including zero-result output, so stream consumers can detect clean completion. |
+| `--pretty` | JSON-capable commands except `mcp` | Pretty-print JSON output with indentation. Default `search --json` remains newline-delimited; use `search --json=array --pretty` for an indented search result array. |
+| `--compact` | `map`, `inspect`, `outline` | Emit AI-oriented compact JSON with capped list sections and `truncation.sections.*` metadata. The default cap is 5 unless `--limit` / `--top` is supplied. |
+| `--fields <csv>` | `inspect` | Select top-level inspect JSON groups: `file`, `workspace`, `graph`, `definitions`, `body`, `nearby_symbols`, `references`, `callers`, `callees`, or `all`. `body` includes definition bodies and maps to `definitions`. |
+| `--body-only` | `inspect` | Shorthand for `--body --fields definitions`, useful when large audits need implementation text without graph context. |
 | `--status <all\|submitted\|unsubmitted>` | `suggestions` | Filter local suggestion history by GitHub submission state. |
 | `--language <lang>` / `--lang <lang>` | `suggestions` | Filter local suggestion history by recorded target language. |
 | `--category <category>` | `suggestions` | Filter local suggestion history by suggestion category. |
@@ -2537,11 +2554,25 @@ release changelog を source of truth とします。完全な syntax line は `
 newline-delimited JSON (ndjson) として出力し、最後に `{"done":true,...}` 行を
 出力します。stream consumer は各行を到着順に parse できます。array 前提の tool
 では `jq -s '.'` を使うか、`search` に `--json=array` を渡すと result set を
-1 つの JSON array として出力できます。
+1 つの JSON array として出力できます。`--json` と一緒に `--pretty` を付けると
+単一 document の JSON 応答をインデント付きで出力します。`search` の result set を
+整形したい場合は、既定の `search --json` が newline-delimited のまま保たれるため
+`--json=array --pretty` を使います。
+AI 向けに上限付き payload が必要な場合、`map`、`inspect`、`outline` は
+`--compact` に対応しています。これは JSON 出力を暗黙に有効化し、list section を
+既定 5 件（明示した `--limit` / `--top` があればその値）に cap し、
+`compact`、`compact_limit`、`truncation.sections.*` metadata を追加します。
+`inspect` の証跡をさらに絞りたい場合、`--fields <csv>` は JSON 出力を暗黙に有効化し、
+`definitions`、`file`、`graph`、`references`、`callers`、`callees` などの
+top-level group を選択します。`--body-only` は `--body --fields definitions` の
+shorthand です。
 
 ```bash
 cdidx search authenticate --json          # ndjson stream、1 行 1 result
 cdidx search authenticate --json=array    # 単一 JSON array
+cdidx inspect QueryCommandRunner --json --pretty
+cdidx map --compact                       # truncation metadata 付きの cap 済み JSON
+cdidx inspect Compute --body-only         # body_content 付き definitions のみ
 ```
 
 ## Editor / index portability
@@ -3428,6 +3459,10 @@ raw match density を正確に測る、といった理由で全 raw chunk hit 
 |---|---|---|
 | `--db <path>` | `languages` を除く全コマンド。`mcp` は `--db` のみ対応 | DBファイルパス。`index` のデフォルトは `<projectPath>/.cdidx/codeindex.db`、クエリ系コマンドのデフォルトはカレントディレクトリの `.cdidx/codeindex.db`。`--db` を付けない query は、その既定の `.cdidx/codeindex.db` sibling path を引き続き正とするため、カレント repo を move/rename しても古い workspace metadata を引きずらない。明示指定 query DB の `project_root`、`git_head`、`git_is_dirty` などの workspace metadata は、利用可能な場合はその DB に保存された `indexed_project_root` から解決される。保存前の古い explicit DB では、意図した project に対して `cdidx index <projectPath> --db <path>`、または少なくとも 1 件の file delete/update を実際に commit する scoped update を一度実行するまで、これらの項目が `null` / 未出力になることがあり、明示パス自体が `.../.cdidx/codeindex.db` でも同じ。 |
 | `--json` | `mcp` を除く全コマンド | JSON出力（AI/機械向け） |
+| `--pretty` | `mcp` を除く JSON 対応コマンド | JSON 出力をインデント付きで整形。既定の `search --json` は newline-delimited のまま維持されるため、検索結果配列を整形したい場合は `search --json=array --pretty` を使う。 |
+| `--compact` | `map`、`inspect`、`outline` | list section を cap した AI 向け compact JSON を出力し、`truncation.sections.*` metadata を含める。既定 cap は 5 件で、`--limit` / `--top` 指定時はその値を使う。 |
+| `--fields <csv>` | `inspect` | inspect JSON の top-level group を選択。`file`、`workspace`、`graph`、`definitions`、`body`、`nearby_symbols`、`references`、`callers`、`callees`、`all` を指定できる。`body` は definition body を含め、`definitions` に対応する。 |
+| `--body-only` | `inspect` | `--body --fields definitions` の shorthand。大規模 audit で graph context なしに実装本文だけが必要な場合に使う。 |
 | `--status <all\|submitted\|unsubmitted>` | `suggestions` | ローカル提案履歴を GitHub 送信状態で絞り込みます。 |
 | `--language <lang>` / `--lang <lang>` | `suggestions` | ローカル提案履歴を記録済み対象言語で絞り込みます。 |
 | `--category <category>` | `suggestions` | ローカル提案履歴を提案カテゴリで絞り込みます。 |

changelog.d/unreleased/2996.added.md

@@ -0,0 +1,20 @@
+---
+category: added
+issues:
+  - 2996
+affected:
+  - src/CodeIndex/Cli/ProgramRunner.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - tests/CodeIndex.Tests/ProgramRunnerTests.cs
+  - USER_GUIDE.md
+---
+
+## English
+
+- **JSON commands can now pretty-print output (#2996)** — `--pretty` enables indented JSON for commands that share the CLI JSON serializer, making large JSON payloads easier to inspect and diff.
+
+## 日本語
+
+- **JSON コマンドが整形出力に対応しました (#2996)** — `--pretty` により CLI の JSON serializer を共有するコマンドでインデント付き JSON を出力でき、大きな JSON payload の確認や diff がしやすくなりました。

changelog.d/unreleased/3009.added.md

@@ -0,0 +1,20 @@
+---
+category: added
+issues:
+  - 3009
+affected:
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerMapTests.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+  - USER_GUIDE.md
+---
+
+## English
+
+- **`map`, `inspect`, and `outline` now support compact JSON section caps (#3009)** — `--compact` emits AI-oriented JSON, caps list sections to 5 items by default or the explicit `--limit` / `--top` value, and adds `truncation.sections.*` metadata for bounded payloads.
+
+## 日本語
+
+- **`map`、`inspect`、`outline` が compact JSON section cap に対応しました (#3009)** — `--compact` は AI 向け JSON を出力し、list section を既定 5 件または明示した `--limit` / `--top` 値で cap し、上限付き payload 用の `truncation.sections.*` metadata を追加します。

changelog.d/unreleased/3056.added.md

@@ -0,0 +1,19 @@
+---
+category: added
+issues:
+  - 3056
+affected:
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+  - USER_GUIDE.md
+---
+
+## English
+
+- **`inspect --json` can now select compact evidence fields (#3056)** — `--fields <csv>` emits only requested top-level evidence groups, while `--body-only` is a shortcut for definition bodies without graph context.
+
+## 日本語
+
+- **`inspect --json` が compact evidence field selection に対応しました (#3056)** — `--fields <csv>` は要求した top-level evidence group だけを出力し、`--body-only` は graph context なしで definition body を取得する shortcut として使えます。

src/CodeIndex/Cli/CliFlagSchema.cs

@@ -75,7 +75,7 @@ internal static class CliFlagSchema
     private static readonly string[] LimitCapableCommands =
     [
         "search", "definition", "goto", "references", "callers", "callees", "symbols",
-        "files", "find", "map", "inspect", "deps", "impact", "unused", "hotspots", "validate",
+        "files", "find", "map", "inspect", "outline", "deps", "impact", "unused", "hotspots", "validate",
     ];
 
     private static readonly string[] LangCapableCommands =
@@ -151,6 +151,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[] MaxLineWidthCommands =
     [
@@ -187,6 +188,8 @@ internal static class CliFlagSchema
         "validate", "deps", "impact", "unused", "hotspots", "languages", "db", "report",
     ];
 
+    private static readonly string[] CompactJsonCommands = ["map", "inspect", "outline"];
+
     private static readonly string[] FormatCommands =
     [
         "search", "definition", "references", "callers", "callees", "find", "validate", "deps",
@@ -214,6 +217,8 @@ private static IReadOnlyList<CliFlag> BuildAll()
             new() { Name = "--workspace-db", ValuePlaceholder = "<path>", Description = "Additional workspace member database path for dependency aggregation", Commands = Set(WorkspaceDbCommands) },
             new() { Name = "--data-dir", ValuePlaceholder = "<dir>", Description = "Directory containing codeindex.db; overrides CDIDX_DATA_DIR/XDG/workspace defaults", Commands = Set(DataDirCommands) },
             new() { Name = "--json", Description = "JSON output; search/files/validate also accept --json=array for a single JSON array", Commands = Set(JsonCommands) },
+            new() { Name = "--pretty", Description = "Pretty-print JSON output with indentation", Commands = Set(JsonCommands) },
+            new() { Name = "--compact", Description = "AI-oriented compact JSON with capped list sections and truncation metadata", Commands = Set(CompactJsonCommands) },
             new() { Name = "--format", ValuePlaceholder = "<text|json|count|compact|csv|tsv|lsp|qf|sarif|issue-drafts>", Description = "Standard output format for token budgets, editor integrations, and CI; search recipes also accept issue-drafts", Commands = Set(FormatCommands) },
             new() { Name = "--quiet", ShortName = "-q", Description = "Suppress informational stderr output; errors still print", Commands = Set(AllCommands.ToArray()) },
             new() { Name = "--silent", Description = "Alias for --quiet", Commands = Set(AllCommands.ToArray()) },
@@ -256,6 +261,8 @@ private static IReadOnlyList<CliFlag> BuildAll()
             new() { Name = "--list-recipes", Description = "Search: list built-in audit recipes", Commands = Set("search") },
             new() { Name = "--open-issues", ValuePlaceholder = "<path>", Description = "Search: preflight issue drafts against open issue JSON", Commands = Set("search") },
             new() { Name = "--body", Description = "Include body", Commands = Set(BodyCommands) },
+            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-only", Description = "Inspect: 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") },
             new() { Name = "--exact-name", Description = "Exact symbol-name equality", Commands = Set(ExactNameCommands), AlsoAcceptedBy = Set("search") },