Widthdom · Widthdom · Jun 18, 2026 · Jun 15, 2026 · Jun 15, 2026 · Jun 15, 2026
diff --git a/README.md b/README.md
@@ -85,6 +85,10 @@ CI checkouts, refresh with `cdidx .`, `--files`, `--commits`, or
 and [incremental update reliability](USER_GUIDE.md#incremental-update-reliability)
 for the full workflow.
 
+For a faster first pass when you only need text search, `definition`, `symbols`,
+or `map`, run `cdidx . --symbols-only`. Reference graph commands remain degraded
+until you rerun `cdidx .` without that flag.
+
 ## Highlights
 
 | Area | What to use |
@@ -255,6 +259,10 @@ cdidx lsp --db .cdidx/codeindex.db
 全体の流れは [ユーザーガイドのクイックスタート](USER_GUIDE.md#クイックスタート) と
 [インクリメンタル更新の信頼性](USER_GUIDE.md#インクリメンタル更新の信頼性) を参照してください。
 
+まず text search、`definition`、`symbols`、`map` だけを速く使いたい場合は
+`cdidx . --symbols-only` を使えます。reference graph 系コマンドは、このフラグなしで
+`cdidx .` を再実行するまで degraded のままです。
+
 ## 特長
 
 | 分野 | 使うもの |

diff --git a/USER_GUIDE.md b/USER_GUIDE.md
@@ -1395,6 +1395,7 @@ same source location.
 | `--duration-format <auto\|seconds\|hms>` | `index` | Choose human elapsed-time display for index summaries. `auto` (default) uses unit labels; `seconds` emits decimal seconds; `hms` keeps `HH:MM:SS`. JSON always keeps raw `elapsed_ms`. |
 | `--max-file-bytes <bytes>` | `index` | Override the per-file indexing limit for this run. Defaults to 4MiB, or `CDIDX_MAX_FILE_BYTES` when set. Values accept raw bytes or `K` / `M` / `G` suffixes such as `50M`. |
 | `--max-symbols-per-file <n>` | `index` | Skip file content, symbols, and references when one file emits too many symbols. Defaults to `5000`; values above `50000` are rejected. |
+| `--symbols-only` | `index` | Full-scan only. Build chunks, symbols, and issues while skipping reference extraction and graph finalization for a faster first pass. `search`, `definition`, `symbols`, and `map` are available; reference graph commands remain degraded until a normal `cdidx index <projectPath>` run. |
 | `--parallelism <n>` | `index` | Set full-scan extraction worker count. Defaults to CPU count capped at 16, or `CDIDX_INDEX_PARALLELISM` when set. SQLite writes stay single-consumer. |
 | `--watch` | `index` | After the initial scan completes, stay running and reindex incrementally as files change (FileSystemWatcher / inotify / FSEvents). Rejects `--commits`, `--changed-between`, `--files`, and `--dry-run` because the loop already drives continuous incremental updates. |
 | `--debounce <ms>` | `index` (watch only) | Coalesce bursts of file events into a single update after `<ms>` of quiet (non-negative integer; default: 500). Invalid values emit a warning and are ignored. |
@@ -3881,6 +3882,7 @@ raw match density を正確に測る、といった理由で全 raw chunk hit
 | `--force` | `index` | 同一 DB に対する index ロックを bypass する。他の `cdidx index` が走っていないと確信できる場合のみ使う。並行実行は schema を破壊し得る。 |
 | `--duration-format <auto\|seconds\|hms>` | `index` | index summary の human 経過時間表示を選ぶ。`auto`（既定）は単位付き、`seconds` は小数秒、`hms` は `HH:MM:SS` を維持。JSON は常に raw の `elapsed_ms` を返す。 |
 | `--max-file-bytes <bytes>` | `index` | この実行で使うファイル単位の索引サイズ上限を上書きする。既定は 4MiB、または `CDIDX_MAX_FILE_BYTES` 設定値。値は raw byte 数、または `50M` のような `K` / `M` / `G` 接尾辞を受け付ける。 |
+| `--symbols-only` | `index` | フルスキャン専用。参照抽出と graph finalization を省き、chunks、symbols、issues だけを作ることで初回利用を速くする。`search`、`definition`、`symbols`、`map` は使えるが、reference graph 系コマンドは通常の `cdidx index <projectPath>` を実行するまで degraded のまま。 |
 | `--parallelism <n>` | `index` | フルスキャンの抽出 worker 数を指定する。既定は CPU 数を最大 16 に丸めた値、または `CDIDX_INDEX_PARALLELISM` 設定値。SQLite 書き込みは単一 consumer のまま。 |
 | `--watch` | `index` | 初回スキャン完了後もプロセスを残し、ファイル変更を検知して差分更新を繰り返す（FileSystemWatcher / inotify / FSEvents）。連続的な差分更新を内蔵しているため `--commits` / `--changed-between` / `--files` / `--dry-run` との併用は拒否する。 |
 | `--debounce <ms>` | `index`（`--watch` 専用） | 一連のイベントを `<ms>` の静止後に 1 つの更新へ集約する（0 以上の整数。既定: 500）。不正な値は警告を出して無視する。 |

diff --git a/changelog.d/unreleased/+csharp-reference-line-state.fixed.md b/changelog.d/unreleased/+csharp-reference-line-state.fixed.md
@@ -0,0 +1,14 @@
+---
+category: fixed
+affected:
+  - src/CodeIndex/Indexer/References/ReferenceExtractor.Preparation.cs
+  - src/CodeIndex/Indexer/References/ReferenceExtractor.TypeReferences.cs
+---
+
+## English
+
+- **C# reference extraction now reuses one line-state scan** — Fresh full indexes avoid a duplicate pass over C# source lines when masking multiline string content and block comments, shaving CPU from first-time `cdidx .` runs.
+
+## 日本語
+
+- **C# reference extraction が 1 回の行状態スキャンを再利用するようになりました** — 初回 `cdidx .` で multiline string content と block comment のマスク用に C# ソース行を二重走査しないようにし、CPU 使用量を削減しました。
diff --git a/changelog.d/unreleased/+fresh-index-reference-refresh.fixed.md b/changelog.d/unreleased/+fresh-index-reference-refresh.fixed.md
@@ -0,0 +1,15 @@
+---
+category: fixed
+affected:
+  - src/CodeIndex/Cli/IndexCommandRunner.FullScan.cs
+  - src/CodeIndex/Database/DbWriter.cs
+  - tests/CodeIndex.Tests/IndexCommandRunnerTests.cs
+---
+
+## English
+
+- **Reduced first-time `cdidx .` indexing time.** Fresh full scans now defer mutual-recursion reference finalization until after bulk reference insertion instead of refreshing it after every file, and skip empty-database cleanup probes that cannot match existing rows.
+
+## 日本語
+
+- **初回の `cdidx .` インデックス時間を短縮しました。** fresh full scan では、相互再帰参照の確定処理をファイルごとではなく参照の一括挿入後にまとめて行い、空DBでは既存行に一致しない cleanup probe も省略します。
diff --git a/changelog.d/unreleased/+head-change-index-skip.fixed.md b/changelog.d/unreleased/+head-change-index-skip.fixed.md
@@ -0,0 +1,14 @@
+---
+category: fixed
+affected:
+  - src/CodeIndex/Cli/IndexCommandRunner.FullScan.cs
+  - tests/CodeIndex.Tests/IndexCommandRunnerTests.cs
+---
+
+## English
+
+- **Reduced `cdidx .` time after a branch or HEAD change.** Default incremental full scans no longer pre-extract every file solely because the stored full-scan HEAD differs from the current worktree HEAD. Unchanged files can now be reused before symbol/reference extraction, while the existing HEAD-change warning, stale-file purge, readiness stamping, and current-HEAD metadata update remain intact.
+
+## 日本語
+
+- **branch / HEAD 変更後の `cdidx .` 時間を短縮しました。** 既定の incremental full scan は、保存済み full-scan HEAD と現在の worktree HEAD が違うという理由だけで全ファイルを先行抽出しなくなりました。既存の HEAD 変更警告、stale file purge、readiness stamp、現在 HEAD metadata 更新は維持しつつ、未変更ファイルを symbol / reference 抽出前に再利用できます。
diff --git a/changelog.d/unreleased/+reference-line-lookup.fixed.md b/changelog.d/unreleased/+reference-line-lookup.fixed.md
@@ -0,0 +1,13 @@
+---
+category: fixed
+affected:
+  - src/CodeIndex/Database/DbWriter.cs
+---
+
+## English
+
+- **Reduced first-time reference indexing work.** Reference-line ID lookups now query only the current insert batch's exact `(file, line, context)` keys instead of rereading every reference line for the file on each batch.
+
+## 日本語
+
+- **初回の reference indexing 処理量を削減しました。** reference line ID の取得時に、各 batch でファイル全体の reference line を読み直さず、現在の insert batch の `(file, line, context)` だけを正確に取得します。
diff --git a/changelog.d/unreleased/+symbols-only-index.added.md b/changelog.d/unreleased/+symbols-only-index.added.md
@@ -0,0 +1,20 @@
+---
+category: added
+affected:
+  - src/CodeIndex/Cli/IndexCommandRunner.FullScan.cs
+  - src/CodeIndex/Cli/IndexCommandRunner.Parse.cs
+  - src/CodeIndex/Cli/IndexCommandRunner.Validation.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - src/CodeIndex/Database/DbWriter.cs
+  - README.md
+  - USER_GUIDE.md
+---
+
+## English
+
+- **Added `cdidx index --symbols-only` for fast first-pass indexing** — full scans can now build chunks, symbols, and issues while skipping reference graph extraction, so search, definition, symbols, and map workflows become usable sooner; graph commands stay degraded until a normal index run.
+
+## 日本語
+
+- **高速な初回 index 向けに `cdidx index --symbols-only` を追加しました** — フルスキャンで chunks、symbols、issues だけを作り、reference graph 抽出を省けるため、search、definition、symbols、map をより早く使い始められます。graph 系コマンドは通常の index 実行まで degraded のままです。
diff --git a/src/CodeIndex/Cli/CliFlagSchema.cs b/src/CodeIndex/Cli/CliFlagSchema.cs
@@ -348,6 +348,7 @@ private static IReadOnlyList<CliFlag> BuildAll()
             new() { Name = "--integrity-check", Description = "Run PRAGMA integrity_check on the database", Commands = Set("db") },
             new() { Name = "--rebuild", Description = "Delete existing DB and rebuild from scratch", Commands = Set("index") },
             new() { Name = "--optimize", Description = "Optimize the existing FTS5 table without scanning files", Commands = Set("index") },
+            new() { Name = "--symbols-only", Description = "Build chunks and symbols while skipping reference graph extraction", Commands = Set("index") },
             new() { Name = "--dry-run", Description = "Preview without writing", Commands = Set("index", "backfill-fold", "vacuum") },
             new() { Name = "--no-checkpoint", Description = "Skip the automatic DB checkpoint before maintenance", Commands = Set("backfill-fold") },
             new() { Name = "--force", Description = "Bypass the per-database index lock", Commands = Set("index") },

diff --git a/src/CodeIndex/Cli/ConsoleUi.cs b/src/CodeIndex/Cli/ConsoleUi.cs
@@ -80,7 +80,7 @@ public static class ConsoleUi
 
     private static readonly (string Command, string Usage)[] CommandUsageLines =
     [
-        ("index", "cdidx index <projectPath> [--db <path>] [--rebuild] [--optimize] [--verbose] [--dry-run] [--force] [--quiet] [--json] [--memory-trace] [--duration-format <auto|seconds|hms>] [--notify <auto|bell|osc9|desktop|none>] [--max-file-bytes <bytes>] [--max-symbols-per-file <n>] [--follow-symlinks <none|internal|all>] [--include-symbol-kind <kind>[,<kind>]] [--exclude-symbol-kind <kind>[,<kind>]] [--watch [--debounce <ms>]]"),
+        ("index", "cdidx index <projectPath> [--db <path>] [--rebuild] [--optimize] [--symbols-only] [--verbose] [--dry-run] [--force] [--quiet] [--json] [--memory-trace] [--duration-format <auto|seconds|hms>] [--notify <auto|bell|osc9|desktop|none>] [--max-file-bytes <bytes>] [--max-symbols-per-file <n>] [--follow-symlinks <none|internal|all>] [--include-symbol-kind <kind>[,<kind>]] [--exclude-symbol-kind <kind>[,<kind>]] [--watch [--debounce <ms>]]"),
         ("hooks", "cdidx hooks <install|uninstall|status> [--project <path>] [--force] [--json]"),
         ("backfill-fold", "cdidx backfill-fold [--db <path>] [--dry-run] [--no-checkpoint] [--json]"),
         ("optimize", "cdidx optimize [--db <path>] [--json]"),
@@ -982,6 +982,7 @@ private static void PrintFlagReference(Action<string> WriteHelpLine)
         Console.WriteLine("  --verbose                  Show per-file status ([OK  ]/[SKIP]/[DEL ]/[ERR ])");
         Console.WriteLine("  --dry-run                  Scan files without writing to the database");
         Console.WriteLine("  --force                    Bypass the per-database index lock; only use when no other cdidx index is active");
+        WriteHelpLine("  --symbols-only             Build chunks and symbols but skip reference extraction; graph queries stay degraded until a normal index run");
         Console.WriteLine("  --json                     Output results as JSON (for AI/machine use)");
         Console.WriteLine("  --memory-trace             Include phase memory samples in index JSON output");
         Console.WriteLine("  --quiet, -q, --silent      Suppress informational stderr output; errors still print (also honors CDIDX_QUIET=1)");