fix(config): consistent index_dir/source_root resolution for CLI and MCP

[HumanBean17]

Problem

A .java-codebase-rag.yml living in a subdirectory of the Java tree (e.g. my-project-context/) resolved its relative paths inconsistently between the CLI (init / increment / reprocess) and the MCP server. No single index_dir value worked for both.

Given the layout:

MyProject/
    my-project-context/.java-codebase-rag.yml   <- cwd
    .java-codebase-rag/                          <- the real index
    microservice-a/ …

Config	init	MCP server
source_root: ../ + index_dir: ../.java-codebase-rag	index lands in ~/ (one level too high)	✅ finds the index
source_root: ../ + index_dir: .java-codebase-rag	✅ finds the index	❌ "index cannot be found"

After this PR, both rows resolve identically and correctly: source_root=MyProject, index_dir=MyProject/.java-codebase-rag.

Root cause

Two compounding bugs in config resolution.

1. index_dir and source_root used different bases (java_codebase_rag/config.py)

source_root resolved relative to the config file's directory (config_dir), but index_dir resolved relative to the already-resolved source_root. So a ../ written in index_dir (intended relative to the config file) was re-applied on top of source_root and overshot by one level → ~/.java-codebase-rag. The docs even contradicted themselves (CONFIGURATION.md said source_root is "relative to the config file's parent directory" but index_dir is "relative to source_root").

Fix: a YAML index_dir now resolves against config_dir — the same base as source_root. CLI/env index_dir and the default ./.java-codebase-rag stay source_root-relative (unchanged), so the common case (config at project root) is unaffected.

2. The MCP server ignored the YAML source_root field (server.py)

main() called resolve_operator_config(source_root=_project_root()), and _project_root() returns the walk-up-discovered config dir (non-None). A non-None source_root routes into the "explicit override" branch that skips the YAML source_root field. The CLI passes source_root=None, which honors the field — so the same config file produced a different effective root for init vs the MCP server.

Fix: main() now passes _source_root_for_operator_config() (JAVA_CODEBASE_RAG_SOURCE_ROOT-or-None). When the env override is unset, the MCP server runs the same walk-up + YAML-source_root-honoring path as the CLI. JAVA_CODEBASE_RAG_SOURCE_ROOT still wins when set. _project_root() is kept for the _resolve_lancedb_uri() fallback only.

Verification

• TDD: wrote failing tests first, watched them fail for the right reason, then implemented.
• Reproduced the original divergence against the real resolve_operator_config before and after the fix; init and MCP now agree.
• tests/test_config.py — 2 new tests (YAML index_dir resolves against config dir, for both ../ and bare forms).
• tests/test_mcp_server_project_root.py — 3 new tests (_source_root_for_operator_config() env-or-None semantics + init/MCP parity regression).
• .venv/bin/ruff check . — clean.
• .venv/bin/python -m pytest tests (no JAVA_CODEBASE_RAG_RUN_HEAVY) — 774 passed, 11 skipped.

User-visible behaviour changes

• A YAML index_dir written relative to the config file now resolves against the config file's directory (previously: against source_root). This is a breaking change for configs where the config file lives in a subdirectory and a relative index_dir was specified — but the old behaviour was already inconsistent between init and MCP, so any such config was already broken for one of the two. The common case (config at project root, or no explicit index_dir) is unchanged.
• The MCP server now honors a YAML source_root field it previously ignored (fixes the init/MCP divergence; also fixes the source_root used for microservice/scope detection).
• Recommended config for a config-in-subdir layout:

  source_root: ../
  index_dir: ../.java-codebase-rag

Scope / impact

• No ontology bump, no embedding change, no re-index required — this only changes path resolution; existing indexes remain valid at their existing locations.
• No env-var contract change. mcp.json.example and the README zero-env-var note remain accurate.
• Skipped a formal propose/active/ doc: this is a bounded 2-file bugfix (plus docs + tests) with the approach pre-approved in the investigation, not a feature/schema change.

🤖 Generated with Claude Code