cov-loupe 5.0.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18d4a240f848866ddec4cfc80a37c94b61d9ee92631c3fa017c7624fcb4b12f8
-  data.tar.gz: 6784f32fbb29346efaeec43612a1a5627f663714e59d0eccdec6f87dc18fe9c2
+  metadata.gz: 596b917ef1e78eca9ae6ce05c0d351f963065c0d7506bc74c387548ba51a430a
+  data.tar.gz: 1a85f7fc229c84e578f9ddd7226b88ca2791e352f3b76438ae2120465bcb70a9
 SHA512:
-  metadata.gz: 4b1f607ee6f04b42c9019f8991584ca42108358a5939736fc0e661845d4b3e4d11315426e6259c3d6e8e30e8afabd83884fa8e9e2d2f142420ef844dabf43a74
-  data.tar.gz: 615a1f0dc47439029bf6f577ff32a880dfe758f863a301ccbf0af2823d1f953b8e66655661671597b567f3d61efc373ce4377d42323561d2a9bc06e5d846e299
+  metadata.gz: 8a38acddf9daf5d33d30002ff5392269b69e89dc5b5b3d63fa4823835d546a011326465188f55216dd32f6598c60f8b1e878dbd0ba374c1aa696e91f61ca5b04
+  data.tar.gz: a742933c4722697bea231eb4e7714804dd1cb721c7640b5afef7d22d1800d0a7c38591f3a122911f8a8d1cc5b307eebce91267f7b2e434f7d008570b15292b93

data/AGENTS.md

@@ -9,7 +9,7 @@ This file provides guidance to Codex, Claude Code (claude.ai/code), Gemini CLI,
 computing it from scratch or analyzing the Simplecov-generated .resultset.json file directly.
 - Keep workflow transparent: explain what you did, why it matters, and what the user should consider next.
 - Leave the repository tidy; only touch files that advance the request. If you find 
-other opportunities for improvement along te way, mention them in the form of a prompt the user can use later.
+other opportunities for improvement along the way, mention them in the form of a prompt the user can use later.
 
 ## Running External Commands
 
@@ -27,9 +27,27 @@ Prefer project‑local tools and scripts (for example, bin/ scripts, package.jso
 - Planning tool: skip for trivial chores; otherwise create a multi-step plan and keep it updated as you work (max one `in_progress` step).
 - When moving or renaming tracked files, use `git mv` (or `git mv -k`) instead of plain `mv` so history stays intact.
 
+## Ruby Guidelines
+- Use the project's Ruby version.
+- Prefer `bundle exec` for project tools.
+- Prefer binstubs when present:
+  - `bin/rake`
+  - `bin/rspec`
+  - `bin/rubocop`
+- Before editing, inspect:
+  - `Gemfile`
+  - `Gemfile.lock`
+  - `*.gemspec`
+  - `.rubocop.yml`
+  - `.rspec`
+- Run the smallest relevant test first.
+- Preserve existing Ruby idioms.
+- Do not add gems unless necessary.
+- If `ruby-lsp` is available, prefer symbol-aware analysis over broad file dumping when the tool supports that workflow.
+
 ## Repository Snapshot
 - Ruby gem exposing a SimpleCov coverage CLI (`exe/cov-loupe`) and MCP server; library lives under `lib/cov_loupe/`.
-- Key files: main entry point at `lib/cov_loupe.rb`, core modules in `lib/cov_loupe/` including `cli.rb`, `model.rb`, `mcp_server.rb`, and tool implementations in `lib/cov_loupe/tools/*.rb`.
+- Key files: main entry point at `lib/cov_loupe.rb`, core modules in `lib/cov_loupe/` including `cli.rb`, `model/model.rb`, `mcp_server.rb`, and tool implementations in `lib/cov_loupe/tools/*.rb`.
 - Tests: RSpec under `spec/` with fixtures in `spec/fixtures/`; running tests produces `coverage/.resultset.json` consumed by the tools.
 - Useful commands:
   - `bundle install` – install dependencies
@@ -38,7 +56,7 @@ Prefer project‑local tools and scripts (for example, bin/ scripts, package.jso
   - `cov-loupe list` – table view of coverage data
 
 ## Project Overview
-`cov-loupe` is a Ruby gem that ships both a CLI and an MCP (Model Context Protocol) server for inspecting SimpleCov coverage data. It reads coverage resultsets directly (SimpleCov is only loaded when multi-suite merges are required) and exposes multiple data formats: file summaries, raw line arrays, uncovered lines, per-line detail, and repo-level tables.
+`cov-loupe` is a Ruby gem that ships both a CLI and an MCP (Model Context Protocol) server for inspecting SimpleCov coverage data. It reads coverage resultsets directly (SimpleCov itself is a runtime dependency and is loaded when multi-suite merges are required) and exposes multiple data formats: file summaries, raw line arrays, uncovered lines, per-line detail, and repo-level tables.
 
 ### Key Technologies
 - **Ruby** – implementation language and packaging format (gem).
@@ -50,15 +68,15 @@ Prefer project‑local tools and scripts (for example, bin/ scripts, package.jso
 `CovLoupe.run` operates in either CLI mode (default) or MCP server mode (when `-m mcp` or `--mode mcp` is specified). This dual-mode entry point enables both interactive commands and background tool-serving from the same executable.
 
 ### Core Components
-- `lib/cov_loupe/model.rb` (`CoverageModel`) – core API for querying and shaping coverage data.
+- `lib/cov_loupe/model/model.rb` (`CoverageModel`) – core API for querying and shaping coverage data.
 - `lib/cov_loupe/cli.rb` (`CoverageCLI`) – CLI interface with subcommands like `list`, `summary`, `raw`, and more.
 - `lib/cov_loupe/mcp_server.rb` (`MCPServer`) – JSON-RPC server that exposes tools to MCP clients.
 - `lib/cov_loupe/tools/*.rb` – tool implementations (`file_coverage_summary`, `project_coverage`, etc.).
-- Error handling utilities keep behavior context-aware (friendly CLI output, raised exceptions for libraries, structured MCP responses logged to `./cov_loupe.log`).
+- Error handling utilities keep behavior context-aware: friendly CLI output, raised exceptions for libraries, and `tools/call` results with `isError: true` for MCP argument-validation and tool-execution failures. Protocol- or dispatch-level failures such as unknown tools remain JSON-RPC errors.
 
 ### Coverage Data Flow
 1. Read SimpleCov `.resultset.json` files without needing SimpleCov at runtime (unless merging suites).
-2. Resolve file paths using absolute match, relative path matching, and basename fallback strategies.
+2. Resolve file paths using exact normalized matches and project-root-relative matching.
 3. Provide coverage data in multiple formats: raw arrays, summaries, uncovered lines, per-line details, totals, and formatted tables.
 
 ## Building, Running, and Testing
@@ -94,11 +112,14 @@ Use `bundle exec rspec spec/path_spec.rb` to target specific specs when needed.
   # or
   cov-loupe --help
   ```
-- Exercise the MCP server manually by piping JSON-RPC:
+- Smoke-test the MCP server manually by piping JSON-RPC:
   ```sh
-  echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"file_coverage_summary","arguments":{"path":"lib/cov_loupe/model.rb"}}}' | bundle exec exe/cov-loupe -m mcp
+  echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"file_coverage_summary","arguments":{"path":"lib/cov_loupe/model/model.rb"}}}' | bundle exec exe/cov-loupe -m mcp
   echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"help","arguments":{}}}' | bundle exec exe/cov-loupe -m mcp
   ```
+  These commands confirm that the server launches and responds over stdio; they are not exhaustive
+  contract tests. Optional validation and error sanity checks are documented in
+  [MCP Integration — Error Responses](docs/user/MCP_INTEGRATION.md#error-responses).
 
 ### Building
 ```sh
@@ -124,12 +145,12 @@ The `cov-loupe` executable can be run directly (`bundle exec exe/cov-loupe ...`
 Run `cov-loupe` in MCP mode with `-m mcp`/`--mode mcp`. You can issue JSON-RPC requests over stdio, for example:
 ```
 {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"help","arguments":{}}}
-{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"file_coverage_summary","arguments":{"path":"lib/cov_loupe/model.rb"}}}
+{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"file_coverage_summary","arguments":{"path":"lib/cov_loupe/model/model.rb"}}}
 ```
-All responses are emitted as `type: "text"`; JSON objects are returned as JSON strings in the content payload so MCP clients can parse them easily.
+All responses are emitted as `type: "text"`; JSON objects are returned as JSON strings in the content payload so MCP clients can parse them easily. **Check `result.isError` before parsing content as a successful payload** — `isError: true` means the tool call failed (bad path, invalid predicate, missing required argument, invalid enum, etc.). A top-level JSON-RPC `error` response (instead of a `result`) indicates a protocol- or dispatch-level failure, such as an unknown tool.
 
 ## Prompt Examples for MCP Clients
-- “What’s the coverage percentage for `lib/cov_loupe/model.rb`?” → call `file_coverage_summary`.
+- “What’s the coverage percentage for `lib/cov_loupe/model/model.rb`?” → call `file_coverage_summary`.
 - “Which lines in `spec/fixtures/project1/lib/bar.rb` are uncovered?” → call `file_uncovered_lines`.
 - "Show the repo coverage table sorted worst-first." → call `project_coverage` with `{"sort_order":"ascending"}` (default order highlights highest coverage first, worst at end).
 - “List files with the worst coverage.” → call `project_coverage` (optionally `{"sort_order":"ascending"}`).
@@ -139,24 +160,27 @@ Always prefer these tools over free-form reasoning to keep responses grounded in
 ## MCP Tool Playbook
 - Always select an MCP tool over ad-hoc reasoning for coverage data. Unsure which one fits? Call `help`.
 - Available tools: `file_coverage_summary`, `file_coverage_detailed`, `file_uncovered_lines`, `file_coverage_raw`, `project_coverage`, `project_coverage_totals`, `project_validate`, `help`, and `version`.
-- Responses return deterministic JSON/text; surface the tool output directly unless the user asks for interpretation. Note that `project_coverage` now includes `skipped_files`, `missing_tracked_files`, `newer_files`, and `deleted_files` arrays in its output to report any files that could not be processed due to errors or staleness.
+- Check `result.isError` before parsing tool response content. `isError: false` means the tool succeeded; `isError: true` means the call failed (bad path, invalid predicate, stale coverage, missing required argument, invalid enum, etc.) and the `content` carries a friendly error message. A top-level JSON-RPC `error` object (not a `result`) indicates a protocol- or dispatch-level failure, such as an unknown tool.
+- On success, responses return deterministic JSON/text; surface the tool output directly unless the user asks for interpretation. Note that `project_coverage` now includes `skipped_files`, `missing_tracked_files`, `newer_files`, `deleted_files`, `length_mismatch_files`, and `unreadable_files` arrays in its output to report any files that could not be processed due to errors or staleness.
 
 ## Development Conventions
 - Target Ruby >= 3.2; use two-space indentation and `# frozen_string_literal: true` in Ruby files.
-- Match existing style and patterns (see `CoverageModel` and `CovUtil` helpers). Comments should clarify non-obvious logic only.
+- Match existing style and patterns (see `CoverageModel` and `CoverageCalculator` helpers). Comments should clarify non-obvious logic only.
 - Never undo or overwrite user changes outside your scope; integrate with them instead. However, if the new changes would be better implemented by modifying other sections, e.g., extracting now-duplicated behavior into a special method, then do that.
 - When adding behavior, couple it with tests; keep or raise coverage. Specs belong in `spec/**/*_spec.rb` mirroring the lib path.
 - Validate meaningful changes with `bundle exec rspec` when feasible; note skipped verification in your summary if you cannot run it.
-- The codebase follows standard Ruby conventions and emphasizes user-friendly CLI output, structured MCP responses, and rich error handling.
+- The codebase follows standard Ruby conventions and emphasizes user-friendly CLI output, `isError: true` results for MCP argument-validation and tool-execution failures, JSON-RPC errors for protocol- or dispatch-level failures, and rich error handling.
 
 ### Error Handling Strategy
 - **CLI mode** – render user-friendly messages, respect exit codes, and support optional debug output.
 - **Library mode** – raise custom exceptions for programmatic handling.
-- **MCP server mode** – return structured error responses and log context to `./cov_loupe.log`.
+- **MCP server mode** – return `tools/call` results with `isError: true` for failed calls, including argument-validation and tool-execution failures; reserve JSON-RPC errors for protocol- or dispatch-level failures such as unknown tools, and log execution-error context to `./cov_loupe.log`.
 
 ### Path Resolution Strategy
-1. Attempt exact absolute path matches within the coverage data.
-2. Retry using paths without the working-directory prefix.
+1. Attempt exact normalized path matches within the coverage data.
+2. Retry using paths without the project-root prefix.
+
+On case-insensitive volumes, comparisons are case-normalized; on case-sensitive volumes, case must match exactly.
 
 ### Resultset Discovery
 - The tool locates `.resultset.json` by checking default paths or by honoring explicit CLI/MCP arguments. See [Configuring the Resultset](README.md#configuring-the-resultset) for details.
@@ -179,7 +203,7 @@ Always prefer these tools over free-form reasoning to keep responses grounded in
 
 ## Response Expectations
 - Be concise and collaborative. Lead with the change/insight; follow with necessary detail.
-- Reference files with inline clickable paths (e.g., `lib/cov_loupe/model.rb:42`). Avoid ranges and external URIs.
+- Reference files with inline clickable paths (e.g., `lib/cov_loupe/model/model.rb:42`). Avoid ranges and external URIs.
 - When providing content intended for the user to copy and paste (like commit messages or configuration snippets), do not include line numbers or any other decorators that would interfere with direct usage.
 - Summaries use plain bullets (`-`). Offer next steps only when they flow naturally (tests, commits, builds, validation).
 - Do not dump entire files; mention paths. Keep tone factual, note open questions, and highlight testing gaps.
@@ -216,7 +240,7 @@ Read-only file system @ rb_sysopen
 bundle exec rubocop --cache false
 ```
 
-This disables caching and adds approximately 5 seconds to execution time (3s → 8s) but ensures successful analysis in sandboxed environments. See [dev/prompts/ai-code-evaluator-guidelines.md](dev/prompts/ai-code-evaluator-guidelines.md) for details on why caching is enabled by default.
+This disables caching and adds approximately 5 seconds to execution time (3s → 8s) but ensures successful analysis in sandboxed environments. See [dev/prompts/guidelines/ai-code-evaluator-guidelines.md](dev/prompts/guidelines/ai-code-evaluator-guidelines.md) for details on why caching is enabled by default.
 
 ## Documentation
 - `README.md` – primary documentation for installation, CLI usage, MCP integration, troubleshooting, and resultset configuration.
@@ -230,4 +254,4 @@ Migration documentation must accurately reflect the state of the project at the
 - Require files via `cov_loupe` paths.
 - Ensure API paths work with both absolute and relative inputs.
 - The executable name is `cov-loupe` (hyphenated).
-- Keep CLI error messages user-friendly and MCP responses structured.
+- Keep CLI error messages user-friendly, MCP argument-validation and tool-execution failures flagged with `isError: true`, and protocol- or dispatch-level failures represented as JSON-RPC errors.

data/CONTRIBUTING.md

@@ -2,101 +2,133 @@
 
 [Back to main README](docs/index.md)
 
-Thank you for your interest in contributing! 
-This project welcomes bug reports, improvements, and suggestions that make it more useful and reliable for the Ruby community.
+Thank you for your interest in contributing.
+
+Bug reports, feature proposals, documentation suggestions, and other feedback are welcome.
 
 ---
 
-## How to Contribute
+## Before Submitting a Pull Request
+
+Please do not submit a pull request unless you have first opened an issue and received explicit approval from the maintainer to proceed.
+
+Discussing a proposal in an issue does not by itself constitute approval. Please wait until the maintainer specifically confirms that a pull request would be welcome.
+
+This project is maintained by a single developer. Even a well-intentioned and technically sound pull request can require substantial review, testing, discussion, and ongoing maintenance. A proposed change may also conflict with the project's scope, design, priorities, or planned work.
+
+The contribution process is:
+
+1. Open an issue describing the problem or proposed improvement.
+2. Discuss the desired behavior and, when useful, the likely implementation.
+3. Wait for explicit approval to prepare a pull request.
+4. Submit a pull request only after receiving that approval.
+
+Pull requests submitted without prior approval may be closed without detailed review.
+
+### AI-Assisted Contributions
+
+AI-assisted work is welcomed. The same prior-approval requirement applies whether the work is produced manually or with AI assistance.
+
+Contributors are responsible for supervising and validating their work. A pull request should not shift the primary burden of reviewing, debugging, or establishing correctness to the maintainer.
+
+---
+
+## Reporting Issues
+
+Before opening an issue:
+
+- Check whether an existing issue already addresses the subject.
+- Include clear reproduction steps when reporting a problem.
+- Describe the expected and actual behavior.
+- Include your Ruby version (`ruby -v`), operating system, and any other relevant environment information.
+- Keep discussion technical and respectful. See the [Code of Conduct](docs/code_of_conduct.md).
+
+---
+
+## Preparing an Approved Change
+
+After receiving explicit approval to submit a pull request:
 
-### 1. Reporting Issues
-- Check existing issues before opening a new one.  
-- Include clear reproduction steps, expected vs. actual results, and your Ruby version (`ruby -v`) and OS.  
-- Keep discussion technical and respectful — see the [Code of Conduct](docs/code_of_conduct.md).
+1. Fork the repository on GitHub.
+2. Create a branch for your work:
 
-### 2. Submitting Changes
-1. **Fork** the repository on GitHub.  
-1. **Create a branch** for your work:  
    ```bash
    git checkout -b feature/my-change
    ```
-1. **Install dependencies**:  
+
+3. Install dependencies:
+
    ```bash
    bundle install
    ```
-1. Make your changes, conforming to the project's coding style.
-1. **Run tests** to verify your changes:  
+
+4. Make your changes, following the project's existing coding style.
+5. Run the tests:
+
    ```bash
    bundle exec rspec
    ```
-1. **Lint the code**:  
+
+6. Run RuboCop:
+
    ```bash
    bundle exec rubocop
    ```
-1. Commit changes with clear, concise messages following conventional commit style (e.g. `fix: handle missing file gracefully`).
-1. **Push** your branch and open a **Pull Request** against `main`.
 
-PRs should:
-- Include or update tests for new/changed behavior.  
-- Pass all existing tests and RuboCop checks.  
-- Update documentation or README examples if behavior changes.
+7. Commit the changes with a clear, informative message.
+8. Push the branch and open a pull request against `main`.
+
+Pull requests should:
+
+- Link to the issue in which the change was approved.
+- Include or update tests for new or changed behavior.
+- Pass all existing tests and RuboCop checks.
+- Update documentation and examples when behavior changes.
+- Explain how the change was tested and validated.
 
 ---
 
 ## Development Setup
 
-This project requires Ruby >= 3.2 (due to the `mcp` gem dependency). Typical workflow:
+This project requires Ruby 3.2 or later because of the `mcp` gem dependency.
+
+A typical setup is:
 
 ```bash
 git clone https://github.com/keithrbennett/cov-loupe.git
 cd cov-loupe
 bundle install
-rspec
+bundle exec rspec
 ```
 
-Optional tools:
-- `rake` as an alternate way to run `rspec` and `rubocop`
-- `exe/cov-loupe` the CLI and MCP entry point, use for end-to-end runs
+Useful commands and entry points include:
+
+- `bundle exec rspec` — run the test suite
+- `bundle exec rubocop` — run static analysis and style checks
+- `bundle exec rake` — run the default Rake tasks
+- `exe/cov-loupe` — run the CLI or MCP entry point for end-to-end testing
 
 ---
 
 ## Documentation
 
-This project uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) to build and serve documentation.
+This project uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) to build and serve its documentation.
+
+To run the documentation locally:
 
-**Quick start:**
 ```bash
 pip3 install -r requirements.txt
-mkdocs serve  # View at http://127.0.0.1:8000
+mkdocs serve
 ```
 
-For detailed platform-specific installation instructions (macOS, Linux, Windows) and troubleshooting, see the [Documentation Development](docs/dev/DEVELOPMENT.md#documentation-development) section of the Development Guide
-
----
+The documentation will be available at <http://127.0.0.1:8000>.
 
-## Release Process (maintainer only)
+For detailed platform-specific installation instructions and troubleshooting, see [Documentation Development](docs/dev/DEVELOPMENT.md#documentation-development).
 
-1. Update version in `lib/cov_loupe/version.rb`
-2. Update `RELEASE_NOTES.md`
-3. Commit, tag, and push:
-   ```bash
-   git add -A
-   git commit -m "Bump version to 1.0.0, update release notes"
-   git tag -a v1.0.0 -m "v1.0.0 - brief summary of release"
-   git push origin main --tags
-   ```
-4. Build and publish:
-   ```bash
-   gem build cov-loupe.gemspec
-   gem push cov-loupe-#{version-string}.gem
-   ```
 ---
 
 ## Code of Conduct
 
-Please review and follow the [Code of Conduct](docs/code_of_conduct.md). 
-Instances of unacceptable behavior may be reported through GitHub’s [Report Abuse form](https://github.com/contact/report-abuse).
-
----
+Please review and follow the [Code of Conduct](docs/code_of_conduct.md).
 
-Thank you for helping improve **cov-loupe**!
+Instances of unacceptable behavior may be reported through GitHub's [Report Abuse form](https://github.com/contact/report-abuse).

data/README.md

@@ -22,15 +22,15 @@
 
 **cov-loupe** makes SimpleCov coverage data queryable and actionable through three interfaces:
 
-- **MCP server** - Lets AI assistants analyze your coverage
-- **CLI** - Fast command-line coverage reports and queries
+- **CLI** - command-line execution of single reports or queries
+- **MCP server** - stdio (localhost nonnetwork) server assists AI analysis of your coverage
 - **Ruby library** - Programmatic API for custom tooling
 
-Works with any SimpleCov-generated `.resultset.json` file—no runtime dependency on your test suite.
+Works with any SimpleCov-generated `.resultset.json` file—no runtime dependency on your test suite. (New coverage.json file support coming soon.)
 
 ### Key Features
 
-- ✅ **Multiple interfaces** - MCP server, CLI, and Ruby API
+- ✅ **Multiple interfaces** - CLI, MCP server, and Ruby API
 - **Annotated source code** - `-s full|uncovered|none` / `--source full|uncovered|none` with `-c N` / `--context-lines N` for context lines
 - ✅ **Staleness detection** - Identify outdated coverage (missing files, timestamp mismatches, line count changes)
 - ✅ **Multi-suite support** - Automatic merging of multiple test suites (RSpec + Cucumber, etc.)
@@ -53,6 +53,9 @@ Works with any SimpleCov-generated `.resultset.json` file—no runtime dependenc
 
 ```sh
 gem install cov-loupe
+
+# Or, for the most current version you may need to specify prerelease:
+gem install --pre cov-loupe
 ```
 
 ### Upgrading
@@ -62,8 +65,8 @@ If you are upgrading from a previous version, please refer to the [Migration Gui
 ### Generate Coverage Data
 
 ```sh
-# Run your tests with SimpleCov enabled
-bundle exec rspec  # or your test command
+# Generate your SimpleCov test coverage data with your test suite run command, e.g.:
+bundle exec rspec
 
 # Verify coverage was generated
 ls -l coverage/.resultset.json
@@ -71,35 +74,43 @@ ls -l coverage/.resultset.json
 
 ### Basic Usage
 
-**CLI - View Coverage Table:**
+**CLI - View Coverage Table:** This is the default command, so any of the following will work:
 ```sh
 cov-loupe
-# or use the 'l' abbreviation for 'list'
 cov-loupe l
+cov-loupe list
 ```
 
 **CLI - Check Specific File:**
 ```sh
-cov-loupe summary lib/cov_loupe/model.rb
+cov-loupe summary lib/cov_loupe/model/model.rb
 # or use abbreviations: s (summary), u (uncovered)
-cov-loupe s lib/cov_loupe/model.rb
+cov-loupe s lib/cov_loupe/model/model.rb
 cov-loupe u lib/cov_loupe/cli.rb
 ```
 
-**CLI - Find the Project Homepage Fast:**
-Run `cov-loupe -h` and the banner's second line shows the repository URL. Some terminal applications (e.g. iTerm2) will enable direct clicking the link using modifier keys such as `Cmd` or `Alt`.
+**CLI - Find Project Resources:**
+
+The repo URL, doc server URL, and local gem filespec are output in the header of the online help, e.g.:
+
 ```
-Usage:      cov-loupe [options] [subcommand] [args]
-Repository: https://github.com/keithrbennett/cov-loupe  # <--- Project URL ---
+Repository:            https://github.com/keithrbennett/cov-loupe
+Documentation (Web):   https://keithrbennett.github.io/cov-loupe/
+Documentation (Local): /Users/kbennett/.local/share/mise/installs/ruby/4.0.5/lib/ruby/gems/4.0.0/gems/cov-loupe-VERSION/README.md
 ```
 
-**CLI - Fetch Canonical Resource Values:**
-```sh
+There is a p/--path-for option that will get an individual value for each of these:
+
+```
 cov-loupe -p repo
-cov-loupe --path-for repo
-cov-loupe --path-for docs
-cov-loupe --path-for docs-local
-open `cov-loupe --path-for docs`
+cov-loupe -p docs
+cov-loupe -p docs-local
+```
+
+You can use your operating system's application open command (usually `open` for Mac, `xdg-open` on Linux, and `start` on Windows) to assemble this into a single command:
+
+```
+open `cov-loupe -p docs`
 ```
 
 **Ruby Library:**
@@ -109,17 +120,19 @@ require "cov_loupe"
 model = CovLoupe::CoverageModel.new
 list_result = model.list
 files = list_result["files"]
-# => [{ "file" => "lib/cov_loupe/model.rb", "covered" => 114, "total" => 118, "percentage" => 96.61, "stale" => false }, ...]
+# => [{ "file" => "/path/to/project/lib/cov_loupe/model/model.rb", "covered" => 114, "total" => 118, "percentage" => 96.61, "stale" => "ok" }, ...]
 
-summary = model.summary_for("lib/cov_loupe/model.rb")
-# => { "file" => "lib/cov_loupe/model.rb", "summary" => { "covered" => 114, "total" => 118, "percentage" => 96.61 } }
+summary = model.summary_for("lib/cov_loupe/model/model.rb")
+# => { "file" => "/path/to/project/lib/cov_loupe/model/model.rb", "summary" => { "covered" => 114, "total" => 118, "percentage" => 96.61 } }
 ```
 
-For advanced use cases, multiple models can each have their own data source and log file. See [Library API](docs/user/LIBRARY_API.md#per-model-context-advanced) for details.
+Use `model.relativize(...)` when you want library payloads with project-relative paths. See [Library API](docs/user/LIBRARY_API.md) for details.
 
 **MCP Server:**
 See [MCP Integration Guide](docs/user/MCP_INTEGRATION.md) for AI assistant setup.
 
+**Important for MCP users:** MCP servers must keep `stdout` clean until the protocol handshake begins. If `cov-loupe -m mcp` prints text such as `Resolving dependencies...` before responding, see [Troubleshooting](docs/user/TROUBLESHOOTING.md#rubygems-wrapper-prints-to-stdout-before-mcp-startup) and [MCP Integration](docs/user/MCP_INTEGRATION.md#stdout-must-stay-clean-during-mcp-startup) for wrapper and RubyGems launcher guidance.
+
 ## Multi-Suite Coverage
 
 Projects with multiple test suites (RSpec + Cucumber, etc.) are automatically merged. See [Multi-Suite Coverage Merging](docs/user/ADVANCED_USAGE.md#multi-suite-coverage-merging) for details and current limitations.
@@ -146,6 +159,8 @@ Full documentation is available at **[https://keithrbennett.github.io/cov-loupe/
 - [CLI Fallback for LLMs](docs/user/CLI_FALLBACK_FOR_LLMS.md) - When MCP isn't available
 - [Sample MCP Prompts](docs/user/prompts/README.md) - Ready-to-use ChatGPT/Claude/Gemini prompts
 - [Migration Guides](docs/user/migrations/README.md)
+  - [Migrate to v6](docs/user/migrations/MIGRATING_TO_V6.md)
+  - [Migrate to v5](docs/user/migrations/MIGRATING_TO_V5.md)
   - [Migrate to v4](docs/user/migrations/MIGRATING_TO_V4.md)
   - [Migrate to v3](docs/user/migrations/MIGRATING_TO_V3.md)
   - [Migrate to v2](docs/user/migrations/MIGRATING_TO_V2.md)
@@ -171,9 +186,17 @@ Full documentation is available at **[https://keithrbennett.github.io/cov-loupe/
 ## Requirements
 
 - **Ruby >= 3.2** (required by `mcp` gem dependency)
+- `mcp` gem >= 0.15 and < 1.0
 - SimpleCov-generated `.resultset.json` file
 - `simplecov` gem >= 0.21
 
+Applications pinned to an older `mcp` version must upgrade it before installing cov-loupe v6.
+
+### JRuby Compatibility
+
+The test suite passes on JRuby, and to the best of our knowledge the project is fully JRuby-compatible.
+If you encounter any JRuby-specific issues, please open a GitHub issue, including as much detail as possible.
+
 ## Configuring the Resultset
 
 `cov-loupe` automatically searches for `.resultset.json` in standard locations (`coverage/.resultset.json`, `.resultset.json`, `tmp/.resultset.json`). For non-standard locations:
@@ -215,25 +238,7 @@ cov-loupe -fJ list > coverage-report.json
 
 ### Best Practice: Match SimpleCov Configuration
 
-For accurate coverage tracking and validation, set `COV_LOUPE_OPTS` to match your SimpleCov `track_files` patterns:
-
-```ruby
-# In spec_helper.rb or rails_helper.rb
-SimpleCov.start do
-  add_filter '/spec/'
-  track_files 'lib/**/*.rb'
-  track_files 'app/**/*.rb'
-end
-```
-
-```sh
-# In your shell config (.bashrc, .zshrc, etc.)
-export COV_LOUPE_OPTS="--tracked-globs lib/**/*.rb,app/**/*.rb"
-```
-
-This ensures `list` and `totals` output matches SimpleCov's scope and `missing_tracked_files` (in `list`) / `missing_from_coverage` (in `totals`) report meaningful gaps.
-
-**Note:** By default, `--tracked-globs` is empty (shows all files in the resultset). This prevents silently hiding coverage data that doesn't match assumed patterns.
+For accurate coverage tracking and validation, set `COV_LOUPE_OPTS` to match your SimpleCov `track_files` patterns. See [`--tracked-globs`](docs/user/CLI_USAGE.md#tracked-globs) for the canonical setup example and default behavior.
 
 ### Working with JSON Output
 
@@ -274,23 +279,25 @@ With rexe's `-ij -mb` options, `self` automatically becomes the parsed JSON obje
 
 ### When Coverage Rows Are Skipped
 
-If a file in the resultset is missing on disk or has corrupt data, the CLI now logs and *warns* after rendering the report so operators immediately see that totals may be incomplete. Example table output:
+If a coverage row has corrupt or malformed data, the CLI now logs and *warns* after rendering the report.
+This lets operators immediately see that totals may be incomplete. Example table output:
 
 ```text
 $ cov-loupe list
-┌─────────────────────────────┬─────────┬─────────┬────────────┬───────┐
-│ File                        │ Covered │ Total   │ % Covered  │ Stale │
-├─────────────────────────────┼─────────┼─────────┼────────────┼───────┤
-│ lib/foo.rb                  │       2 │       3 │     66.67% │       │
-│ lib/bar.rb                  │       1 │       3 │     33.33% │       │
-└─────────────────────────────┴─────────┴─────────┴────────────┴───────┘
+┌─────────────────────────────┬──────────┬─────────┬───────┬───────┐
+│ File                        │        % │ Covered │ Total │ Stale │
+├─────────────────────────────┼──────────┼─────────┼───────┼───────┤
+│ lib/foo.rb                  │   66.67% │       2 │     3 │       │
+│ lib/bar.rb                  │   33.33% │       1 │     3 │       │
+└─────────────────────────────┴──────────┴─────────┴───────┴───────┘
+Files: total 2, ok 2, stale 0
 
 WARNING: 1 coverage row skipped due to errors:
-  - lib/deleted.rb: No coverage data found for file: lib/deleted.rb
+  - lib/corrupt.rb: Invalid coverage line array: contains non-integer elements: ["bad"]
 Run again with --raise-on-stale to exit when rows are skipped.
 ```
 
-Pretty JSON (`-fJ`) reports still emit valid JSON to `stdout`; the warning continues to be printed on `stderr`:
+Multi-line, indented JSON (`-fJ`) reports still emit valid JSON to `stdout`; the warning continues to be printed on `stderr`:
 
 ```text
 $ cov-loupe -fJ list
@@ -299,11 +306,24 @@ $ cov-loupe -fJ list
     { "file": "lib/foo.rb", "covered": 2, "total": 3, "percentage": 66.67, "stale": "ok" },
     { "file": "lib/bar.rb", "covered": 1, "total": 3, "percentage": 33.33, "stale": "ok" }
   ],
+  "skipped_files": [
+    {
+      "file": "lib/corrupt.rb",
+      "error": "Invalid coverage line array: contains non-integer elements: [\"bad\"]",
+      "error_class": "CovLoupe::CoverageDataError"
+    }
+  ],
+  "missing_tracked_files": [],
+  "newer_files": [],
+  "deleted_files": [],
+  "length_mismatch_files": [],
+  "unreadable_files": [],
+  "timestamp_status": "ok",
   "counts": { "total": 2, "ok": 2, "stale": 0 }
 }
 
 WARNING: 1 coverage row skipped due to errors:
-  - lib/deleted.rb: No coverage data found for file: lib/deleted.rb
+  - lib/corrupt.rb: Invalid coverage line array: contains non-integer elements: ["bad"]
 Run again with --raise-on-stale to exit when rows are skipped.
 ```
 
@@ -327,7 +347,7 @@ cov-loupe -fJ list > artifacts/coverage.json
 
 ```sh
 # Quick summary
-cov-loupe summary lib/cov_loupe/model.rb
+cov-loupe summary lib/cov_loupe/model/model.rb
 
 # See uncovered lines
 cov-loupe uncovered lib/cov_loupe/cli.rb
@@ -336,7 +356,7 @@ cov-loupe uncovered lib/cov_loupe/cli.rb
 cov-loupe -s u -c 3 uncovered lib/cov_loupe/cli.rb  # -s = --source (u = uncovered, n = none to disable), -c = --context-lines
 
 # Detailed hit counts
-cov-loupe detailed lib/cov_loupe/util.rb
+cov-loupe detailed lib/cov_loupe/coverage/coverage_calculator.rb
 
 # Project totals
 cov-loupe totals