Fix search hints and exact substring highlights

DEVELOPER_GUIDE.md

@@ -1007,7 +1007,7 @@ Exact-match flag compatibility is documented in [USER_GUIDE.md](USER_GUIDE.md#fl
 
 `search`, `definition`, `references`, `callers`, `callees`, `symbols`, and `files` also share path-aware narrowing via `--path`, repeatable `--exclude-path`, and `--exclude-tests`. The read layer ranks source files ahead of tests and docs, and `search` further boosts exact symbol-name and path matches so AI clients are more likely to land on implementation files first.
 
-`search --json` and MCP `search` project full chunks into compact match-centered snippets with `chunk_start_line`, `chunk_end_line`, `snippet_start_line`, `snippet_end_line`, `snippet`, `match_lines`, `highlights`, `context_before`, `context_after`, `truncated_line_count`, `dropped_match_line_count`, and `truncation_context`. `--snippet-lines` caps the snippet length up front (default: 8, max: 20), and `--max-line-width` (CLI) / `maxLineWidth` (MCP) clamps each individual snippet line around the first match token via the shared `LineWidthFormatter.ClampLine` contract used by `find` / `references` / `excerpt` / `inspect` (default: 512, max: 4096) so a single match inside a minified / transpiled / generated single-line file no longer returns hundreds of KB per hit. Clamped lines surface `...(+N)...` markers inside the snippet and expose `truncation_context.char_counts`, `truncation_context.total_chars`, `highlights[].truncated`, `highlights[].original_line_length`, and `highlights[].truncated_char_counts` so AI clients can detect clamping and quantify omitted characters. `highlights[].terms` remains a distinct term list for compatibility; `highlights[].term_occurrences` records every matched occurrence with `term`, 1-based `line`, 1-based `column`, and `length`. `dropped_match_line_count` reports match lines omitted because they fell outside the selected snippet window.
+`search --json` and MCP `search` project full chunks into compact match-centered snippets with `chunk_start_line`, `chunk_end_line`, `snippet_start_line`, `snippet_end_line`, `snippet`, `match_lines`, `highlights`, `context_before`, `context_after`, `truncated_line_count`, `dropped_match_line_count`, and `truncation_context`. `--snippet-lines` caps the snippet length up front (default: 8, max: 20), and `--max-line-width` (CLI) / `maxLineWidth` (MCP) clamps each individual snippet line around the first match token via the shared `LineWidthFormatter.ClampLine` contract used by `find` / `references` / `excerpt` / `inspect` (default: 512, max: 4096) so a single match inside a minified / transpiled / generated single-line file no longer returns hundreds of KB per hit. Clamped lines surface `...(+N)...` markers inside the snippet and expose `truncation_context.char_counts`, `truncation_context.total_chars`, `highlights[].truncated`, `highlights[].original_line_length`, and `highlights[].truncated_char_counts` so AI clients can detect clamping and quantify omitted characters. `highlights[].terms` remains a distinct term list for compatibility; `highlights[].term_occurrences` records every matched occurrence with `term`, 1-based `line`, 1-based `column`, and `length`. Exact substring search also adds `highlights[].literal_terms` and `highlights[].literal_term_occurrences` (camelCase in MCP) so clients can render only the requested literal phrase while preserving the broader diagnostic token list. Non-exact punctuation-heavy code-phrase searches add `exact_substring_hint` to CLI JSON compact results and `recovery_hint` to MCP `search` responses so clients can retry with exact substring semantics when FTS tokenization is likely to hide punctuation. `dropped_match_line_count` reports match lines omitted because they fell outside the selected snippet window.
 
 `excerpt --json` includes `semantic_tokens`, a lightweight range list with 1-based start/end positions, token `type`, and `modifiers`, so IDE and LLM clients can render or post-process excerpt spans without reparsing the raw `content` string.
 
@@ -2619,7 +2619,7 @@ exact-match flag の互換性は [USER_GUIDE.md](USER_GUIDE.md#フラグ互換
 
 `search`、`definition`、`references`、`callers`、`callees`、`symbols`、`files` は `--path`、繰り返し指定できる `--exclude-path`、`--exclude-tests` による絞り込みを共有します。読み取り層は tests や docs より source を優先し、`search` はシンボル名やパスがクエリと正確に一致する候補をさらに上位に出して、AIクライアントが実装ファイルへ早く到達できるようにします。
 
-`search --json` と MCP の `search` は、フルチャンクを `chunk_start_line`、`chunk_end_line`、`snippet_start_line`、`snippet_end_line`、`snippet`、`match_lines`、`highlights`、`context_before`、`context_after`、`truncated_line_count`、`dropped_match_line_count`、`truncation_context` を持つ軽量スニペットへ投影します。`--snippet-lines` で抜粋長を先に制限でき（デフォルト: 8、最大: 20）、`--max-line-width`（CLI）/ `maxLineWidth`（MCP）は `find` / `references` / `excerpt` / `inspect` と同じ共有 `LineWidthFormatter.ClampLine` 契約（デフォルト: 512、最大: 4096、`0` で切り詰め解除）で各スニペット行を最初のマッチトークン周辺にクランプするため、minified / transpiled / 生成された 1 行ファイル内の 1 ヒットで数百 KB を返さなくなります。クランプされた行はスニペットに `...(+N)...` マーカーが入り、`truncation_context.char_counts`、`truncation_context.total_chars`、`highlights[].truncated`、`highlights[].original_line_length`、`highlights[].truncated_char_counts` で AI クライアントがクランプの有無と省略文字数を検出できます。`highlights[].terms` は互換性のため distinct な term list のまま残し、`highlights[].term_occurrences` は一致ごとの `term`、1-based の `line` / `column`、`length` を記録します。`dropped_match_line_count` は選択された snippet window 外に落ちた一致行数を示します。
+`search --json` と MCP の `search` は、フルチャンクを `chunk_start_line`、`chunk_end_line`、`snippet_start_line`、`snippet_end_line`、`snippet`、`match_lines`、`highlights`、`context_before`、`context_after`、`truncated_line_count`、`dropped_match_line_count`、`truncation_context` を持つ軽量スニペットへ投影します。`--snippet-lines` で抜粋長を先に制限でき（デフォルト: 8、最大: 20）、`--max-line-width`（CLI）/ `maxLineWidth`（MCP）は `find` / `references` / `excerpt` / `inspect` と同じ共有 `LineWidthFormatter.ClampLine` 契約（デフォルト: 512、最大: 4096、`0` で切り詰め解除）で各スニペット行を最初のマッチトークン周辺にクランプするため、minified / transpiled / 生成された 1 行ファイル内の 1 ヒットで数百 KB を返さなくなります。クランプされた行はスニペットに `...(+N)...` マーカーが入り、`truncation_context.char_counts`、`truncation_context.total_chars`、`highlights[].truncated`、`highlights[].original_line_length`、`highlights[].truncated_char_counts` で AI クライアントがクランプの有無と省略文字数を検出できます。`highlights[].terms` は互換性のため distinct な term list のまま残し、`highlights[].term_occurrences` は一致ごとの `term`、1-based の `line` / `column`、`length` を記録します。exact substring search では `highlights[].literal_terms` と `highlights[].literal_term_occurrences`（MCP では camelCase）も追加され、広めの診断 token list を残したまま、要求された literal phrase だけを render できます。exact ではない記号の多い code phrase 検索では、FTS tokenization が記号を失いやすい場合に exact substring semantics で再検索できるよう、CLI JSON compact result に `exact_substring_hint`、MCP `search` に `recovery_hint` を追加します。`dropped_match_line_count` は選択された snippet window 外に落ちた一致行数を示します。
 
 `excerpt --json` は 1-based の開始/終了位置、token `type`、`modifiers` を持つ軽量 range list の `semantic_tokens` を返すため、IDE や LLM クライアントは生の `content` 文字列を再パースせずに抜粋範囲を描画・後処理できます。
 

USER_GUIDE.md

@@ -358,6 +358,14 @@ not scheduled for removal before the next major release. If removal is planned,
 the release notes will announce the timeline before the alias stops working.
 MCP mirrors the same split: use `exactSubstring` on `search`, `exactName` on
 name-based tools, and keep `exact` only for backward-compatible clients.
+In `search --json` and MCP `search` responses, exact substring highlights add
+`literal_terms` / `literal_term_occurrences` (camelCase in MCP) so clients can
+render only the requested literal phrase while keeping the broader diagnostic
+`terms` / `term_occurrences` fields.
+When a normal `search` query looks like a punctuation-heavy code phrase,
+text output suggests `--exact-substring`, JSON results include
+`exact_substring_hint`, and MCP `search` includes a `recovery_hint` with
+`exactSubstring: true` arguments.
 
 For single-value CLI flags, repeated occurrences keep the long-standing
 rightmost-wins behavior. `cdidx` prints a warning that names the winning value:
@@ -2452,6 +2460,13 @@ name に対する NFKC + Unicode CaseFold の等価比較です。
 削除する予定はありません。削除する場合は、alias が使えなくなる前に release notes で
 timeline を告知します。MCP も同じ分割を反映します。`search` では `exactSubstring`、
 name-based tools では `exactName` を使い、`exact` は後方互換 client 向けに残します。
+`search --json` と MCP `search` の exact substring highlight には
+`literal_terms` / `literal_term_occurrences`（MCP では camelCase）も追加されるため、
+広めの診断用 `terms` / `term_occurrences` を残したまま、要求した literal phrase だけを
+render できます。
+通常の `search` query が記号の多い code phrase に見える場合、text output は
+`--exact-substring` を提案し、JSON 結果は `exact_substring_hint`、MCP `search` は
+`exactSubstring: true` arguments 付きの `recovery_hint` を返します。
 
 単一値の CLI フラグを複数回指定した場合は、従来どおり右端の指定が採用されます。
 `cdidx` は採用される値を含む警告を出し、最後の CLI 指定がそれ以前の CLI 指定や

changelog.d/unreleased/2813.fixed.md

@@ -0,0 +1,23 @@
+---
+category: fixed
+issues:
+  - 2813
+affected:
+  - src/CodeIndex/Cli/SearchQueryAdvisor.cs
+  - src/CodeIndex/Cli/SearchSnippetFormatter.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - src/CodeIndex/Mcp/McpToolHandlers.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerTests.cs
+  - tests/CodeIndex.Tests/McpServerTests.cs
+  - DEVELOPER_GUIDE.md
+  - USER_GUIDE.md
+---
+
+## English
+
+- **Punctuation-heavy searches now suggest exact substring matching (#2813)** — `search` now hints when a normal FTS query looks like a literal code phrase, including text stderr, CLI JSON `exact_substring_hint`, and MCP `recovery_hint` retry metadata.
+
+## 日本語
+
+- **記号の多い検索で exact substring matching を提案するようになりました (#2813)** — 通常の FTS `search` query が literal code phrase に見える場合、text stderr、CLI JSON の `exact_substring_hint`、MCP の `recovery_hint` retry metadata で案内するようになりました。

changelog.d/unreleased/2820.fixed.md

@@ -0,0 +1,22 @@
+---
+category: fixed
+issues:
+  - 2820
+affected:
+  - src/CodeIndex/Cli/SearchSnippetFormatter.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.cs
+  - src/CodeIndex/Mcp/McpToolHandlers.cs
+  - tests/CodeIndex.Tests/SearchSnippetFormatterTests.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerTests.cs
+  - tests/CodeIndex.Tests/McpServerTests.cs
+  - DEVELOPER_GUIDE.md
+  - USER_GUIDE.md
+---
+
+## English
+
+- **Exact substring highlights expose literal-only terms (#2820)** — `search --json` and MCP `search` now add `literal_terms` / `literal_term_occurrences` for exact substring results so clients can render the requested phrase without also highlighting tokenized punctuation fragments.
+
+## 日本語
+
+- **exact substring highlight が literal-only terms を公開するようになりました (#2820)** — `search --json` と MCP `search` は exact substring 結果に `literal_terms` / `literal_term_occurrences` を追加し、tokenize された記号片まで highlight せずに要求された phrase だけを render できるようになりました。

src/CodeIndex/Cli/JsonOutputContracts.cs

@@ -431,6 +431,7 @@ internal sealed record VersionInfoJsonResult(
 [JsonSerializable(typeof(RepoModuleResult))]
 [JsonSerializable(typeof(ReportBundleSummary))]
 [JsonSerializable(typeof(SearchHighlight))]
+[JsonSerializable(typeof(SearchQueryHint))]
 [JsonSerializable(typeof(SearchResult))]
 [JsonSerializable(typeof(SearchTermOccurrence))]
 [JsonSerializable(typeof(SearchTruncationContext))]