Fix shell completion value metadata

DEVELOPER_GUIDE.md

@@ -37,7 +37,7 @@ Development contracts:
 | `cdidx validate` | This 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. |
 | `cdidx doctor` | This is the copy-pasteable environment summary for support requests. Keep it redacted by default: secret-like `CDIDX_*` values must not be printed, and new diagnostic fields should be stable enough for issue triage. Full environment inventory filters (`--env-domain`, `--env-category`, and `--env-sensitivity`) use case-insensitive exact values and compose with AND; filtered JSON summaries describe the returned inventory rather than the global catalog. `--max-json-bytes` is valid only with `--json --env-inventory=full`, counts the serialized UTF-8 document plus its newline, and returns a structured usage error rather than an oversized successful document. The `github` block reports `proxy_default_credentials` as `enabled` / `disabled` and the bounded `max_request_timeout_s`; never print proxy credential material or raw secret values. `license --json` returns the versioned `license`, `commercial_use`, `trademark`, and controlling `documents` contract. |
 | Exception diagnostics | User-facing CLI, JSON, MCP, file-issue, and local diagnostic output must not echo raw `ex.Message` directly. Route exception prose through `CommandErrorWriter.FormatSanitizedExceptionMessage`, `DiagnosticSanitizer.ForMessage`, or an existing bounded `DiagnosticRedactor` helper, and use stable error codes/categories when the message is not needed for recovery. Intentional broad catches should match the `risky-code/broad-exception-catch` taxonomy and normalize to bounded diagnostics, private best-effort suppression, or a documented fallback. |
-| Shell completions | 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. |
+| Shell completions | Generated shell completion scripts include a comment with the `cdidx` version that produced them. Completion candidates come from `CliFlagSchema`: `ValueKind` / `CommandValueKinds` select contextual path, project, repository, language, and symbol-kind behavior; `ValueDomain` / `CommandValueDomains` define exhaustive finite choices; and `SupplementalCompletionValues` preserves real reserved literals for mixed inputs such as path-or-`github`. Display placeholders such as `<name\|path>` are metavariables and must never be parsed into candidates. When command or flag schema changes, update completion tests and keep the README guidance that installed completions should be regenerated after upgrades. |
 | Target frameworks | 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 target frameworks when validating the full CI-equivalent test matrix. |
 | SDK selection | `global.json` pins the repository SDK to `9.0.301` with `rollForward` disabled. CI installs both `8.0.413` and `9.0.301` explicitly: `8.0.413` provides the `net8.0` runtime lane, while `9.0.301` is the selected SDK for restore, build, test, publish, and changelog validation. When rolling SDKs, update `global.json`, every `actions/setup-dotnet` version list, the Docker build image, and this guide together. |
 | GitHub Actions policy | Workflows pin hosted runners to versioned labels (`ubuntu-24.04`, `windows-2022`, `macos-14`), keep the top-level `contents` permission read-only by default, limit `continue-on-error` to failure-path diagnostic artifact upload, give every upload artifact explicit retention, bound every artifact download by pattern and path, and scope cache keys to workflow + runner OS + `packages.lock.json` / `global.json` without broad restore-key fallbacks. `CiWorkflowTests.GitHubActionsWorkflows_FollowRunnerArtifactCacheAndContinueOnErrorPolicy` enforces this checklist. |
@@ -3429,7 +3429,7 @@ net9 CI lane に合わせる場合は `FRAMEWORK=net9.0 make test` を使いま
 | `cdidx validate` | replacement character、BOM、NUL byte、混在改行、UTF-16 BOM、非 UTF-8 らしい内容など、indexed content の問題を user-facing に検査する integrity scan です。validation issue の種別や filter を追加する場合は、CLI usage、README entry、help summary を同期してください。 |
 | `cdidx doctor` | support request 向けにコピーしやすい environment summary です。既定では redacted に保ち、secret 風の `CDIDX_*` 値は出力しないでください。新しい diagnostic field は issue triage に使える程度に安定したものだけにします。full environment inventory の filter（`--env-domain`、`--env-category`、`--env-sensitivity`）は大文字小文字を区別しない完全一致で AND 合成し、filtered JSON summary は global catalog ではなく返却 inventory を表します。`--max-json-bytes` は `--json --env-inventory=full` とだけ組み合わせ、serialize した UTF-8 文書と改行を数え、上限を超える成功文書の代わりに structured usage error を返します。`github` block は `proxy_default_credentials` を `enabled` / `disabled` として出力し、bounded な `max_request_timeout_s` も出します。proxy credential material や raw secret value は出力しないでください。`license --json` は version 付きの `license`、`commercial_use`、`trademark`、controlling `documents` contract を返します。 |
 | 例外診断 | user-facing な CLI / JSON / MCP / file issue / local diagnostic output では raw `ex.Message` を直接 echo しないでください。例外の prose は `CommandErrorWriter.FormatSanitizedExceptionMessage`、`DiagnosticSanitizer.ForMessage`、または既存の bounded な `DiagnosticRedactor` helper を通し、回復に message が不要な場合は安定した error code/category を使ってください。意図的に残す broad catch は `risky-code/broad-exception-catch` taxonomy に沿い、bounded diagnostic、private な best-effort suppression、または documented fallback に正規化してください。 |
-| shell completion | 生成された shell completion script には、生成元の `cdidx` version comment が含まれます。command や flag の schema を変えた場合は completion test を更新し、upgrade 後に installed completion を再生成する README guidance も保ってください。 |
+| shell completion | 生成された shell completion script には、生成元の `cdidx` version comment が含まれます。completion candidate は `CliFlagSchema` を基準にし、`ValueKind` / `CommandValueKinds` が path、project、repository、language、symbol kind の文脈別動作を選び、`ValueDomain` / `CommandValueDomains` は網羅的な有限候補を定義し、`SupplementalCompletionValues` は path または `github` のような混合入力で実在する予約 literal を維持します。`<name\|path>` のような表示用 placeholder は metavariable であり、候補へ分解してはいけません。command や flag の schema を変えた場合は completion test を更新し、upgrade 後に installed completion を再生成する README guidance も保ってください。 |
 | target framework | 製品版 CLI と NuGet tool packaging は `net8.0` を対象にしています。test project は `net8.0;net9.0` の multi-target で、CI は Linux、Windows、macOS の各 lane で両方の framework に対して test suite を実行します。CI 相当の full matrix を検証する場合は、両方の target framework を restore / 実行できる .NET SDK を使ってください。 |
 | SDK selection | `global.json` は repository SDK を `9.0.301` に固定し、`rollForward` を無効化します。CI は `8.0.413` と `9.0.301` を明示的に install します。`8.0.413` は `net8.0` runtime lane を提供し、`9.0.301` は restore、build、test、publish、changelog 検証で選択される SDK です。SDK を更新する場合は、`global.json`、すべての `actions/setup-dotnet` version list、Docker build image、この guide を同じ変更で更新してください。 |
 | GitHub Actions policy | workflow は hosted runner を version 付き label（`ubuntu-24.04`、`windows-2022`、`macos-14`）に固定し、top-level の `contents` permission は既定で read-only に保ちます。`continue-on-error` は failure path の diagnostic artifact upload に限定し、すべての upload artifact に明示的な retention を付け、artifact download は pattern と path で境界を絞ります。cache key は workflow + runner OS + `packages.lock.json` / `global.json` に scope し、広い restore-key fallback は使いません。`CiWorkflowTests.GitHubActionsWorkflows_FollowRunnerArtifactCacheAndContinueOnErrorPolicy` がこの checklist を強制します。 |

USER_GUIDE.md

@@ -181,6 +181,13 @@ Command-specific `--format` values, search origin filters, and `--result-kind`
 values come from the same registry as command help and runtime validation. For
 example, audit completion includes `sarif`, and search completion includes
 `schema_description` and `unknown`.
+Completion behavior uses canonical value-kind metadata rather than display
+metavariables: finite domains are suggested, while free-form placeholders such
+as `<name|path>` remain help text and are never emitted as literal candidates.
+Path/project options use shell file completion where supported; repository and
+free-text options accept user input without invented placeholder choices.
+Mixed options retain real reserved values—for example, `--open-issues` suggests
+`github` alongside file completion without suggesting `path` or `github:owner/name`.
 
 Install the script in the startup file or completion directory for your shell:
 
@@ -3527,6 +3534,13 @@ read-write で mount してください。read-only query container では、fre
 command 固有の `--format` 値、search origin filter、`--result-kind` 値は command
 help と runtime validation と同じ registry から生成されます。たとえば audit の補完には
 `sarif`、search の補完には `schema_description` と `unknown` が含まれます。
+補完動作は表示用 metavariable ではなく canonical な value kind metadata を使います。
+有限 domain の値だけを提示し、`<name|path>` のような自由入力 placeholder は help 表示
+だけに使われ、literal 候補にはなりません。path / project 系 option は対応 shell で
+file completion を使い、repository / free-text option は架空の placeholder 候補を出さずに
+ユーザー入力を受け付けます。混合型 option は実在する予約値を維持し、たとえば
+`--open-issues` は file completion と併せて `github` を提示しますが、`path` や
+`github:owner/name` は literal 候補にしません。
 
 利用中の shell の startup file または completion directory にスクリプトを
 インストールしてください。
@@ -4418,6 +4432,13 @@ completion を使います。
 command 固有の `--format` 値、search origin filter、`--result-kind` 値は command
 help と runtime validation と同じ registry から生成されます。たとえば audit の補完には
 `sarif`、search の補完には `schema_description` と `unknown` が含まれます。
+補完動作は表示用 metavariable ではなく canonical な value kind metadata を使います。
+有限 domain の値だけを提示し、`<name|path>` のような自由入力 placeholder は help 表示
+だけに使われ、literal 候補にはなりません。path / project 系 option は対応 shell で
+file completion を使い、repository / free-text option は架空の placeholder 候補を出さずに
+ユーザー入力を受け付けます。混合型 option は実在する予約値を維持し、たとえば
+`--open-issues` は file completion と併せて `github` を提示しますが、`path` や
+`github:owner/name` は literal 候補にしません。
 
 使っている shell の startup file または completion directory に保存してください:
 

changelog.d/unreleased/4902.fixed.md

@@ -0,0 +1,20 @@
+---
+category: fixed
+issues:
+  - 4902
+affected:
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - src/CodeIndex/Cli/ConsoleCompletionRenderer.cs
+  - tests/CodeIndex.Tests/CliFlagSchemaTests.cs
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+  - USER_GUIDE.md
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **Shell completions no longer offer display metavariables as literal option values (#4902)** — canonical option metadata now separates finite domains, supplemental reserved values, paths, projects, repositories, dynamic language/kind sources, and free text from help placeholders, so Bash, Zsh, Fish, and PowerShell retain real choices such as `github` plus contextual path completion without suggesting literals such as `name` or `path`.
+
+## 日本語
+
+- **shell 補完が表示用 metavariable を literal な option 値として提示しなくなりました (#4902)** — canonical option metadata で有限 domain、補助的な予約値、path、project、repository、動的な language / kind source、自由入力を help placeholder から分離し、Bash、Zsh、Fish、PowerShell は `github` などの実在する候補と文脈に応じた path 補完を維持しながら、`name` や `path` のような literal を候補に出さなくなりました。