fix: restore identifier retrieval and preserve keyword cache data

CHANGELOG.md

@@ -22,6 +22,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Identifier-word retrieval**: Match natural-language terms inside camelCase, PascalCase, and acronym-bearing identifiers in BM25, and preserve word boundaries in lexical definition fallback without colliding with lowercased cache entries. Keep whole-identifier queries distinct from searches for shared identifier words.
+- **Keyword cache upgrades**: Keep older keyword snapshots readable and expose `keyword-index-outdated` through explicit freshness checks. Ordinary indexing refreshes affected active-branch tokenization without regenerating unchanged embeddings; structural caches rebuild from persisted source. Track partially refreshed branch chunks across snapshot reloads. Reject unsupported newer keyword formats without deleting their snapshots or resetting catalog/vector data, including reused structural writers. Validate persisted versions without replacing unsaved keyword state needed after a failed publication.
+- **Hybrid keyword readability**: Keep semantic retrieval available when only optional keyword reads degrade, but expose `keyword-index-unreadable` rather than claiming the index is current. Prevent ordinary coordinated indexing from skipping validation of an unsupported newer keyword format as healthy/current; retain source-freshness and blocking-read safeguards.
+- **Code-request source preference**: Prefer implementation paths when a search explicitly asks for code, while preserving explicit test, documentation, and configuration intent.
+- **Initial module-config watching**: Register startup-discovered local module configuration dependencies as explicit Chokidar targets, preserving transitive alias-graph updates when an initial recursive directory notification is omitted, including when an explicit host configuration path is supplied.
+- **MCP shutdown persistence**: Treat late completion of an already-interrupted operation as a no-op. Prevent cancelled startup diagnostics from scheduling writes after ordered shutdown has drained, including recreation of removed runtime storage.
+- **Startup watcher catch-up**: Request one ordinary coordinated refresh after file/Git subscriptions become ready when automatic indexing is enabled. Recover edits made during initial watcher startup or background-leader promotion without changing watcher-only startup or queuing work after stop.
 - **Consumer-visible evidence correctness**: Count only retained source and graph rows in pre-edit details, close truncated source fences at whole lines, and reserve outer-heading/final-truncation overhead before source fitting. Credit source only when its complete fitted block survives final composition. Allow structural-mode architecture maps to read branch files from SQLite without a vector store. Add native-backed citation, Unicode/CRLF, scope, and token-budget acceptance.
 - **Pre-edit source identity and cancellation**: Resolve canonical native symbol IDs before fitting target source, including large fragmented declarations, instead of accepting ranked body slices, suffix paths, or enclosing declarations. Cap source blocks at 512 tokens, withhold missing source, preserve default host roots, and share the exact lookup with evaluation. Keep selection-hook test references metadata-only and honor cancellation after empty lookups.
 - **Working-tree snapshot integrity**: Detect concurrent database publication even when source hashes and catalog counts are unchanged. Reject lossy UTF-8 Git paths and retain only project-local endpoints for cross-boundary renames.

docs/configuration.md

@@ -309,7 +309,11 @@ Ollama server is stopped. The standard suite uses deterministic HTTP replicas wi
 
 Unlimited depth retains hidden/build/ignored-path exclusions, does not follow symlinks, and keeps file-size and per-directory caps. Compared with older defaults, normal indexing can discover more source files and therefore take more time or use more embedding tokens in hybrid mode. Existing explicit `maxDepth` settings are preserved; set `5` to retain the former depth bound.
 
-When file watching uses Chokidar, an identified Node `watch` registration failure (`EPERM` or `EACCES`) for a readable, selected source file can trigger the existing one-shot polling recovery, just like open-file exhaustion. The error must name an absolute path inside the project, and the file and all its ancestors must remain eligible under the watcher traversal, exclusion, Git-ignore, and protected-path policy. Readiness follows the replacement watcher, with policy-filtered catch-up for changes during replacement. Polling is not the default; unreadable, restricted, unselected, configuration-only, directory, and unidentified or relative error targets do not enable this recovery.
+When file watching uses Chokidar, an identified Node `watch` registration failure (`EPERM` or `EACCES`) for a readable, selected source file or directory, including the project root, can trigger the existing one-shot polling recovery, just like open-file exhaustion. The error must name an absolute path inside the project, and the target and all its ancestors must remain eligible under the watcher traversal, exclusion, Git-ignore, and protected-path policy. Readiness follows the replacement watcher, with policy-filtered catch-up for changes during replacement. Polling is not the default; unreadable, restricted, unselected, configuration-only, and unidentified or relative error targets do not enable this recovery.
+
+Chokidar also receives explicit targets for local module configuration dependencies discovered at startup, including transitive `tsconfig` dependencies. This retains its independent first-change coverage when macOS omits an initial recursive directory notification. Existing selection, exclusion, and protected-path policies still apply; configuration notifications do not broaden which files are indexed.
+
+With automatic indexing enabled, file/Git watcher readiness requests one ordinary coordinated refresh. This catches edits made after the initial scan but before subscriptions became ready, including during background-leader promotion. Existing in-flight indexing coalesces the refresh; unchanged chunks reuse their embeddings. Watcher-only mode (`autoIndex: false`) does not request a startup refresh.
 
 For the disabled-by-default compiler-index pilot, see [Optional SCIP TypeScript enrichment](scip-typescript.md).
 

docs/tools.md

@@ -170,6 +170,12 @@ Do not repeat context calls or broad reads when existing evidence already answer
 
 ## Core retrieval tools
 
+Keyword retrieval recognizes identifier word boundaries: for example, `response` and `payload` can match `readResponsePayload`, while the complete identifier remains searchable. Lexical definition fallback also recognizes camelCase and snake_case name components. Older keyword snapshots need the ordinary refresh described under `index_status` before they gain these matches.
+
+Identifier-word expansion applies to indexed code, not query terms: a whole camelCase query does not match an unrelated identifier merely because they share one component.
+
+Searches that explicitly ask for code prefer implementation paths. Explicit requests for tests, documentation, or configuration still take precedence.
+
 ### `codebase_edit_context`
 
 Use for a known or suspected edit target. `query`, optional `symbol`/`filePath`, caller/callee limits, and a 128–4000-token budget produce target source and direct graph evidence, or a risk-marked conceptual fallback. `filePath` disambiguates the target; it does not restrict related test locations to the implementation directory. Details count only source and graph evidence retained in the response.
@@ -262,8 +268,16 @@ Pass `checkFreshness: true` to compare the selected source/configuration hashes
 
 Catalog presence and provider/model compatibility remain separate from pending storage migrations. An active catalog can be `ready` and compatible while parser, symbol, or call-graph migration markers are outdated. `migrationRequired` and a noncurrent freshness reason recommend ordinary `index_codebase` with `force: false`, not index deletion. Resolve unreadable source/index access before indexing. The CLI equivalents are `ocbi status --check-freshness` and `ocbi status --check-freshness --json` (`cbi` is equivalent). JSON contains the shared status object; MCP adds the diagnostics below, while Pi/omp return the same facts as details. Workspace status remains a bounded catalog inspection with freshness explicitly not checked.
 
+An older keyword snapshot remains readable. With freshness checking, `keyword-index-outdated` means the active branch needs the current identifier-word tokenizer. Run ordinary `index_codebase` or `ocbi index`; unchanged embeddings are reused, without deleting the index or forcing re-embedding. Read-only status checks never rewrite the cache. Other hybrid branches' pending tokenizer state is not counted against the refreshed active branch.
+
+A cache written with a newer, unsupported tokenizer version is not a corrupt cache to reset. Ordinary indexing rejects it without deleting or rewriting its keyword snapshot, catalog, or vectors, including when a long-lived process reuses an existing structural writer. Version validation runs under the mutation lease without replacing the live keyword state needed to retry a failed publication. Use a compatible package version.
+
+If only a hybrid keyword artifact is unreadable, `keyword-index-unreadable` distinguishes degraded retrieval from a healthy, fully current index. With valid vectors and current source/configuration/HEAD, freshness is `{ readable: true, current: false, reason: "keyword-index-unreadable" }` and semantic retrieval remains available. Source changes, incompatible providers, missing vectors, and blocking read failures keep their existing freshness checks and priority. Ordinary coordinated indexing does not skip this degraded state as healthy/current: it repairs recoverable keyword damage or rejects an unsupported newer format without resetting stored data.
+
 MCP responses add `structuredContent.mcpDiagnostics` with schema version `1`. `activeOperations` reports each operation, its current phase, start and last-activity timestamps, and `active` or `suspected_stall` status. The current `index_status` call is excluded. `latestInterruptedOperation` is included only after an ordered shutdown marks an active call or a later local process confirms that the recorded PID is absent. A stale heartbeat alone is never classified as an interruption.
 
+Once ordered shutdown marks an operation interrupted, its late completion does not write diagnostics again or recreate removed runtime storage. The interruption remains available to a subsequent connected session.
+
 ### `index_codebase`
 
 Creates or updates the index. Incremental indexing is the default. Use `force: true` only for a required full rebuild. `estimateOnly` reports estimated embedding work without indexing. `dryRun` parses the real file set and reports the exact embedding token total (files, source chunks, tokens) without requesting embeddings or writing to the index — a read-only preflight.