Merge origin/main into issue 1781 1785 1826 fixes

Author: Widthdom

DEVELOPER_GUIDE.md

@@ -129,10 +129,109 @@ Query commands that accept path filters (`search`, `definition`, `references`, `
 
 Do not add mutable static caches, shared `StringBuilder` instances, reused `MatchCollection` enumerators, or singleton scanner state to extractor code. If a future extractor needs cross-call memoization, use an explicit thread-safe collection and add a targeted parallel regression test that proves deterministic output under concurrent calls.
 
+### Symbol Kind Taxonomy
+
+`symbols.kind`, `symbols.container_kind`, and `symbol_references.container_kind` use the public symbol kind taxonomy below. New extractors must register new kind values in `SymbolKindCatalog` before writing them so schema checks, writer validation, CLI filters, and downstream JSON consumers stay aligned.
+
+| Kind | Current producers / meaning | Graph behavior |
+|---|---|---|
+| `accessor` | Accessor declarations when extracted separately from their owning property | Search/filter symbol |
+| `annotation` | Annotation declarations or annotation-like language constructs | Metadata/search symbol |
+| `async_function` | JavaScript/TypeScript async function declarations | Callable definition; participates in callers/callees through reference rows |
+| `async_generator` | JavaScript/TypeScript async generator declarations | Callable definition; participates in callers/callees through reference rows |
+| `attribute` | Razor attributes and metadata-like declarations | Context/search symbol; not a call edge by itself |
+| `associatedtype` | Swift associated type declarations | Type-like definition target |
+| `class` | Class declarations across object-oriented languages | Definition target and container |
+| `class_hook` | Python class hook methods such as dunder hooks reclassified from functions | Callable/search symbol |
+| `code` | Markdown fenced or structured code blocks | Search/outline symbol |
+| `constant` | Constant declarations where the language distinguishes them | Search/filter symbol |
+| `delegate` | C# / F# delegate declarations | Callable type definition and container-like target |
+| `enum` | Enum declarations | Definition target and container |
+| `event` | Event declarations | Search/filter symbol |
+| `field` | Field declarations where distinct from properties | Search/filter symbol |
+| `file_module` | File-scoped module/package declarations | Namespace-like context symbol |
+| `function` | Functions, methods, constructors, delegates, tasks, and callable bindings that do not have a narrower kind | Primary callable definition; participates in callers/callees through reference rows |
+| `generator` | JavaScript/TypeScript generator declarations | Callable definition; participates in callers/callees through reference rows |
+| `heading` | Markdown headings | Outline symbol |
+| `hook` | JavaScript/TypeScript React custom hook bindings | Callable-like search/filter symbol |
+| `implements` | Razor `@implements` directives | Context/search symbol |
+| `import` | Imports, using directives, aliases, and package includes | Search/filter symbol |
+| `interface` | Interface declarations | Definition target and container |
+| `lambda` | Named lambda/arrow bindings | Callable definition; participates in callers/callees through reference rows |
+| `layout` | Razor layout directives | Context/search symbol |
+| `method` | Languages or hooks that explicitly distinguish methods from functions | Callable definition; participates in callers/callees through reference rows |
+| `module` | Module declarations | Definition target and container |
+| `namespace` | Namespace declarations | Definition target and container |
+| `operator` | C# operator overload and conversion operator declarations | Callable definition; participates in callers/callees through reference rows |
+| `object` | Object-literal/object container context used by nested extracted symbols | Container context |
+| `package` | Package declarations | Namespace-like context symbol |
+| `property` | Properties and property-like fields | Definition target; not treated as a call edge by itself |
+| `procedure` | Procedure declarations in languages such as Fortran | Callable definition |
+| `program` | Program block declarations in languages such as Fortran | Definition target and container |
+| `protocol` | Protocol declarations in languages that distinguish protocols from interfaces | Definition target and container |
+| `reference` | Secondary extracted symbolic references, such as HTML classes or metadata keys | Search/filter symbol |
+| `rule` | CSS/SCSS rule container context used by nested references | Container context |
+| `route` | Razor route directives | Context/search symbol |
+| `service` | Service declarations in IDL/protobuf-like languages | Definition target and container |
+| `specialization` | C++ template specialization declarations | Definition target for specialized type/function forms |
+| `struct` | Struct declarations | Definition target and container |
+| `submodule` | Fortran submodule declarations | Namespace/module-like definition target |
+| `subroutine` | Fortran subroutine declarations | Callable definition |
+| `test.method` | Test methods detected by test-aware extraction | Callable definition; participates in callers/callees through reference rows |
+| `trait` | Trait declarations in languages that distinguish traits from interfaces | Definition target and container |
+| `type` | Type declarations where a narrower class/interface/struct/enum kind is not available | Definition target |
+| `typealias` | Type alias declarations | Definition target for alias names |
+| `union` | Union declarations | Definition target and container |
+| `block data` | Fortran block data declarations | Definition target |
+| `variable` | Variable bindings | Search/filter symbol |
+
+`symbol_references.reference_kind` uses this separate reference taxonomy:
+
+| Reference kind | Meaning |
+|---|---|
+| `annotation` | Annotation usage in languages that distinguish annotations from attributes |
+| `attribute` | Metadata/attribute usage |
+| `augmentation` | TypeScript declaration/interface merge edge |
+| `call` | Function, method, operator, macro, or command call |
+| `capture` | Captured callback/delegate relationship used by impact analysis |
+| `column_reference` | SQL column reference in a statement-specific context |
+| `consumes_hook` | React hook consumption relationship |
+| `const_assertion` | TypeScript `as const` assertion edge |
+| `const_generic_reference` | Rust const generic argument reference |
+| `copy_from` | Dockerfile `COPY --from=<stage>` stage dependency |
+| `cte_body_reference` | SQL common table expression body reference |
+| `decorator` | Python decorator usage |
+| `extends` | Inheritance or type-extension relationship |
+| `from` | Dockerfile `FROM <stage>` dependency |
+| `friend` | C++ friend declaration relationship |
+| `generic_type_argument` | Generic type argument attached to an explicit invocation |
+| `implement` | Interface implementation relationship |
+| `implicit_implementation` | C# implicit interface implementation relationship |
+| `import` | Import/include/reference through a module system |
+| `instantiate` | Constructor or object creation |
+| `join_condition_reference` | SQL join/merge condition column reference |
+| `lifetime_reference` | Rust/C#-style lifetime or lifetime-like type reference |
+| `metadata` | Metadata-only reference |
+| `reference` | Generic persisted reference row used by fixtures or extractors without a narrower edge kind |
+| `razor_event_binding` | Razor event binding relationship |
+| `stage` | Build-stage relationship |
+| `subscribe` | Event subscription relationship |
+| `type_reference` | Type annotation, generic constraint, or other type-position reference |
+| `unsubscribe` | Event unsubscription relationship |
+| `use` | Generic usage relationship when no narrower reference kind applies |
+
 ### Status freshness age threshold
 
 `status --check` keeps the DB/worktree checksum comparison in `IndexFreshnessChecker`, but the user-facing age hint threshold is resolved in `QueryCommandRunner`: CLI `--stale-after <duration>` wins over `CDIDX_STALE_AFTER`, which wins over `.cdidxrc.json`'s `stale_after`, then the 24-hour default. Supported duration suffixes are `m`, `h`, and `d`. JSON output includes `stale_after_seconds` and `index_age_seconds` only for `--check`, so clients can confirm which threshold was applied without inferring it from text.
 
+### Workspace version pinning
+
+On startup, `cdidx` walks up from the current directory looking for `.cdidx-version`. The first non-empty line is treated as the required CLI version for that workspace. A mismatch prints a warning and continues by default; `--strict-version` or `CDIDX_STRICT_VERSION=1` turns the mismatch into exit code `64` (`EX_USAGE`). This check is advisory and does not rewrite the file. Use it to keep teams on the same binary when index contracts or query behavior differ between releases.
+
+### Release freshness and upgrade checks
+
+`cdidx --check-updates` and `cdidx status --check-updates` query the GitHub latest-release endpoint through `UpdateChecker`, using the same 24-hour cache and `CDIDX_DISABLE_UPDATE_CHECK=1` opt-out as the `--version` hint. `cdidx upgrade --check-only` reuses that check. `cdidx upgrade` is intentionally a thin wrapper around the signed release installer: it downloads `install.sh`, verifies the current binary directory is writable, sets `CDIDX_INSTALL_DIR` to that directory, and runs the installer for the latest release.
+
 ### Degradation reason codes
 
 Readiness degradation reason codes are centralized in `DegradationReasonCodes`. Add new codes there with human text, a recommended action, and an alternative action before emitting them from readers, CLI, or MCP payloads.
@@ -1033,17 +1132,29 @@ lifecycle breadcrumbs to a per-user daily log. The log path follows
 `XDG_CACHE_HOME/cdidx/logs/`, `XDG_RUNTIME_DIR/cdidx/logs/`, then the
 platform default: `%LOCALAPPDATA%\cdidx\logs\` on Windows,
 `~/Library/Logs/cdidx/` on macOS, or `~/.local/state/cdidx/logs/` on Linux.
-The file name is `stderr-YYYYMMDD.log`, and the logger keeps only the newest
-30 daily files. Repository-local development runs from `src/CodeIndex/bin/...`
-and `tests/.../bin/...` are excluded by default so ordinary build/test cycles
-do not accumulate persistent logs. Set `CDIDX_DISABLE_PERSISTENT_LOG=1` to opt
-out entirely; the toggle accepts `1`, `true`, `yes`, or `on`
-case-insensitively. Use `CDIDX_GLOBAL_TOOL_LOG_DIR` to redirect the log
-directory during testing or packaging.
+Each candidate is probed with a create/write/delete round trip before the
+logger commits to it, so read-only state/cache/runtime mounts fall through to
+the next candidate instead of losing the first log write. The file name is
+`stderr-YYYYMMDD.log`, timestamps inside the file are ISO-8601 UTC
+(`yyyy-MM-ddTHH:mm:ss.fffZ`) using invariant culture, and the logger keeps
+only the newest 30 daily files. Repository-local development runs from
+`src/CodeIndex/bin/...` and `tests/.../bin/...` are excluded by default so
+ordinary build/test cycles do not accumulate persistent logs. Set
+`CDIDX_DISABLE_PERSISTENT_LOG=1` to opt out entirely; the toggle accepts `1`,
+`true`, `yes`, or `on` case-insensitively. Use
+`CDIDX_GLOBAL_TOOL_LOG_DIR` to redirect the log directory during testing or
+packaging.
 Set `CDIDX_FORCE_GLOBAL_TOOL_LOG=1` to force lifecycle logging for local
 package smoke tests or launcher diagnostics even when the executable path looks
 like a development build; `CDIDX_DISABLE_PERSISTENT_LOG` still wins when both
 are set.
+Unhandled exceptions keep stderr concise but write the full exception chain and
+stack trace to the lifecycle log for post-mortem diagnostics. Logged command
+arguments are minimally redacted by default: secret-looking `--flag=value`
+pairs, values following secret-looking flags, URI passwords, and long token-like
+hex/base64 strings are replaced with `<redacted>`. `CDIDX_LOG_REDACT=none`
+preserves raw arguments for controlled local debugging, while
+`CDIDX_LOG_REDACT=full` also replaces path-like arguments with a stable hash.
 
 ### The moving parts
 

INTEGRATION_POLICY.md

@@ -82,6 +82,28 @@ CLI payload can be substituted for an MCP payload without adaptation. Additive
 fields may appear on either surface in minor releases; consumers should ignore
 unknown fields and prefer documented fields over positional assumptions.
 
+### JSON and MCP stability contract
+
+CodeIndex follows SemVer for the supported integration surfaces listed above.
+Patch releases may fix incorrect values while preserving documented field names
+and value types. Minor releases may add fields, tools, tool arguments, examples,
+annotations, error `data` members, or enum values when existing consumers can
+ignore them safely. Breaking removals, required-field additions, field renames,
+or incompatible type changes require a major release unless the old shape was
+explicitly documented as preview.
+
+Deprecations are announced in the changelog before removal. Stable fields keep a
+minimum one-major-release compatibility window; preview fields may change in a
+minor release, but the release notes must say so. Tool definitions can expose
+additional metadata such as examples and annotations without changing the
+meaning of existing `inputSchema` entries.
+
+Consumers should branch on documented structural fields, not prose. For MCP
+errors, route on `error.code` and structured `error.data.category` when present;
+do not parse `error.message`, which is diagnostic text and may be clarified in
+minor or patch releases. For CLI automation, route on documented exit codes and
+JSON fields rather than human output.
+
 | Query surface | CLI `--json` shape | MCP response shape | Compatibility notes |
 |---|---|---|---|
 | `search` | One JSON object per result, with CLI query metadata such as `api_version`, `query`, path, line range, snippet, highlights, and truncation details. | Tool result content contains equivalent search-result objects using MCP serialization and tool-call framing. | Result semantics are shared, but the outer envelope and field casing follow the called surface. |

README.md

@@ -118,7 +118,20 @@ file completion.
 | Drift checks | `cdidx diff <db1> <db2>` compares schema, file, symbol, and reference deltas with stable exit codes: `0` identical, `1` drift, `2` schema mismatch, `3` unreadable DB. |
 | Extensibility and feedback | Post-extraction hooks from `~/.config/cdidx/hooks/*.dll` or `CDIDX_HOOKS_DIR` can enrich symbols and references. `cdidx suggestions` lists, inspects, and exports local suggestion history, with fuzzy MCP suggestion deduplication controlled by CLI, env, or `.cdidxrc.json`. |
 | Language coverage | 78 detected languages, with symbol and graph support where available. |
-| Updates | `cdidx --version` checks GitHub releases at most once per day and appends a newer-release hint when one is available. Set `CDIDX_DISABLE_UPDATE_CHECK=1` to suppress the check. |
+| Updates | `cdidx --version` checks GitHub releases at most once per day and appends a newer-release hint when one is available. Use `cdidx --check-updates` or `cdidx status --check-updates` for an explicit freshness check, and `cdidx upgrade` to reinstall the latest GitHub release via `install.sh`. Set `CDIDX_DISABLE_UPDATE_CHECK=1` to suppress checks. |
+
+### Upgrade and uninstall
+
+`cdidx upgrade --check-only` reports whether a newer GitHub release is available. `cdidx upgrade` downloads the current `install.sh`, refuses unwritable install directories, and reruns the installer with `CDIDX_INSTALL_DIR` pointed at the current binary directory.
+
+Direct `install.sh` installs can be removed with:
+
+```bash
+bash ./install.sh --uninstall
+bash ./install.sh --uninstall --purge-cache
+```
+
+The uninstaller removes files placed next to the `cdidx` binary and can optionally remove `~/.cache/cdidx`. It does not remove project `.cdidx/` directories, shell profile PATH edits, shell completion scripts, Homebrew installs, or .NET global-tool installs.
 
 The documented `status --json` trust contract covers these fields:
 

USER_GUIDE.md

@@ -30,7 +30,7 @@ cdidx suggestions list           # Review local AI feedback history
 cdidx mcp                        # Start MCP server for AI tools
 ```
 
-78 languages supported. 24 MCP tools. Incremental updates. Zero config.
+78 languages supported. 24 registered MCP tools. Incremental updates. Zero config.
 
 | Topic | Link |
 |---|---|
@@ -1764,7 +1764,7 @@ OpenAI Codex CLI (`codex.json` or `~/.codex/config.json`):
 
 Once configured, the AI can directly call these tools:
 
-The MCP `tools/list` descriptions include compact English/Japanese usage examples for the primary search and navigation tools, so AI clients can discover valid argument shapes directly from the server response.
+The MCP `tools/list` response includes an `examples` array for every registered tool, so AI clients can discover valid `tools/call` argument shapes directly from the server response.
 
 | Tool | Description |
 |---|---|
@@ -1809,6 +1809,26 @@ Graph-oriented MCP tools such as `references`, `callers`, and `callees` also ret
 
 All MCP tools include `annotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so AI clients can auto-approve safe read-only queries without prompting the user.
 
+#### MCP error responses
+
+MCP JSON-RPC failures use the standard `error` object. Clients should route on
+`error.code` and, when present, `error.data.category`; do not parse
+`error.message`, which is human-facing diagnostic text.
+
+| Code | Meaning | Client action |
+|---|---|---|
+| `-32700` | Parse error or frame too large | Fix the JSON/frame size before retrying |
+| `-32600` | Invalid JSON-RPC request | Fix request shape before retrying |
+| `-32601` | Method not found or disabled tool | Check server version and `tools/list` |
+| `-32602` | Invalid params, unknown tool, or bad protocol version | Fix arguments or negotiate a supported version |
+| `-32603` | Internal error | Surface the failure and inspect server stderr |
+| `-32000` | Rate limited | Retry after the reported delay |
+| `-32001` | Permission denied | Provide the configured auth token |
+| `-32010` | Index missing | Run `cdidx index <projectPath>` first |
+| `-32011` | Index stale/schema mismatch | Rebuild or refresh the index |
+| `-32012` | Index corrupted/unreadable | Rebuild the index from source |
+| `-32015` | Request cancelled | Retry if the client still needs the result |
+
 #### Optional HTTP transport
 
 By default `cdidx mcp` speaks JSON-RPC over stdin/stdout, which is what every config example above uses. AI clients that prefer to keep one warm server running across many requests — instead of paying subprocess-spawn cost per call — can switch the transport to HTTP:

changelog.d/unreleased/1691.fixed.md

@@ -0,0 +1,17 @@
+---
+category: fixed
+issues:
+  - 1691
+affected:
+  - src/CodeIndex/Database/DbContext.cs
+  - src/CodeIndex/Database/DbWriter.cs
+  - tests/CodeIndex.Tests/DatabaseTests.cs
+---
+
+## English
+
+- **Rejected malformed persisted kind values (#1691)** — new schemas add CHECK constraints for symbol/reference kind columns, and writer paths fail fast when extractors try to persist unregistered kind values.
+
+## 日本語
+
+- **不正な kind 値の永続化を拒否するようにしました (#1691)** — 新規 schema が symbol/reference kind 列に CHECK 制約を追加し、extractor が未登録 kind 値を永続化しようとした場合は writer path が早期に失敗します。

changelog.d/unreleased/1700.fixed.md

@@ -0,0 +1,15 @@
+---
+category: fixed
+issues:
+  - 1700
+affected:
+  - tests/CodeIndex.Tests/QueryCommandRunnerTests.cs
+---
+
+## English
+
+- **Out-of-range query numeric flags now fail closed (#1700)** — numeric options such as `--depth 999999999` return usage errors instead of being silently coerced or clamped.
+
+## 日本語
+
+- **範囲外の query 数値フラグを fail-closed にしました (#1700)** — `--depth 999999999` のような数値 option は silent な補正や clamp ではなく usage error を返します。