cov-loupe 3.0.0 → 4.0.0.pre

data/docs/user/MCP_INTEGRATION.md

@@ -1,158 +1,54 @@
 # MCP Integration Guide
 
-[Back to main README](../README.md)
+[Back to main README](../index.md)
+
+> **⚠️ BREAKING CHANGE (v4.0.0+):** The `-m/--mode mcp` flag is now **required** to run cov-loupe as an MCP server. 
+> Automatic mode detection based on TTY/stdin has been removed. If you're upgrading from an earlier version, you **must** update your MCP server configuration to include `-m mcp` or `--mode mcp` or the server will run in CLI mode and hang. See [Migration Guide](migrations/MIGRATING_TO_V4.md) for details.
 
 ## Table of Contents
 
-- [What is MCP?](#what-is-mcp)
-- [Prerequisites](#prerequisites)
-- [Quick Start](#quick-start)
 - [Setup by Client](#setup-by-client)
-- [Available MCP Tools](#available-mcp-tools)
+- [Available MCP Tools](#available-mcp-tools-functions)
 - [Testing Your Setup](#testing-your-setup)
 - [Troubleshooting](#troubleshooting)
 
-## What is MCP?
-
-The Model Context Protocol (MCP) is a standard for integrating tools and data sources with AI assistants. By running cov-loupe as an MCP server, you enable AI coding assistants to:
-
-- Query coverage data for files
-- Identify uncovered code
-- Analyze coverage gaps
-- Suggest improvements based on coverage data
-
-### Why Use MCP with Coverage Tools?
-
-AI assistants can help you:
-- **Prioritize testing** - "Which files need coverage most urgently?"
-- **Understand gaps** - "Why is this file's coverage low?"
-- **Generate tests** - "Write tests for uncovered lines in this file"
-- **Track progress** - "Has coverage improved since last commit?"
-
-## Prerequisites
-
-- **Ruby >= 3.2** (required by MCP gem dependency)
-- **cov-loupe installed** - See [Installation Guide](INSTALLATION.md)
-- **simplecov gem >= 0.21** - Needed when a resultset contains multiple suites (loaded lazily)
-- **Coverage data** - Run tests to generate `coverage/.resultset.json`
-- **MCP-compatible client** - Claude Code, Cursor, Codex, etc.
-
-## Quick Start
-
-### 1. Install cov-loupe
-
-```sh
-gem install cov-loupe
-```
-
-### 2. Verify Installation
-
-```sh
-# Find the executable path (needed for MCP configuration)
-which cov-loupe
-
-# Test it works
-cov-loupe version
-```
-
-### 3. Configure Your AI Assistant
-
-See [Setup by Client](#setup-by-client) below for specific instructions.
-
-### 4. Generate Coverage Data
-
-```sh
-# Run your test suite
-bundle exec rspec  # or your test command
-
-# Verify coverage file exists
-ls coverage/.resultset.json
-```
-
-> **Multi-suite note:** If the resultset contains several suites (e.g., `RSpec` and `Cucumber`), cov-loupe lazily loads the `simplecov` gem and merges them before answering coverage queries. Staleness checks currently use the newest suite’s timestamp, so treat multi-suite freshness warnings as advisory until per-file timestamps are introduced.
->
-> Only suites stored in a *single* `.resultset.json` are merged automatically. If your test runs produce multiple resultset files, merge them (e.g., via `SimpleCov::ResultMerger.merge_and_store`) and point cov-loupe at the combined file.
-
-> Multifile support may be added in a future version (post an issue if you want this).
-
-### 5. Test the MCP Server
-
-```sh
-# Test manually
-echo '''{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}''' | cov-loupe
-```
-
-You should see a JSON-RPC response with version information.
-
 ## Setup by Client
 
-### Claude Code
+For the `mcp add` commands, the executable path comes after the server name. You can optionally pass arguments to the executable after that (e.g., `-- --error-mode debug`).
 
-**Current Status:** Claude Code has a bug in its MCP client that prevents it from working with spec-compliant MCP servers like cov-loupe. Claude Code will automatically fall back to using the CLI interface.
-
-**Bug Report:** [Claude Code Issue #8239](https://github.com/anthropics/claude-code/issues/8239)
-
-**Workaround:** Use the CLI interface, which provides the same functionality:
-```sh
-# Instead of MCP tools, use CLI
-cov-loupe list
-cov-loupe summary lib/cov_loupe/cli.rb
-```
+**Note:** If you change which Ruby version you use, you will need to `bundle install` or `gem install cov-loupe` again with the new version active. Additionally, if your MCP server configuration uses an absolute path, that configuration will need to be updated as well.
 
-**Configuration (for when bug is fixed):**
-
-Using the Claude CLI tool:
+### Claude Code
 
 ```sh
-# Basic setup (if cov-loupe is in default PATH)
-claude mcp add cov-loupe cov-loupe
-
-# With rbenv/asdf (use absolute path)
-claude mcp add cov-loupe /Users/yourname/.rbenv/shims/cov-loupe
+# Add the MCP server; equivalent to ...--scope local...
+claude mcp add cov-loupe cov-loupe -- -m mcp
 
-# With RVM wrapper (recommended for stability)
-rvm wrapper ruby-3.3.8 cov-loupe cov-loupe
-claude mcp add cov-loupe /Users/yourname/.rvm/wrappers/ruby-3.3.8/cov-loupe
+# For user-wide configuration
+claude mcp add --scope user cov-loupe cov-loupe -- -m mcp
 
-# For user-wide configuration (default is local)
-claude mcp add --scope user cov-loupe cov-loupe
-
-# For project-specific configuration
-claude mcp add --scope project cov-loupe cov-loupe
-```
+# For project-specific configuration.
+claude mcp add --scope project cov-loupe cov-loupe -- -m mcp
 
-**Verify configuration:**
-```sh
 # List configured MCP servers
 claude mcp list
 
 # Get server details
 claude mcp get cov-loupe
 
-# Remove if needed
-claude mcp remove cov-loupe
+# Remove if needed (use --scope to match where it was added)
+claude mcp remove cov-loupe                # Removes from local scope (default)
+claude mcp remove --scope user cov-loupe   # Removes from user scope
+claude mcp remove --scope project cov-loupe # Removes from project scope
 ```
 
-**Important Notes:**
-- Default scope is `local` (current project)
-- Use `--scope user` for global config, `--scope project` for project-specific
-- The executable path is tied to Ruby version with version managers
-- If you change Ruby versions, remove and re-add the configuration
-
-### Cursor / Codex
+### Codex
 
 Using the Codex CLI:
 
 ```sh
-# Basic setup (if cov-loupe is in default PATH)
-codex mcp add cov-loupe --command cov-loupe
-
-# With rbenv/asdf (use absolute path)
-codex mcp add cov-loupe --command /Users/yourname/.rbenv/shims/cov-loupe
-
-# With RVM wrapper (recommended for stability)
-rvm wrapper ruby-3.3.8 cov-loupe cov-loupe
-codex mcp add cov-loupe --command /Users/yourname/.rvm/wrappers/ruby-3.3.8/cov-loupe
+# Add the MCP server
+codex mcp add cov-loupe cov-loupe -m mcp
 
 # List configured servers
 codex mcp list
@@ -160,56 +56,45 @@ codex mcp list
 # Show server details
 codex mcp get cov-loupe
 
-# Remove if needed
+# Remove if needed (check codex documentation for scope options if applicable)
 codex mcp remove cov-loupe
 ```
 
-**Find your executable path:**
-```sh
-which cov-loupe
+**Important:** Codex does not pass environment variables like `GEM_HOME`/`GEM_PATH` to MCP servers
+by default. After adding the server, you **must** manually edit `~/.codex/config.toml` to add the 'env_vars' setting:
+
+```toml
+[mcp_servers.cov-loupe]
+command = "cov-loupe"
+args = ["-m", "mcp"]
+env_vars = ["GEM_HOME", "GEM_PATH"]  # Add this line manually
 ```
 
+**Warning:** If you run `codex mcp remove cov-loupe`, the `env_vars` line will be deleted along with the rest of the section.
+You'll need to manually add it back after running `codex mcp add` again.
+To avoid this, consider editing `~/.codex/config.toml` directly instead of using `remove`/`add` commands.
+
 ### Gemini
 
 Using the Gemini CLI:
 
 ```sh
-# Add MCP server
-gemini mcp add cov-loupe /Users/yourname/.rbenv/shims/cov-loupe
-
-# Or with RVM
-gemini mcp add cov-loupe /Users/yourname/.rvm/wrappers/ruby-3.3.8/cov-loupe
+# Add the MCP server
+gemini mcp add cov-loupe cov-loupe -- -m mcp
 
 # List configured servers
 gemini mcp list
 
-# Remove if needed
+# Remove if needed (check gemini documentation for scope options if applicable)
 gemini mcp remove cov-loupe
 ```
 
-### Generic MCP Client
-
-For any MCP client that uses JSON configuration:
-
-```json
-{
-  "mcpServers": {
-    "cov-loupe": {
-      "command": "/path/to/cov-loupe",
-      "args": [],
-      "env": {
-        "COV_LOUPE_OPTS": "--resultset coverage"
-      }
-    }
-  }
-}
-```
 
 **Environment variables you can set:**
 
 - `COV_LOUPE_OPTS` - Default CLI options (though less useful for MCP mode)
 
-## Available MCP Tools
+## Available MCP Tools (Functions)
 
 ### Tool Catalog
 
@@ -221,7 +106,7 @@ cov-loupe exposes 10 MCP tools:
 | `coverage_detailed_tool` | Per-line coverage | `path` |
 | `coverage_raw_tool` | Raw SimpleCov array | `path` |
 | `uncovered_lines_tool` | List uncovered lines | `path` |
-| `all_files_coverage_tool` | Project-wide coverage | `sort_order`, `tracked_globs` |
+| `list_tool` | Project-wide coverage | `sort_order`, `tracked_globs` |
 | `coverage_totals_tool` | Aggregated line totals | `tracked_globs` |
 | `coverage_table_tool` | Formatted coverage table | `sort_order` |
 | `validate_tool` | Validate coverage policies | `code` or `file` |
@@ -236,7 +121,7 @@ For tools that return structured data, `cov-loupe` serializes the data as a JSON
 ```json
 {
   "type": "text",
-  "text": "{"coverage_summary":{"covered":10,"total":20,"percentage":50.0}}"
+  "text": "{\"file\":\"lib/foo.rb\",\"summary\":{\"covered\":10,\"total\":20,\"percentage\":50.0},\"stale\":false}"
 }
 ```
 
@@ -250,15 +135,45 @@ This decision was informed by discussions with multiple AI models. For more deta
 - [Perplexity AI Discussion](https://www.perplexity.ai/search/title-resolving-a-model-contex-IfpFWU1FR5WQXQ8HcQctyg#0)
 - [ChatGPT Discussion](https://chatgpt.com/share/68e4d7e1-cad4-800f-80c2-58b33bfc31cb)
 
+### CLI Options in MCP Mode
+
+When the MCP server starts, you can pass CLI options via the startup command. These options become the default config for MCP tools. **Per-request JSON parameters still win over CLI defaults.**
+
+| CLI Option | Affects MCP Server? | JSON Parameter | Notes |
+|------------|-------------------|----------------|-------|
+| `-R`, `--root` | ✅ Default | `root` | Request param overrides; CLI sets default |
+| `-r`, `--resultset` | ✅ Default | `resultset` | Request param overrides; CLI sets default |
+| `-S`, `--raise-on-stale` | ✅ Default | `raise_on_stale` | Request param overrides; CLI sets default (`false` or `true`) |
+| `-g`, `--tracked-globs` | ✅ Default | `tracked_globs` | Request param overrides; CLI sets default (array) |
+| `--error-mode` | ✅ Yes | `error_mode` | Sets server-wide error handling; can override per tool |
+| `-l`, `--log-file` | ✅ Yes | N/A | Sets server log location (cannot override per tool) |
+| `-f`, `--format` | ❌ No | N/A | CLI-only presentation flag (not used by MCP) |
+| `-o`, `--sort-order` | ❌ No | `sort_order` | CLI flag ignored in MCP; pass per tool call (`\"ascending\"` or `\"descending\"`) |
+| `-s`, `--source` | ❌ No | N/A | CLI-only presentation flag (not used by MCP) |
+| `-c`, `--context-lines` | ❌ No | N/A | CLI-only presentation flag (not used by MCP) |
+| `-C`, `--color BOOLEAN` | ❌ No | N/A | CLI-only presentation flag (not used by MCP) |
+| `-m`, `--mode` | ✅ Required | N/A | **Required for MCP mode:** `-m mcp` or `--mode mcp`. Default: `cli`. |
+
+**Key Takeaways:**
+- **Server-level options** (`--error-mode`, `--log-file`): Set once when server starts, apply to all tool calls
+- **Tool-level options** (`root`, `resultset`, `raise_on_stale`, `tracked_globs`): CLI args provide defaults; per-tool JSON params override when provided
+- **CLI-only options** (`--format`, `--source`, etc.): Not applicable to MCP mode
+
+**Precedence for MCP tool config:** `JSON request param` > `CLI args used to start MCP` (including `COV_LOUPE_OPTS`) > built-in defaults (`root: '.'`, `raise_on_stale: false`, `resultset: nil`, `tracked_globs: []` - no filtering, no tracking).
+
+CLI-only presentation flags (`-f/--format`, `-s/--source`, `-c/--context-lines`, `-C/--color`, and CLI `-o/--sort-order` defaults) never flow into MCP. Pass `sort_order` explicitly in each tool request when you need non-default ordering.
+
+**Data caching:** Coverage data is cached in a global singleton (`ModelDataCache`) and shared across all `CoverageModel` instances. When the resultset file changes (based on file signature and MD5 digest), the cache automatically reloads fresh data. Model instances themselves are lightweight and created fresh for each tool request.
+
 ### Common Parameters
 
-All file-specific tools accept these parameters:
+All file-specific tools accept these parameters in the JSON request:
 
 - `path` (required for file tools) - File path (relative or absolute)
 - `root` (optional) - Project root directory (default: `.`)
-- `resultset` (optional) - Path to the `.resultset.json` file. See [Configuring the Resultset](../README.md#configuring-the-resultset) for details.
-- `staleness` (optional) - Staleness mode: `"off"` (default) or `"error"`
-- `error_mode` (optional) - Error handling: `"off"`, `"log"` (default), `"debug"`
+- `resultset` (optional) - Path to the `.resultset.json` file. See [Configuring the Resultset](../index.md#configuring-the-resultset) for details.
+- `raise_on_stale` (optional) - Raise error on staleness: `false` (default) or `true`
+- `error_mode` (optional) - Error handling: `"off"`, `"log"` (default), `"debug"` (overrides server-level setting)
 
 ### Tool Details
 
@@ -268,46 +183,49 @@ These tools analyze individual files. All require `path` parameter.
 
 **`coverage_summary_tool`** - Covered/total/percentage summary
 ```json
-{"file": "...", "summary": {"covered": 12, "total": 14, "percentage": 85.71}, "stale": false}
+{"file": "...", "summary": {"covered": 12, "total": 14, "percentage": 85.71}, "stale": "ok"}
 ```
 
 **`uncovered_lines_tool`** - List uncovered line numbers
 ```json
-{"file": "...", "uncovered": [5, 9, 12], "summary": {...}, "stale": false}
+{"file": "...", "uncovered": [5, 9, 12], "summary": {...}, "stale": "ok"}
 ```
 
 **`coverage_detailed_tool`** - Per-line hit counts
 ```json
-{"file": "...", "lines": [{"line": 1, "hits": 1, "covered": true}, ...], "summary": {...}, "stale": false}
+{"file": "...", "lines": [{"line": 1, "hits": 1, "covered": true}, ...], "summary": {...}, "stale": "ok"}
 ```
 
 **`coverage_raw_tool`** - Raw SimpleCov lines array
 ```json
-{"file": "...", "lines": [1, 0, null, 5, 2, null, 1], "stale": false}
+{"file": "...", "lines": [1, 0, null, 5, 2, null, 1], "stale": "ok"}
 ```
 
+**Staleness values:** `"ok"` (fresh), `"missing"` (missing), `"newer"` (timestamp), `"length_mismatch"` (length), `"error"` (staleness check error)
+
 #### Project-Wide Tools
 
-**`all_files_coverage_tool`** - Coverage for all files
+**`list_tool`** - Coverage for all files
 - Parameters: `sort_order` (`ascending`|`descending`), `tracked_globs` (array)
-- Returns: `{"files": [...], "counts": {"total": N, "ok": N, "stale": N}}`
+- Returns: `{"files": [...], "counts": {"total": N, "ok": N, "stale": N}, "skipped_files": [...], "missing_tracked_files": [...], "newer_files": [...], "deleted_files": [...], "length_mismatch_files": [...], "unreadable_files": [...], "timestamp_status": "ok|missing"}`
 
 **`coverage_totals_tool`** - Aggregated line totals
-- Parameters: `tracked_globs` (array), `staleness`
-- Returns: `{"lines":{"total":N,"covered":N,"uncovered":N},"percentage":Float,"files":{"total":N,"ok":N,"stale":N}}`
+- Parameters: `tracked_globs` (array), `raise_on_stale`
+- Returns: `{"lines":{"total":N,"covered":N,"uncovered":N,"percent_covered":Float},"tracking":{"enabled":Boolean,"globs":[String]},"files":{"total":N,"with_coverage":{"total":N,"ok":N,"stale":{"total":N,"by_type":{"missing_from_disk":N,"newer":N,"length_mismatch":N,"unreadable":N}}},"without_coverage":{"total":N,"by_type":{"missing_from_coverage":N,"unreadable":N,"skipped":N}}}}`
+- `without_coverage` is only present when tracking is enabled (tracked globs provided).
 
-**`coverage_table_tool`** - Formatted ASCII table
+**`coverage_table_tool`** - Formatted table with box-drawing characters
 - Parameters: `sort_order` (`ascending`|`descending`)
 - Returns: Plain text table
 
 #### Policy Validation Tools
 
 **`validate_tool`** - Validate coverage against custom policies
-- Parameters: Either `code` (Ruby string) OR `file` (path to Ruby file), plus optional `root`, `resultset`, `staleness`, `error_mode`
+- Parameters: Either `code` (Ruby string) OR `file` (path to Ruby file), plus optional `root`, `resultset`, `raise_on_stale`, `error_mode`
 - Returns: `{"result": Boolean}` where `true` means policy passed, `false` means failed
 - Security Warning: Predicates execute as arbitrary Ruby code with full system privileges. Only use predicate files from trusted sources.
 - Examples:
-  - Check if all files have at least 80% coverage: `{"code": "->(m) { m.all_files.all? { |f| f['percentage'] >= 80 } }"}`
+  - Check if all files have at least 80% coverage: `{"code": "->(m) { m.list.all? { |f| f['percentage'] >= 80 } }"}`
   - Run coverage policy from file: `{"file": "coverage_policy.rb"}`
 
 #### Utility Tools
@@ -317,6 +235,8 @@ These tools analyze individual files. All require `path` parameter.
 
 ## Example Prompts for AI Assistants
 
+(Hopefully, your AI agent will not need you to explicilty specify "Using cov-loupe",
+but this is included here because we have seen cases where it does not know to use cov-loupe.)
 ### Coverage Analysis
 
 ```
@@ -344,7 +264,7 @@ Using cov-loupe, find the most important uncovered code in lib/cov_loupe/tools/c
 ### Test Generation
 
 ```
-Using cov-loupe, find uncovered lines in lib/cov_loupe/staleness_checker.rb and write RSpec tests for them.
+Using cov-loupe, find uncovered lines in lib/cov_loupe/staleness_checker.rb and write *meaningful* RSpec tests for them.
 ```
 
 ```
@@ -367,17 +287,23 @@ Using cov-loupe, create a markdown report of:
 Test the MCP server responds to JSON-RPC:
 
 ```sh
-# Test version tool (simplest)
-echo '''{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}''' | cov-loupe
+# Test version tool (simplest, no parameters needed)
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | cov-loupe -m mcp
+
+# Test help tool (no parameters needed)
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"help_tool","arguments":{}}}' | cov-loupe -m mcp
 
-# Test summary tool
-echo '''{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"lib/cov_loupe/model.rb"}}}''' | cov-loupe
+# Test summary tool (use root param if needed)
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"lib/cov_loupe/model.rb","root":"."}}}' | cov-loupe -m mcp
 
-# Test help tool
-echo '''{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"help_tool","arguments":{}}}''' | cov-loupe
+# Test with a project-specific root
+echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"app/models/order.rb","root":"docs/fixtures/demo_project"}}}' | cov-loupe -m mcp
 ```
 
-**Important:** JSON-RPC messages must be on a single line. Multi-line JSON will cause parse errors.
+**Important Notes:**
+- JSON-RPC messages must be on a single line. Multi-line JSON will cause parse errors.
+- CLI flags like `-R` set server defaults, but per-request JSON parameters still win.
+- The `root` parameter is optional and defaults to `.` (current directory).
 
 ### Testing in AI Assistant
 
@@ -412,7 +338,9 @@ tail -f cov_loupe.log
 grep ERROR cov_loupe.log | tail -20
 ```
 
-To override the default log file location, specify the `--log-file` argument wherever and however you configure your MCP server. For example, to log to a different file path, include `--log-file /path/to/logfile.log` in your server configuration. To log to standard error, use `--log-file stderr`.
+To override the default log file location, specify the `--log-file` (or `-l`) argument wherever and however you configure your MCP server. For example, to log to a different file path, include `-l /path/to/logfile.log` in your server configuration. To log to standard error, use `-l stderr`.
+
+**Warning:** Log files may grow unbounded in long-running or CI usage. Consider using a log rotation tool or periodically cleaning up the log file if this is a concern.
 
 **Note:** Logging to `stdout` is not permitted in MCP mode.
 
@@ -420,7 +348,7 @@ To override the default log file location, specify the `--log-file` argument whe
 
 ### CLI Fallback
 
-**Important:** If the MCP server doesn't work, you can use the CLI directly with the `-fJ` flag.
+**Important:** If the MCP server doesn't work, you can use the CLI directly with the `-fJ` (output in JSON format) flag.
 
 See the **[CLI Fallback for LLMs Guide](CLI_FALLBACK_FOR_LLMS.md)** for:
 - Complete command reference and MCP tool mappings
@@ -432,17 +360,11 @@ See the **[CLI Fallback for LLMs Guide](CLI_FALLBACK_FOR_LLMS.md)** for:
 
 **Server Won't Start**
 ```sh
-which cov-loupe                            # Verify executable exists
-ruby -v                                         # Check Ruby >= 3.2
-cov-loupe version                          # Test basic functionality
+which cov-loupe     # Verify executable exists
+ruby -v             # Check Ruby >= 3.2
+cov-loupe version   # Test basic functionality
 ```
 
-**Path Issues with Version Managers**
-```sh
-which cov-loupe                            # Use this absolute path in MCP config
-# RVM: Create wrapper for stability
-rvm wrapper ruby-3.3.8 cov-loupe cov-loupe
-```
 
 **Tools Not Appearing**
 1. Restart AI assistant after config changes
@@ -462,26 +384,15 @@ For troubleshooting, add error mode when configuring the server:
 
 ```sh
 # Claude Code
-claude mcp add cov-loupe cov-loupe --error-mode debug
+claude mcp add cov-loupe cov-loupe -- -m mcp --error-mode debug
 
 # Codex
-codex mcp add cov-loupe --command cov-loupe --args "--error-mode" --args "debug"
+codex mcp add cov-loupe cov-loupe -m mcp --error-mode debug
 
 # Gemini
-gemini mcp add cov-loupe "$(which cov-loupe) --error-mode debug"
+gemini mcp add cov-loupe cov-loupe -- -m mcp --error-mode debug
 ```
 
-### Project-Specific vs. Global Configuration
-
-**Global configuration** (all projects):
-- Claude: `claude mcp add --scope user cov-loupe ...`
-- Codex: `codex mcp add` (uses global config by default)
-- Gemini: `gemini mcp add` (uses global config)
-
-**Project-specific** (one project):
-- Claude: `claude mcp add --scope project cov-loupe ...` (default is `local`)
-- Codex/Gemini: Create `.codex/config.toml` or `.gemini/config.toml` in project root (manual)
-
 ## Next Steps
 
 - **[CLI Fallback for LLMs](CLI_FALLBACK_FOR_LLMS.md)** - Using CLI when MCP isn't available

data/docs/user/README.md

@@ -1,6 +1,8 @@
 # User Documentation
 
-Guides for installing, configuring, and using SimpleCov MCP in day-to-day
+[Back to main README](../index.md)
+
+Guides for installing, configuring, and using cov-loupe in day-to-day
 workflows.
 
 - [Installation](INSTALLATION.md) – environment setup across platforms
@@ -12,3 +14,5 @@ workflows.
 - [CLI Fallback for LLMs](CLI_FALLBACK_FOR_LLMS.md) – when MCP isn't available
 - [Library API](LIBRARY_API.md) – embedding the gem in Ruby code
 - [Troubleshooting](TROUBLESHOOTING.md) – diagnostics for common issues
+- [Migration Guides](migrations/README.md) – breaking change notes for v2 through v4
+- [Prompt Library](prompts/README.md) – copy/paste instructions for MCP clients when you need coverage analyses fast

data/docs/user/TROUBLESHOOTING.md

@@ -1,13 +1,12 @@
 # Troubleshooting Guide
 
-[Back to main README](../README.md)
+[Back to main README](../index.md)
 
 ## Table of Contents
 
 - [Running Issues](#running-issues)
 - [Coverage Data Issues](#coverage-data-issues)
 - [MCP Server Issues](#mcp-server-issues)
-- [Development Issues](#development-issues)
 - [Diagnostic Commands](#diagnostic-commands)
 
 ## Running Issues
@@ -41,28 +40,48 @@ Codex's macOS sandbox forbids `/bin/ps`; RVM shells need it. When you run `bundl
    ```
 2. If your coverage lives elsewhere, point the tools at it:
    ```bash
-   cov-loupe --resultset build/coverage/.resultset.json
+   cov-loupe -r build/coverage/.resultset.json  # -r = --resultset
    # or
-   export COV_LOUPE_OPTS="--resultset build/coverage"
+   export COV_LOUPE_OPTS="-r build/coverage"
    ```
 
 ### Stale Coverage Errors
 
-`--staleness error` (or `staleness: 'error'`) compares file mtimes and line counts to the coverage snapshot. When it fails:
+`--raise-on-stale` (or `-S`, or `raise_on_stale: true`) compares file mtimes and line counts
+to the coverage snapshot and raises if stale. When it fails:
 
 - Regenerate coverage (`bundle exec rspec`) so the snapshot matches current sources.
-- Or drop back to warning-only behaviour using `--staleness off` / `staleness: 'off'`.
+- Or drop back to warning-only behaviour using `--no-raise-on-stale` / `raise_on_stale: false`.
 
-If you only care about a subset of files, supply `--tracked-globs` (CLI) or `tracked_globs:` (API) so new files outside those globs do not trigger staleness.
+If you only care about a subset of files, supply `-g` / `--tracked-globs` (CLI) or `tracked_globs:`
+(API) so new files outside those globs do not trigger staleness.
+
+**Note:** If you see warnings about missing timestamps, time-based staleness checks may be skipped.
+See [Timestamp Warnings](ADVANCED_USAGE.md#timestamp-warnings) for details.
 
 ### "No coverage data found for file"
 
-The model looks up files by absolute path, then cwd-relative path, then basename. If you still hit this error:
+The model looks up files by absolute path, then by relative path (stripping the project root). If you still hit this error:
 
 1. Verify the file is listed in the coverage table (`cov-loupe list | grep model.rb`).
-2. Use the exact project-relative path that SimpleCov recorded (case-sensitive, no symlinks).
+2. Use the exact project-relative path that SimpleCov recorded (no symlinks; case-sensitivity
+depends on your volume - see note below).
 3. If the file truly never executes under tests, add coverage or exclude it from your workflow.
 
+**Note on case-sensitivity:** `cov-loupe` auto-detects volume case-sensitivity at startup. 
+On case-insensitive volumes (most macOS/Windows), `lib/Foo.rb` and `lib/foo.rb` are treated
+as the same file. On case-sensitive volumes (most Linux, some macOS), they are different files.
+
+### SimpleCov path consistency (merged resultsets)
+
+When SimpleCov merges resultsets from multiple suites or environments, it can record the same file
+under different path forms (for example, absolute vs relative, or with different roots). This is a
+SimpleCov output issue, not a cov-loupe issue. Downstream tools will normalize paths and may treat
+one entry as overriding another if two keys map to the same file.
+
+**Recommendation:** Keep `SimpleCov.root` consistent across suites and avoid manual path rewriting
+when merging resultsets.
+
 ## MCP Server Issues
 
 ### MCP Integration Not Working
@@ -89,6 +108,7 @@ The model looks up files by absolute path, then cwd-relative path, then basename
    ```bash
    claude mcp list  # For Claude Code
    codex mcp list   # For Codex
+   gemini mcp list  # For Gemini
    tail -f cov_loupe.log  # Check logs
    ```
 
@@ -107,35 +127,37 @@ The model looks up files by absolute path, then cwd-relative path, then basename
    If MCP still isn't working, you can use the CLI with `-fJ` flag instead.
    See **[CLI Fallback for LLMs](CLI_FALLBACK_FOR_LLMS.md)** for complete guidance.
 
+7. **Check for Codex environment variable issues:**
+   If you are using Codex and the server fails to start due to missing gems, you need to manually add 
+   `env_vars = ["GEM_HOME", "GEM_PATH"]` to your `~/.codex/config.toml`. 
+   See the [MCP Integration - Codex section](MCP_INTEGRATION.md#codex) for complete setup instructions.
+
 ### Path Issues with Version Managers
 
-**Symptom:** Works in terminal but not in MCP client.
+**Symptom:** `cov-loupe` works in terminal but not in MCP client.
 
 **Cause:** MCP client doesn't have your shell environment (PATH, RVM, etc.).
 
 **Solution:** Use absolute paths in MCP configuration:
 
 ```bash
-# For rbenv/asdf
+# For rbenv/asdf - get the full absolute path
 which cov-loupe
-# Use this path in MCP config
+# Example output: /home/username/.rbenv/shims/cov-loupe
+# Use this exact path in your MCP config
 
-# For RVM, create wrapper
+# For RVM you may need to create a wrapper and specify its absolute path
+# (Replace ruby-3.3.8 with your rvm Ruby label) 
 rvm wrapper ruby-3.3.8 cov-loupe cov-loupe
-# Use: ~/.rvm/wrappers/ruby-3.3.8/cov-loupe
-```
-
-## Development Issues
-
-### Test Suite Failures
 
-**Symptom:** `bundle exec rspec` fails with coverage errors.
+# Get the full path (expands ~ to your home directory)
+realpath ~/.rvm/wrappers/ruby-3.3.8/cov-loupe
+# Example output: /home/username/.rvm/wrappers/ruby-3.3.8/cov-loupe
 
-**Common causes:**
-
-1. **Stale coverage data** - Delete `coverage/` directory and re-run
-2. **SimpleCov not loaded** - Check `spec/spec_helper.rb` requires SimpleCov
-3. **Wrong Ruby version** - Verify Ruby >= 3.2
+# Use the FULL path in MCP config (NOT the ~ version):
+# Good: /home/username/.rvm/wrappers/ruby-3.3.8/cov-loupe
+# Bad:  ~/.rvm/wrappers/ruby-3.3.8/cov-loupe  (~ may not expand)
+```
 
 ## Diagnostic Commands
 
@@ -178,8 +200,8 @@ If the above doesn't solve your problem:
    # MCP server logs
    tail -50 cov_loupe.log
 
-   # Or specify custom log location
-   cov-loupe --log-file /tmp/debug.log summary lib/cov_loupe/cli.rb
+   # Or specify custom log location (--log-file or -l)
+   cov-loupe -l /tmp/debug.log summary lib/cov_loupe/cli.rb
    ```
 
 3. **Search existing issues:**