docs: document index versioning (phase 06) and relationship sidecar (phase 07)

Author: PatrickSys

CHANGELOG.md

@@ -4,6 +4,9 @@
 
 ### Added
 
+- **Index versioning (Phase 06)**: Index artifacts are versioned via `index-meta.json`. Mixed-version indexes are never served; version mismatches or corruption trigger automatic rebuild.
+- **Crash-safe rebuilds (Phase 06)**: Full rebuilds write to `.staging/` and swap atomically only on success. Failed rebuilds don't corrupt the active index.
+- **Relationship sidecar (Phase 07)**: New `relationships.json` artifact containing file import graph, reverse imports, and symbol export index. Updated incrementally alongside the main index.
 - Tree-sitter-backed symbol extraction is now used by the Generic analyzer when available (with safe fallbacks).
 - Expanded language/extension detection to improve indexing coverage (e.g. `.pyi`, `.php`, `.kt`/`.kts`, `.cc`/`.cxx`, `.cs`, `.swift`, `.scala`, `.toml`, `.xml`).
 - New tool: `get_symbol_references` for concrete symbol usage evidence (usageCount + top snippets).

README.md

@@ -207,6 +207,7 @@ The retrieval pipeline is designed around one goal: give the agent the right con
 - **Import centrality** - files that are imported more often rank higher.
 - **Cross-encoder reranking** - a stage-2 reranker triggers only when top scores are ambiguous. CPU-only, bounded to top-K.
 - **Incremental indexing** - only re-indexes files that changed since last run (SHA-256 manifest diffing).
+- **Version gating** - index artifacts are versioned; mismatches trigger automatic rebuild so mixed-version data is never served.
 - **Auto-heal** - if the index corrupts, search triggers a full re-index automatically.
 
 ## Language Support
@@ -239,7 +240,9 @@ Structured filters available: `framework`, `language`, `componentType`, `layer`
 ```
 .codebase-context/
   memory.json         # Team knowledge (should be persisted in git)
+  index-meta.json     # Index metadata and version (generated)
   intelligence.json   # Pattern analysis (generated)
+  relationships.json  # File/symbol relationships (generated)
   index.json          # Keyword index (generated)
   index/              # Vector database (generated)
 ```

docs/capabilities.md

@@ -84,7 +84,10 @@ Output: `{ ready: boolean, reason?: string }`
 
 - Initial: full scan → chunking (50 lines, 0 overlap) → embedding → vector DB (LanceDB) + keyword index (Fuse.js)
 - Incremental: SHA-256 manifest diffing, selective embed/delete, full intelligence regeneration
+- Version gating: `index-meta.json` tracks format version; mismatches trigger automatic rebuild
+- Crash-safe rebuilds: full rebuilds write to `.staging/` and swap atomically only on success
 - Auto-heal: corrupted index triggers automatic full re-index on next search
+- Relationships sidecar: `relationships.json` contains file import graph and symbol export index
 - Storage: `.codebase-context/` directory (memory.json + generated files)
 
 ## Analyzers