diff --git a/USER_GUIDE.md b/USER_GUIDE.md
index 5e38e3abfa..b495bff72b 100644
--- a/USER_GUIDE.md
+++ b/USER_GUIDE.md
@@ -309,6 +309,11 @@ cdidx search authenticate --json          # ndjson stream, one result per line
 cdidx search authenticate --json=array    # single JSON array
 ```
 
+For `cdidx find --count --json`, `files` is the canonical matched-file count.
+The older `file_count` field remains as a deprecated compatibility alias with
+the same value and is not scheduled for removal before the next major release;
+new consumers should read `files`.
+
 ## Editor and index portability
 
 Use `cdidx export ctags` when an editor wants the traditional ctags file format
@@ -3682,6 +3687,11 @@ AIエージェントがDBを直接SQL検索する場合、`sqlite3` CLIが必要
 
 人間向けの出力では、ファイルサイズを2進単位（`KiB`、`MiB`、`GiB` など）で表示します。大きなリポジトリや `map` / `files` の一覧を読み取りやすくするためです。テキスト出力をシェルパイプラインで扱うなど、生のバイト数が必要な場合は `files` または `map` に `--bytes` を指定してください。JSON 出力（`--json`）では、機械処理向けに size フィールドを常に raw integer bytes のまま返します。
 
+`cdidx find --count --json` では、`files` が一致ファイル数の正規フィールドです。
+古い `file_count` フィールドは現在のメジャーリリース中、同じ値を返す非推奨の
+互換エイリアスとして残り、次のメジャーリリースより前に削除される予定は
+ありません。新しい consumer は `files` を読んでください。
+
 `map` の entrypoint 候補は、従来の `score` に加えて `match_type`、`confidence`（0.0..1.0）、`hint_rank` を返します。`match_type` は候補が慣例的なファイルパス、シンボル名、またはその両方に一致したかを示し、`hint_rank` は一致した言語別 hint の 1-based 順位です。`0.8` 以上に近い confidence は path と symbol/name heuristic が一致したことを示し、`0.5` 前後は単一の弱い heuristic、さらに低い値は曖昧な重複名や file-only fallback のような参考候補です。弱い entrypoint を human / JSON 出力から除外するには `cdidx map --min-entrypoint-confidence <0.0..1.0>` を指定してください。
 
 CLI JSON（`--json`）と MCP tool response はどちらも安定した integration surface ですが、wire envelope は同一ではありません。CLI command は `api_version` や command result field など CLI 向けのメタデータを保持し、MCP tool は JSON-RPC tool result と camelCase field name、および MCP 固有のメタデータを返す場合があります。参照行をグループ化する graph tool（`callers`、`callees`、および bundled `analyze_symbol` の caller/callee 行）は、後方互換の scalar summary kind、ソート済み kind array、mixed-kind flag を返します。CLI JSON は `reference_kind` / `reference_kinds` / `has_mixed_reference_kinds`、MCP は `referenceKind` / `referenceKinds` / `hasMixedReferenceKinds` を使います。すべての underlying kind が必要な consumer は、呼び出した surface の array field を読み、将来追加される未知の field は無視してください。CLI/MCP compatibility table は [INTEGRATION_POLICY.md](INTEGRATION_POLICY.md#cli-json-and-mcp-response-compatibility) を参照してください。
diff --git a/changelog.d/unreleased/1423.deprecated.md b/changelog.d/unreleased/1423.deprecated.md
new file mode 100644
index 0000000000..c9cf5900fa
--- /dev/null
+++ b/changelog.d/unreleased/1423.deprecated.md
@@ -0,0 +1,17 @@
+---
+category: deprecated
+issues:
+  - 1423
+affected:
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerTests.cs
+  - USER_GUIDE.md
+---
+
+## English
+
+- **Deprecated `find --count --json` `file_count` alias (#1423)** - `files` is now documented and tested as the canonical matched-file count, while `file_count` remains as a compatibility alias with the same value and is not scheduled for removal before the next major release.
+
+## 日本語
+
+- **`find --count --json` の `file_count` エイリアスを非推奨にしました (#1423)** - `files` を一致ファイル数の正規フィールドとして文書化しテストで固定しました。`file_count` は同じ値を返す互換エイリアスとして残り、次のメジャーリリースより前に削除される予定はありません。
diff --git a/src/CodeIndex/Cli/JsonOutputContracts.cs b/src/CodeIndex/Cli/JsonOutputContracts.cs
index 7361e75a4e..9745644871 100644
--- a/src/CodeIndex/Cli/JsonOutputContracts.cs
+++ b/src/CodeIndex/Cli/JsonOutputContracts.cs
@@ -142,6 +142,7 @@ internal sealed record QueryCountFilesJsonResult(
 internal sealed record QueryFindCountJsonResult(
     [property: JsonPropertyName("count")] int Count,
     [property: JsonPropertyName("files")] int Files,
+    [property: Obsolete("Use the 'files' JSON field. The 'file_count' field is a deprecated compatibility alias for find --count --json.")]
     [property: JsonPropertyName("file_count")] int FileCount);
 
 internal sealed record QueryPathErrorJsonResult(
diff --git a/tests/CodeIndex.Tests/QueryCommandRunnerTests.cs b/tests/CodeIndex.Tests/QueryCommandRunnerTests.cs
index 2df6887174..3ed77b257a 100644
--- a/tests/CodeIndex.Tests/QueryCommandRunnerTests.cs
+++ b/tests/CodeIndex.Tests/QueryCommandRunnerTests.cs
@@ -29319,7 +29319,7 @@ public void RunFind_CountOnlyRegexAndFocusUseSameMatchingSemantics()
     }
 
     [Fact]
-    public void RunFind_CountOnlyJsonIncludesVisibleMatchAndFileCounts()
+    public void RunFind_CountOnlyJsonUsesFilesAsCanonicalCountAndKeepsDeprecatedAlias_Issue1423()
     {
         var projectRoot = TestProjectHelper.CreateTempProject("cdidx_query_runner_find_count");
         try
@@ -29343,6 +29343,7 @@ public void RunFind_CountOnlyJsonIncludesVisibleMatchAndFileCounts()
             Assert.Equal(2, json.GetProperty("count").GetInt32());
             Assert.Equal(1, json.GetProperty("files").GetInt32());
             Assert.Equal(1, json.GetProperty("file_count").GetInt32());
+            Assert.Equal(json.GetProperty("files").GetInt32(), json.GetProperty("file_count").GetInt32());
         }
         finally
         {