Widthdom · Widthdom · May 31, 2026 · May 30, 2026
diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md
@@ -10,6 +10,23 @@ dotnet test
 dotnet run --project src/CodeIndex -- <command> [options]
 ```
 
+CLI help is intentionally layered: `cdidx --help` stays brief, `cdidx --help-all`
+prints the full command/flag/example reference, `cdidx --help-flags` prints only
+shared flag tables, and `cdidx <command> --help` prints one command's usage
+line. Keep new commands visible in the brief summary only when they are a
+primary user workflow; every command must remain present in the full help and
+command-specific usage table.
+
+`cdidx validate` is the user-facing integrity scan for indexed content issues
+such as replacement characters, BOMs, NUL bytes, mixed line endings, UTF-16 BOMs,
+and likely non-UTF8 content. Keep its CLI usage, README entry, and help summary
+in sync when adding validation issue kinds or filters.
+
+Generated shell completion scripts include a comment with the `cdidx` version
+that produced them. When command or flag schema changes, update completion
+tests and keep the README guidance that installed completions should be
+regenerated after upgrades.
+
 The production CLI and NuGet tool packaging target `net8.0`. The test project
 multi-targets `net8.0;net9.0`, and CI runs the test suite on both frameworks
 across Linux, Windows, and macOS. Use a .NET SDK that can restore and run both

diff --git a/README.md b/README.md
@@ -54,6 +54,7 @@ cdidx status --check --json
 cdidx search "handleRequest"
 cdidx definition UserService
 cdidx search "Handle" --project MyApp
+cdidx validate
 cdidx mcp
 ```
 
@@ -81,6 +82,15 @@ Output controls:
 Use `cdidx` when a repository will be searched repeatedly from terminals,
 scripts, CI, or AI tools. Use `rg` when you only need a one-off text scan.
 
+Help discovery:
+
+| Need | Command |
+|---|---|
+| Concise command overview | `cdidx --help` |
+| Full command, flag, and example reference | `cdidx --help-all` or `cdidx --help-extended` |
+| Shared flag reference only | `cdidx --help-flags` |
+| One command's usage line | `cdidx <command> --help` |
+
 Install choice and network notes:
 
 | Need | Use |
@@ -93,13 +103,24 @@ Install choice and network notes:
 See [DISTRIBUTION.md](DISTRIBUTION.md) for the full channel matrix and
 [isolated network install notes](USER_GUIDE.md#isolated-networks-and-proxies).
 
+### Validate
+
+Run `cdidx validate [--db <path>] [--json] [--verbose] [--kind <kind>] [--path <glob>]`
+to report indexed file issues such as replacement characters (`U+FFFD`), BOMs,
+NUL bytes, mixed line endings, UTF-16 BOMs, and likely non-UTF8 content.
+Validation findings are reported in the output and do not by themselves make
+the command fail; the command exits non-zero when the DB cannot be read or the
+command arguments are invalid. Use `--json` for machine-readable issue rows.
+
 ### Shell Completion
 
 Generate completion scripts with `cdidx --completions <bash|zsh|fish|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.
+file completion. Each generated script includes the `cdidx` version that
+produced it; regenerate installed completion scripts after upgrading or
+downgrading `cdidx`.
 
 ## Highlights
 
@@ -271,6 +292,7 @@ cdidx status --check --json
 cdidx search "handleRequest"
 cdidx definition UserService
 cdidx search "Handle" --project MyApp
+cdidx validate
 cdidx mcp
 ```
 
@@ -298,12 +320,31 @@ cdidx mcp
 ターミナル、スクリプト、CI、AI ツールから同じリポジトリを繰り返し検索する
 場合は `cdidx` が向いています。1回限りのテキスト検索には `rg` が向いています。
 
+help の探し方:
+
+| 目的 | コマンド |
+|---|---|
+| 短いコマンド概要 | `cdidx --help` |
+| 全コマンド、flag、例の完全版 | `cdidx --help-all` または `cdidx --help-extended` |
+| 共有 flag だけの一覧 | `cdidx --help-flags` |
+| 1 コマンドの usage 行 | `cdidx <command> --help` |
+
+### Validate
+
+`cdidx validate [--db <path>] [--json] [--verbose] [--kind <kind>] [--path <glob>]`
+は、index 済みファイルの replacement character (`U+FFFD`)、BOM、NUL byte、
+混在改行、UTF-16 BOM、非 UTF-8 らしい内容などを報告します。validation finding は
+出力で報告され、それ自体では command failure になりません。DB を読めない場合や
+引数が不正な場合は non-zero で終了します。機械処理には `--json` を使えます。
+
 ### シェル補完
 
 `cdidx --completions <bash|zsh|fish|powershell>` で補完スクリプトを生成できます。
 生成されたスクリプトは subcommand、flag、よく使う flag 値を補完します。
 `--lang` は対応言語、`--kind` は symbol / reference kind を提示し、`--db`、
 `--path`、`--output` など path 系 option は shell の file completion を使います。
+生成された script には生成元の `cdidx` version が含まれるため、`cdidx` の
+upgrade / downgrade 後はインストール済み補完 script を再生成してください。
 
 ## 特長
 

diff --git a/changelog.d/unreleased/1422.fixed.md b/changelog.d/unreleased/1422.fixed.md
@@ -0,0 +1,16 @@
+---
+category: fixed
+issues:
+  - 1422
+affected:
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+---
+
+## English
+
+- **Per-command usage lines now show `--top` beside `--limit` (#1422)** — query commands that accept the result cap alias now document `[--limit <n>|--top <n>]`, matching the parser and shell-completion schema.
+
+## 日本語
+
+- **各 command の usage 行で `--limit` と並べて `--top` を表示するようになりました (#1422)** — result cap alias を受け付ける query command が `[--limit <n>|--top <n>]` を記載し、parser と shell-completion schema と一致します。
diff --git a/changelog.d/unreleased/1694.docs.md b/changelog.d/unreleased/1694.docs.md
@@ -0,0 +1,17 @@
+---
+category: docs
+issues:
+  - 1694
+affected:
+  - README.md
+  - DEVELOPER_GUIDE.md
+  - src/CodeIndex/Cli/ConsoleUi.cs
+---
+
+## English
+
+- **Documented `cdidx validate` in user-facing help and guides (#1694)** — `validate` now appears in the top-level command summaries, README, and developer guidance so indexed-content validation is discoverable without reading source.
+
+## 日本語
+
+- **`cdidx validate` をユーザー向け help と guide に記載しました (#1694)** — `validate` が top-level command summary、README、developer guidance に表示されるようになり、source を読まなくても indexed content validation を見つけられます。
diff --git a/changelog.d/unreleased/1702.changed.md b/changelog.d/unreleased/1702.changed.md
@@ -0,0 +1,20 @@
+---
+category: changed
+issues:
+  - 1702
+affected:
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - src/CodeIndex/Cli/ProgramRunner.cs
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+  - tests/CodeIndex.Tests/ProgramCliTests.cs
+  - README.md
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **Top-level help is now brief by default (#1702)** — `cdidx --help` prints a concise overview, while `--help-all` / `--help-extended` retain the full reference and `--help-flags` prints only shared flag tables.
+
+## 日本語
+
+- **top-level help の既定表示を短くしました (#1702)** — `cdidx --help` は簡潔な概要を表示し、完全版は `--help-all` / `--help-extended`、共有 flag 一覧は `--help-flags` で確認できます。
diff --git a/changelog.d/unreleased/2013.fixed.md b/changelog.d/unreleased/2013.fixed.md
@@ -0,0 +1,18 @@
+---
+category: fixed
+issues:
+  - 2013
+affected:
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+  - README.md
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **Generated completion scripts now carry the generating `cdidx` version (#2013)** — bash, zsh, fish, and PowerShell completion output includes a version marker and regeneration guidance so stale completions can be audited after upgrades.
+
+## 日本語
+
+- **生成された補完 script に生成元の `cdidx` version を含めるようになりました (#2013)** — bash、zsh、fish、PowerShell の completion output に version marker と再生成案内を含め、upgrade 後に古い補完を確認できます。