Improve inspect body paging and mode metadata

USER_GUIDE.md

@@ -312,14 +312,21 @@ For AI-oriented bounded payloads, `map`, `inspect`, and `outline` accept
 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`.
+definitions`. When a definition body is longer than the returned slice,
+`body_content_next_start_line` points to the next source line to pass with
+`--body-start`; use `--body-lines` to choose the page size. If a single long
+source line hits the body byte cap, continuation still advances to the following
+source line because body paging is line-based. `inspect --json` also includes
+`body_mode` metadata so clients can see whether body content was requested,
+whether it is present, and which follow-up flags to use.
 
 ```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
+cdidx inspect Compute --body --body-start 40 --body-lines 40
 ```
 
 For `cdidx find --count --json`, `files` is the canonical matched-file count.
@@ -1219,6 +1226,8 @@ same source location.
 | `--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. |
+| `--body-start <line>` | `inspect` | Start the returned definition body slice at a 1-based source line inside the symbol body. Pair with `body_content_next_start_line` from JSON to page a long body. |
+| `--body-lines <n>` | `inspect` | Return at most this many definition body lines for `--body`, `--body-only`, or `--fields body`; maximum 1000. |
 | `--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. |
@@ -2611,14 +2620,19 @@ AI 向けに上限付き payload が必要な場合、`map`、`inspect`、`outli
 `inspect` の証跡をさらに絞りたい場合、`--fields <csv>` は JSON 出力を暗黙に有効化し、
 `definitions`、`file`、`graph`、`references`、`callers`、`callees` などの
 top-level group を選択します。`--body-only` は `--body --fields definitions` の
-shorthand です。
+shorthand です。definition body が返却 slice より長い場合は
+`body_content_next_start_line` が次に `--body-start` へ渡す source line を示します。
+`--body-lines` で page size を指定できます。`inspect --json` には `body_mode`
+metadata も含まれるため、body content が要求済みか、存在するか、次に使う flag が何かを
+client 側で判断できます。
 
 ```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 のみ
+cdidx inspect Compute --body --body-start 40 --body-lines 40
 ```
 
 ## Editor / index portability
@@ -3517,6 +3531,8 @@ raw match density を正確に測る、といった理由で全 raw chunk hit 
 | `--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 なしに実装本文だけが必要な場合に使う。 |
+| `--body-start <line>` | `inspect` | symbol body 内の 1-based source line から definition body slice を返す。長い body の page 送りでは JSON の `body_content_next_start_line` を次の値として渡す。 |
+| `--body-lines <n>` | `inspect` | `--body`、`--body-only`、`--fields body` で返す definition body 行数の上限。最大 1000。 |
 | `--status <all\|submitted\|unsubmitted>` | `suggestions` | ローカル提案履歴を GitHub 送信状態で絞り込みます。 |
 | `--language <lang>` / `--lang <lang>` | `suggestions` | ローカル提案履歴を記録済み対象言語で絞り込みます。 |
 | `--category <category>` | `suggestions` | ローカル提案履歴を提案カテゴリで絞り込みます。 |

changelog.d/unreleased/3394.added.md

@@ -0,0 +1,21 @@
+---
+category: added
+issues:
+  - 3394
+affected:
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Database/DbSymbolReader.cs
+  - src/CodeIndex/Models/QueryResults.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+  - USER_GUIDE.md
+---
+
+## English
+
+- **Inspect can page long definition bodies (#3394)** — `inspect --body` now accepts `--body-start` and `--body-lines`, and JSON definition rows include the returned body slice range plus `body_content_next_start_line` for fetching the next page; byte-capped single-line slices advance to the following source line so clients do not loop.
+
+## 日本語
+
+- **長い定義 body を `inspect` で page 取得できるようになりました (#3394)** — `inspect --body` は `--body-start` と `--body-lines` を受け付け、JSON の definition 行には返却した body slice 範囲と次ページ用の `body_content_next_start_line` が含まれるようになりました。byte cap に当たった単一行 slice でも次の source line へ進むため、client が同じ行で loop しません。

changelog.d/unreleased/3441.changed.md

@@ -0,0 +1,19 @@
+---
+category: changed
+issues:
+  - 3441
+affected:
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerInspectTests.cs
+  - USER_GUIDE.md
+---
+
+## English
+
+- **Inspect now reports body output mode metadata (#3441)** — `inspect --json` includes a `body_mode` block describing whether body content was requested or present, while human `inspect` output prints a body hint when source bodies are omitted.
+
+## 日本語
+
+- **`inspect` が body 出力 mode metadata を返すようになりました (#3441)** — `inspect --json` は body content が要求済みか、存在するかを示す `body_mode` block を含み、人間向け `inspect` 出力では source body が省略されたときに body hint を表示します。

src/CodeIndex/Cli/CliFlagSchema.cs

@@ -281,9 +281,11 @@ private static IReadOnlyList<CliFlag> BuildAll()
             new() { Name = "--status", ValuePlaceholder = "<status>", Description = "Suggestions: filter by suggestion status", Commands = Set("suggestions") },
             new() { Name = "--category", ValuePlaceholder = "<category>", Description = "Suggestions: filter by category", Commands = Set("suggestions") },
             new() { Name = "--agent", ValuePlaceholder = "<agent>", Description = "Suggestions: filter by agent", Commands = Set("suggestions") },
-            new() { Name = "--body", Description = "Include body", Commands = Set(BodyCommands) },
+            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-only", Description = "Inspect: JSON shorthand for --body --fields definitions", 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") },
             new() { Name = "--exact-name", Description = "Exact symbol-name equality", Commands = Set(ExactNameCommands), AlsoAcceptedBy = Set("search") },

src/CodeIndex/Cli/ConsoleUi.cs

@@ -98,7 +98,7 @@ private static readonly (string Command, string Usage)[] CommandUsageLines =
         ("find", "cdidx find <query> --path <glob> [--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] [--pretty] [--compact] [--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] [--pretty] [--compact] [--fields <csv>] [--body-only] [--verbose] [--limit <n>|--top <n>] [--lang <lang>] [--path <glob>] [--exclude-path <glob>] [--exclude-tests] [--body] [--max-line-width <n>] [--exact|--exact-name]"),
+        ("inspect", "cdidx inspect <query>|--query <query>|-- <query> [--db <path>] [--json] [--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]"),
         ("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]"),