simplecov-mcp 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95c9d9edb894cafc89610f2d171e7452ec092a484666cfb15eac0314a1189963
-  data.tar.gz: bdb9d23aa1a53adfde9abe953fbeb21e1c998435a9fa63e7150f8ab7d26c8184
+  metadata.gz: f35432a5fa155b21702ea533b8ab875a14bf520881e8a40e348aa15d597cdd66
+  data.tar.gz: 34deaac536651232ed05a606af80b07ebdba9ef945e4fc454efd4aecf0631251
 SHA512:
-  metadata.gz: 5f2c42c2f48e5fecf6c7e7392dd384b7255a2b3b48ccb5fcc89fb423918ff9f5028b57f6ce68b4c03f288c23665a23d08d7cf48f9e36eaebab753cd4f2aa7ec6
-  data.tar.gz: 4a96af4e01a259d194a902e9ea45c98058ffc06c5ed4313cf6785e7fc40929b3a186b6ccd9bbb078b9907f84173223096eafb278bbb696c3df414495b1e672d4
+  metadata.gz: 9adcc5e0b9f70ac5f6e9501194aa891fa93756e91513c470a11028072f7a7a260e36d25d0337a4bade9889dfc7f1a9d28d429148320560697b1ac465335bb820
+  data.tar.gz: '095a9e06c5b45d635d03e84aeb35a39ecbe49ff2b5fef4cbac27913794e822a7d28b3997d68e047f67ea4215500c2fe8931978c81440cdafbc0d28d6830899a8'

data/README.md

@@ -8,20 +8,23 @@
 
 **simplecov-mcp** makes SimpleCov coverage data queryable and actionable through three interfaces:
 
-- **MCP server** - Let AI assistants analyze your coverage
+- **MCP server** - Lets AI assistants analyze your coverage
 - **CLI** - Fast command-line coverage reports and queries
 - **Ruby library** - Programmatic API for custom tooling
 
 Works with any SimpleCov-generated `.resultset.json` file—no runtime dependency on your test suite.
 
-### Key capabilities
+### Key Features
 
-- Flexible path resolution (absolute or relative paths)
-- Staleness detection (identifies outdated coverage files)
-- Multi-suite resultset merging when needed
-- Multiple useful output formats (tables, JSON, annotated source)
+- ✅ **Multiple interfaces** - MCP server, CLI, and Ruby API
+- **Annotated source code** - `--source full|uncovered` with `--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.)
+- ✅ **Flexible path resolution** - Works with absolute or relative paths
+- ✅ **Comprehensive error handling** - Context-aware messages for each mode
+- ⚠️ **Branch coverage limitation** - Branch-level metrics are collapsed to per-line totals. Use native SimpleCov reports for branch-by-branch analysis.
 
-### Practical use cases
+### Practical Use Cases
 
 - Query coverage data from AI assistants, e.g.:
   - "Using simplecov-mcp, analyze test coverage data and write a report to a markdown file containing a free text analysis of each issue and then two tables, one sorted in descending order of urgency, the other in ascending order of level of effort."
@@ -29,6 +32,7 @@ Works with any SimpleCov-generated `.resultset.json` file—no runtime dependenc
 - Find files with the lowest coverage
 - Investigate specific files or directories
 - Generate CI/CD coverage reports
+- Create custom pass/fail predicates for scripts and CI - use the library API or CLI JSON output to implement arbitrarily complex coverage rules beyond simple thresholds (e.g., require higher coverage for critical paths, exempt test utilities, track coverage trends)
 
 ## Quick Start
 
@@ -45,7 +49,7 @@ gem install simplecov-mcp
 bundle exec rspec  # or your test command
 
 # Verify coverage was generated
-ls coverage/.resultset.json
+ls -l coverage/.resultset.json
 ```
 
 ### Basic Usage
@@ -61,6 +65,13 @@ simplecov-mcp summary lib/simplecov_mcp/model.rb
 simplecov-mcp uncovered lib/simplecov_mcp/cli.rb
 ```
 
+**CLI - Find the Project Homepage Fast:**
+Run `simplecov-mcp -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`.
+```
+Usage:      simplecov-mcp [options] [subcommand] [args]
+Repository: https://github.com/keithrbennett/simplecov-mcp  # <--- Project URL ---
+```
+
 **Ruby Library:**
 ```ruby
 require "simplecov_mcp"
@@ -70,21 +81,11 @@ files = model.all_files
 # => [{ "file" => "lib/simplecov_mcp/model.rb", "covered" => 114, "total" => 118, "percentage" => 96.61, "stale" => false }, ...]
 
 summary = model.summary_for("lib/simplecov_mcp/model.rb")
-# => { "file" => "lib/simplecov_mcp/model.rb", "summary" => { "covered" => 114, "total" => 118, "pct" => 96.61 }, "stale" => false }
+# => { "file" => "lib/simplecov_mcp/model.rb", "summary" => { "covered" => 114, "total" => 118, "percentage" => 96.61 }, "stale" => false }
 ```
 
 **MCP Server:**
-See [MCP Integration Guide](docs/MCP_INTEGRATION.md) for AI assistant setup.
-
-## Key Features
-
-- ✅ **Multiple interfaces** - MCP server, CLI, and Ruby API
-- ✅ **Rich output formats** - Tables, JSON, annotated source code
-- ✅ **Staleness detection** - Identify outdated coverage (missing files, timestamp mismatches, line count changes)
-- ✅ **Multi-suite support** - Automatic merging of multiple test suites (RSpec + Cucumber, etc.)
-- ✅ **Flexible path resolution** - Works with absolute or relative paths
-- ✅ **Comprehensive error handling** - Context-aware messages for each mode
-- ⚠️ **Branch coverage limitation** - Branch-level metrics are collapsed to per-line totals. Use native SimpleCov reports for branch-by-branch analysis.
+See [MCP Integration Guide](docs/user/MCP_INTEGRATION.md) for AI assistant setup.
 
 ## Multi-Suite Coverage Merging
 
@@ -103,25 +104,28 @@ When a `.resultset.json` file contains multiple test suites (e.g., RSpec + Cucum
 ## Documentation
 
 **Getting Started:**
-- [Installation](docs/INSTALLATION.md) - Setup for different environments
-- [CLI Usage](docs/CLI_USAGE.md) - Command-line reference
-- [Examples](docs/EXAMPLES.md) - Common use cases
+- [Installation](docs/user/INSTALLATION.md) - Setup for different environments
+- [CLI Usage](docs/user/CLI_USAGE.md) - Command-line reference
+- [Examples](docs/user/EXAMPLES.md) - Common use cases
 
 **Advanced Usage:**
-- [MCP Integration](docs/MCP_INTEGRATION.md) - AI assistant configuration
-- [Library API](docs/LIBRARY_API.md) - Ruby API documentation
-- [Error Handling](docs/ERROR_HANDLING.md) - Error modes and exceptions
+- [MCP Integration](docs/user/MCP_INTEGRATION.md) - AI assistant configuration
+- [CLI Fallback for LLMs](docs/user/CLI_FALLBACK_FOR_LLMS.md) - Using CLI when MCP isn't available
+- [Library API](docs/user/LIBRARY_API.md) - Ruby API documentation
+- [Advanced Usage](docs/user/ADVANCED_USAGE.md) - Staleness detection, error modes, path resolution
+- [Error Handling](docs/user/ERROR_HANDLING.md) - Error modes and exceptions
 
 **Reference:**
-- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues
-- [Development](docs/DEVELOPMENT.md) - Contributing guide
+- [Architecture](docs/dev/ARCHITECTURE.md) - Design and internals
+- [Branch Coverage](docs/dev/BRANCH_ONLY_COVERAGE.md) - Branch coverage limitations
+- [Troubleshooting](docs/user/TROUBLESHOOTING.md) - Common issues
+- [Development](docs/dev/DEVELOPMENT.md) - Contributing guide
 
 ## Requirements
 
 - **Ruby >= 3.2** (required by `mcp` gem dependency)
 - SimpleCov-generated `.resultset.json` file
 - `simplecov` gem >= 0.21
-- RVM users: export your preferred ruby/gemset *before* running commands (e.g. `rvm use 3.4.5@simplecov-mcp`)
 
 ## Configuring the Resultset
 
@@ -139,7 +143,7 @@ export SIMPLECOV_MCP_OPTS="--resultset /path/to/your/coverage"
 # "args": ["--resultset", "/path/to/your/coverage"]
 ```
 
-See [CLI Usage Guide](docs/CLI_USAGE.md#-r---resultset-path) for complete details.
+See [CLI Usage Guide](docs/user/CLI_USAGE.md#-r---resultset-path) for complete details.
 
 
 
@@ -149,26 +153,66 @@ See [CLI Usage Guide](docs/CLI_USAGE.md#-r---resultset-path) for complete detail
 
 ```sh
 # Files with worst coverage
-simplecov-mcp list --sort-order d # display table in descending order, worst will be at end of output
-simplecov-mcp list -o d           # same as above, short form option
+simplecov-mcp -o d list           # -o = --sort-order, d = descending (worst at end)
 simplecov-mcp list | less         # display table in pager, worst files first
 simplecov-mcp list | head -10     # truncate the table
 
 # Specific directory
-simplecov-mcp list --tracked-globs "lib/simplecov_mcp/tools/**/*.rb"
+simplecov-mcp -g "lib/simplecov_mcp/tools/**/*.rb" list  # -g = --tracked-globs
 
 # Export for analysis
-simplecov-mcp list --json > coverage-report.json
+simplecov-mcp -fJ list > coverage-report.json
 ```
 
+### Working with JSON Output
+
+The `-fJ` flag enables programmatic processing of coverage data using command-line JSON tools.
+
+**Using jq:**
+```sh
+# Filter files below 80% coverage
+simplecov-mcp -fJ list | jq '.files[] | select(.percentage < 80)'
+```
+
+**Using Ruby one-liners:**
+```sh
+# Count files below threshold
+simplecov-mcp -fJ list | ruby -r json -e '
+  puts JSON.parse($stdin.read)["files"].count { |f| f["percentage"] < 80 }
+'
+```
+
+**Using rexe:**
+
+[rexe](https://github.com/keithrbennett/rexe) is a Ruby gem that enables shorter Ruby command lines by providing command-line options for input and output formats, plus other conveniences. It eliminates the need for explicit JSON parsing and formatting code.
+
+Install: `gem install rexe`
+
+```sh
+# Filter files below 80% coverage with pretty-printed JSON output
+simplecov-mcp -fJ list | rexe -ij -mb -oJ 'self["files"].select { |f| f["percentage"] < 80 }'
+
+# Count files below threshold
+simplecov-mcp -fJ list | rexe -ij -mb -op 'self["files"].count { |f| f["percentage"] < 80 }'
+
+# Human-readable output with AwesomePrint
+simplecov-mcp -fJ list | rexe -ij -mb -oa 'self["files"].first(3)'
+```
+
+With rexe's `-ij -mb` options, `self` automatically becomes the parsed JSON object. The same holds true for JSON output -- using `-oJ` produces pretty-printed JSON without explicit formatting calls. Rexe also supports YAML input/output (`-iy`, `-oy`) and AwesomePrint output (`-oa`) for human consumption.
+
+Run `rexe -h` to see all available options, or visit the [rexe project page](https://github.com/keithrbennett/rexe) for more examples.
+
+For comprehensive JSON processing examples, see [docs/user/EXAMPLES.md](docs/user/EXAMPLES.md).
+
 ### CI/CD Integration
 
 ```sh
 # Fail build if coverage is stale
-simplecov-mcp --stale error || exit 1
+simplecov-mcp --staleness error || exit 1
 
 # Generate coverage report artifact
-simplecov-mcp list --json > artifacts/coverage.json
+simplecov-mcp -fJ list > artifacts/coverage.json
 ```
 
 ### Investigate Specific Files
@@ -181,31 +225,35 @@ simplecov-mcp summary lib/simplecov_mcp/model.rb
 simplecov-mcp uncovered lib/simplecov_mcp/cli.rb
 
 # View in context
-simplecov-mcp uncovered lib/simplecov_mcp/cli.rb --source=uncovered --source-context 3
+simplecov-mcp -s u -c 3 uncovered lib/simplecov_mcp/cli.rb  # -s = --source (u = uncovered), -c = --context-lines
 
 # Detailed hit counts
 simplecov-mcp detailed lib/simplecov_mcp/util.rb
+
+# Project totals
+simplecov-mcp totals
+simplecov-mcp -fJ totals
 ```
 
 ## Commands and Tools
 
-**CLI Subcommands:** `list`, `summary`, `uncovered`, `detailed`, `raw`, `version`
+**CLI Subcommands:** `list`, `summary`, `uncovered`, `detailed`, `raw`, `totals`, `validate`, `version`
 
-**MCP Tools:** `coverage_summary_tool`, `coverage_detailed_tool`, `coverage_raw_tool`, `uncovered_lines_tool`, `all_files_coverage_tool`, `coverage_table_tool`, `help_tool`, `version_tool`
+**MCP Tools:** `coverage_summary_tool`, `coverage_detailed_tool`, `coverage_raw_tool`, `uncovered_lines_tool`, `all_files_coverage_tool`, `coverage_totals_tool`, `coverage_table_tool`, `validate_tool`, `help_tool`, `version_tool`
 
 📖 **See also:**
-- [CLI Usage Guide](docs/CLI_USAGE.md) - Complete command-line reference
-- [MCP Integration Guide](docs/MCP_INTEGRATION.md#available-mcp-tools) - MCP tools documentation
+- [CLI Usage Guide](docs/user/CLI_USAGE.md) - Complete command-line reference
+- [MCP Integration Guide](docs/user/MCP_INTEGRATION.md#available-mcp-tools) - MCP tools documentation
 
 ## Troubleshooting
 
-- **"command not found"** - See [Installation Guide](docs/INSTALLATION.md#path-configuration)
-- **"cannot load such file -- mcp"** - Upgrade to Ruby >= 3.2
-- **"Could not find .resultset.json"** - Run tests to generate coverage. See the [Configuring the Resultset](#configuring-the-resultset) section for more details.
-- **MCP server won't connect** - Check PATH and Ruby version in [MCP Troubleshooting](docs/MCP_INTEGRATION.md#troubleshooting)
-- **Codex on macOS with RVM** - Codex's macOS sandbox disallows `/bin/ps`, which RVM needs. Use a different version manager (rbenv, chruby) or run outside the Codex environment.
+- **"command not found"** - See [Installation Guide](docs/user/INSTALLATION.md#path-configuration)
+- **"cannot load such file -- mcp"** - Requires Ruby >= 3.2. Verify: `ruby -v`
+- **"Could not find .resultset.json"** - Ensure SimpleCov is configured in your test suite, then run tests to generate coverage. See the [Configuring the Resultset](#configuring-the-resultset) section for more details.
+- **MCP server won't connect** - Check PATH and Ruby version in [MCP Troubleshooting](docs/user/MCP_INTEGRATION.md#troubleshooting)
+- **RVM in sandboxed environments (macOS)** - RVM requires `/bin/ps` which may be blocked by sandbox restrictions. Use rbenv or chruby instead.
 
-For more detailed help, see the full [Troubleshooting Guide](docs/TROUBLESHOOTING.md).
+For more detailed help, see the full [Troubleshooting Guide](docs/user/TROUBLESHOOTING.md).
 
 ## Development
 
@@ -219,14 +267,14 @@ bundle install
 bundle exec rspec
 
 # Test locally
-ruby -Ilib exe/simplecov-mcp
+bundle exec exe/simplecov-mcp
 
 # Build and install
 gem build simplecov-mcp.gemspec
 gem install simplecov-mcp-*.gem
 ```
 
-See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for more *(coming soon)*.
+See [docs/dev/DEVELOPMENT.md](docs/dev/DEVELOPMENT.md) for more.
 
 ## SimpleCov Dependency
 
@@ -265,7 +313,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 📦 **Install:** `gem install simplecov-mcp`
 
-📖 **Read:** [CLI Usage Guide](docs/CLI_USAGE.md) | [MCP Integration](docs/MCP_INTEGRATION.md)
+📖 **Read:** [CLI Usage Guide](docs/user/CLI_USAGE.md) | [MCP Integration](docs/user/MCP_INTEGRATION.md)
 
 🐛 **Report issues:** [GitHub Issues](https://github.com/keithrbennett/simplecov-mcp/issues)
 

data/docs/{ARCHITECTURE.md → dev/ARCHITECTURE.md}

@@ -1,5 +1,7 @@
 # Architecture
 
+[Back to main README](../README.md)
+
 simplecov-mcp is organized around a single coverage data model that feeds three delivery channels: a command-line interface, an MCP server for LLM agents, and a light-weight Ruby API. The codebase is intentionally modular—shared logic for loading, normalizing, and validating SimpleCov data lives in `lib/simplecov_mcp/`, while adapters wrap that core for each runtime mode.
 
 ## Runtime Entry Points
@@ -11,16 +13,16 @@ simplecov-mcp is organized around a single coverage data model that feeds three
 ## Coverage Data Pipeline
 
 1. **Resultset discovery** – The tool locates the `.resultset.json` file by checking a series of default paths or by using a path specified by the user. For a detailed explanation of the configuration options, see the [Configuring the Resultset](../README.md#configuring-the-resultset) section in the main README.
-2. **Parsing and normalization** – `CoverageModel` loads the chosen resultset once, selects the first suite that exposes `coverage`, and maps all file keys to absolute paths anchored at the configured project root. Timestamps are cached for staleness checks.
+2. **Parsing and normalization** – `CoverageModel` loads the chosen resultset once, extracts all test suites that expose `coverage` data (e.g., "RSpec", "Minitest"), merges them if multiple suites exist, and maps all file keys to absolute paths anchored at the configured project root. Timestamps are cached for staleness checks.
 3. **Path relativizing** – `PathRelativizer` produces relative paths for user-facing payloads without mutating the canonical data. Tool responses pass through `CoverageModel#relativize` before leaving the process.
 4. **Derived metrics** – `CovUtil.summary`, `CovUtil.uncovered`, and `CovUtil.detailed` compute coverage stats from the raw `lines` arrays. `CoverageModel` exposes `summary_for`, `uncovered_for`, `detailed_for`, and `raw_for` helpers that wrap these utilities.
-5. **Staleness detection** – `StalenessChecker` compares source mtimes/line counts to coverage metadata. CLI flags and MCP arguments can promote warnings to hard failures (`--stale error`) or simply mark rows as stale for display.
+5. **Staleness detection** – `StalenessChecker` compares source mtimes/line counts to coverage metadata. CLI flags and MCP arguments can promote warnings to hard failures (`--staleness error`) or simply mark rows as stale for display.
 
 ## Interfaces
 
 ### CLI (`SimpleCovMcp::CoverageCLI`)
 
-- Builds on Ruby’s `OptionParser`, with global options such as `--resultset`, `--stale`, `--json`, and `--source` modes.
+- Builds on Ruby’s `OptionParser`, with global options such as `--resultset`, `--staleness`, `-fJ`, and `--source` modes.
 - Subcommands (`list`, `summary`, `raw`, `uncovered`, `detailed`, `version`) translate to calls on `CoverageModel`.
 - Uses `ErrorHandlerFactory.for_cli` to convert unexpected exceptions into friendly user messages while honoring `--error-mode`.
 - Formatting logic (tables, JSON) lives in the model to keep presentation consistent with MCP responses.
@@ -45,7 +47,7 @@ simplecov-mcp is organized around a single coverage data model that feeds three
 ## Error Handling & Logging
 
 - Custom exceptions under `lib/simplecov_mcp/errors.rb` capture context for configuration issues, missing files, stale coverage, and general runtime errors. Each implements `#user_friendly_message` for consistent UX.
-- `SimpleCovMcp::ErrorHandler` encapsulates logging and severity decisions. Modes (`:off`, `:on`, `:trace`) control whether errors are recorded and whether stack traces are included.
+- `SimpleCovMcp::ErrorHandler` encapsulates logging and severity decisions. Modes (`:off`, `:log`, `:debug`) control whether errors are recorded and whether stack traces are included.
 - Runtime configuration (error handlers, log destinations) flows through `SimpleCovMcp::AppContext`. Entry points push a context with `SimpleCovMcp.with_context`, which stores the active configuration in a thread-local slot (`SimpleCovMcp.context`). Nested calls automatically restore the previous context when the block exits, ensuring isolation even when multiple callers share a process or thread.
 - Two helper accessors clarify intent:
   - `SimpleCovMcp.default_log_file` / `default_log_file=` adjust the baseline log sink that future contexts inherit.
@@ -57,22 +59,21 @@ simplecov-mcp is organized around a single coverage data model that feeds three
 
 - **Environment defaults** – `SIMPLECOV_MCP_OPTS` applies baseline CLI flags before parsing the actual command line.
 - **Resultset overrides** – The location of the `.resultset.json` file can be specified via CLI options or in the MCP configuration. See [Configuring the Resultset](../README.md#configuring-the-resultset) for details.
-- **Tracked globs** – For project staleness checks, `tracked_globs` ensures new files raise alerts when absent from coverage.
+- **Tracked globs** – Glob patterns (e.g., `lib/**/*.rb`) that specify which files should have coverage. When provided, SimpleCov MCP alerts you if any matching files are missing from the coverage data, helping catch untested files that were added to the project but never executed during test runs.
 - **Colorized source** – CLI-only flags (`--source`, `--source-context`, `--color`) enhance human-readable reports when working locally.
 
 ## Repository Layout Highlights
 
 - `lib/simplecov_mcp/` – Core runtime (model, utilities, error handling, CLI, MCP server, tools).
 - `lib/simplecov_mcp.rb` – Primary public entry point required by gem consumers.
-- `docs/` – User-facing guides (usage, installation, troubleshooting, architecture).
+- `docs/` – Audience-specific guides (`docs/user` for usage, `docs/dev` for contributors).
 - `spec/` – RSpec suite with fixtures under `spec/fixtures/` for deterministic coverage data.
-- `scripts/` – Helper scripts (e.g., `scripts/setup_codex_cloud.sh`).
 
-## Extending the System
+## Extending the System With a New Tool or Metric
 
 1. Add or update data processing inside `CoverageModel` or `CovUtil` when a new metric is needed.
-2. Surface that metric through the desired interface: CLI option/subcommand, new MCP tool, or library helper.
-3. Register the new tool in `MCPServer`, or update CLI option parsing in `CoverageCLI`.
+2. Surface that metric through all interfaces: add a CLI option/subcommand, create an MCP tool, and expose a library helper method.
+3. Register the new tool in `MCPServer` and update CLI option parsing in `CoverageCLI`.
 4. Provide tests under `spec/` mirroring the lib path (`spec/lib/simplecov_mcp/..._spec.rb`).
 5. Update documentation to reflect the new capability.
 

data/docs/dev/BRANCH_ONLY_COVERAGE.md

@@ -0,0 +1,158 @@
+# Branch-Only Coverage Handling
+
+[Back to main README](../README.md)
+
+> **Note:** This document is for **developers working on SimpleCov MCP**, not for users of the gem.
+> If you're a user, you don't need to read this - branch-only coverage "just works" automatically.
+> This explains the internal implementation for contributors who need to maintain or modify the code.
+
+## The Problem This Solves for SimpleCov MCP
+
+SimpleCov can be configured to track different types of coverage:
+- **Line coverage**: Which lines of code were executed
+- **Branch coverage**: Which paths through if/else, case/when, etc. were taken
+- **Both**: Track both lines and branches together
+
+When users configure SimpleCov to track **only branch coverage** (without line coverage),
+the `.resultset.json` file has a different structure: the `lines` array is `null`,
+and only the `branches` data exists.
+
+**This breaks SimpleCov MCP** because our entire tool is designed around the `lines` array:
+- Our MCP tools (`coverage_summary_tool`, `uncovered_lines_tool`, etc.) expect line data
+- Our CLI commands expect line data
+- Our `CoverageModel` API expects line data
+
+Rather than failing with "no coverage data found" errors, SimpleCov MCP **automatically
+converts branch coverage into line coverage** so all our tools continue to work seamlessly
+for projects using branch-only configuration.
+
+## What Branch-Only Coverage Data Looks Like
+
+When SimpleCov writes branch-only coverage, the `.resultset.json` file looks different
+from the normal line coverage format. Here's an example:
+
+```json
+{
+  "lib/example.rb": {
+    "lines": null,
+    "branches": {
+      "[:if, 0, 12, 4, 20, 29]": {
+        "[:then, 1, 13, 6, 13, 18]": 4,
+        "[:else, 2, 15, 6, 15, 16]": 0
+      }
+    }
+  }
+}
+```
+
+### Understanding the Branch Data Structure
+
+The `branches` hash uses a nested structure:
+
+**Outer key** (e.g., `"[:if, 0, 12, 4, 20, 29]"`):
+- This is either a Ruby array or its stringified version
+- It describes where the branch decision happens (the `if` statement itself)
+- Format: `[type, id, start_line, start_col, end_line, end_col]`
+  - Position 0: Branch type (`:if`, `:case`, `:unless`, etc.)
+  - Position 1: SimpleCov's internal ID for this branch
+  - **Position 2: The line number** ← This is what we need for line coverage!
+  - Position 3: Starting column
+  - Position 4: Ending line
+  - Position 5: Ending column
+
+**Nested hash** (the value of the outer key):
+- Contains each possible path through the branch
+- Keys are branch targets like `"[:then, 1, 13, 6, 13, 18]"` or `"[:else, 2, 15, 6, 15, 16]"`
+- Each target has the same array format as the outer key
+- Values are integers showing how many times that path was executed
+  - `4` means the `then` branch ran 4 times
+  - `0` means the `else` branch never ran
+
+**Why this matters for our conversion:**
+- We extract the line number (position 2) from each branch target
+- We sum up all the execution counts for branches on the same line
+- This gives us enough information to build a line coverage array
+
+## How SimpleCov MCP Converts Branch Coverage to Line Coverage
+
+Since all of SimpleCov MCP's tools expect a `lines` array, we need to build one from
+the `branches` data. This happens automatically in the `CoverageLineResolver` whenever
+it detects that `lines` is `null` but `branches` exists.
+
+### The Conversion Algorithm
+
+Here's how we transform branch data into line data:
+
+**Step 1: Parse the branch keys**
+- Branch keys can be either raw Ruby arrays or stringified (e.g., `"[:if, 0, 12, 4, 20, 29]"`)
+- We handle both formats by parsing the string format when needed
+
+**Step 2: Extract line numbers**
+- From each branch target tuple, we pull out position 2 (the line number)
+- Invalid or malformed tuples are silently skipped
+
+**Step 3: Sum hits per line**
+- Multiple branches can exist on the same line (e.g., nested ifs, ternaries)
+- We add up all the execution counts for branches on the same line
+- Example: if line 15 has a `then` branch hit 4 times and an `else` branch hit 2 times,
+  that line gets a total of 6 hits
+
+**Step 4: Build the line array**
+- We create an array with length equal to the highest line number found
+- Each array position represents a line: `array[0]` = line 1, `array[1]` = line 2, etc.
+- Positions get the summed hit count for that line, or `nil` if no branches appeared there
+
+**Result:** We now have a `lines` array that looks exactly like SimpleCov's normal
+format, so all our tools (`summary`, `uncovered`, staleness checks, etc.) work without
+knowing branch coverage was involved.
+
+## Where to Find the Code
+
+If you need to modify or debug the branch coverage conversion, here's where everything lives:
+
+### Implementation
+**`lib/simplecov_mcp/resolvers/coverage_line_resolver.rb`**
+- Line 59-66: `lines_from_entry` - Detects when to synthesize line data
+- Line 68-103: `synthesize_lines_from_branches` - The main conversion logic
+- Line 105-123: `extract_line_number` - Parses line numbers from branch tuples
+
+This file is referenced in the code comments at line 79.
+
+### Tests
+**`spec/resolvers/coverage_line_resolver_spec.rb`**
+- Contains tests specifically for the resolver and branch synthesis
+
+**`spec/simplecov_mcp_model_spec.rb`**
+- Integration tests showing how the model uses synthesized line data
+
+### Test Data
+**`spec/fixtures/branch_only_project/coverage/.resultset.json`**
+- Example of real branch-only coverage data used in tests
+- Useful reference when debugging issues or adding new test cases
+
+## Important Implementation Notes
+
+### Why the resolver returns `nil` for missing files
+
+When `CoverageLineResolver.lookup_lines` can't find a file, it returns `nil` rather
+than immediately raising an error. This is deliberate:
+
+- The lookup tries multiple strategies: exact path match, relative path, path without
+  working directory prefix
+- Each strategy calls `lines_from_entry` which may return `nil`
+- Only after **all strategies fail** does the resolver raise a `FileError`
+- This ensures we try every possible way to find the file before giving up
+
+If you change `lines_from_entry` to raise an error immediately, the multi-strategy
+lookup will break!
+
+### Future-proofing for SimpleCov changes
+
+SimpleCov's branch tuple format could change in future versions. If that happens:
+
+1. Update `extract_line_number` to recognize the new tuple format
+2. Add test fixtures with the new format
+3. Update this documentation with the new structure
+4. Keep backward compatibility with the old format if possible
+
+This way, SimpleCov MCP continues working even when SimpleCov evolves.

data/docs/{DEVELOPMENT.md → dev/DEVELOPMENT.md}

@@ -1,5 +1,7 @@
 # Development Guide
 
+[Back to main README](../README.md)
+
 > **Note:** Commands like `simplecov-mcp` assume the gem is installed globally. If not, substitute `bundle exec exe/simplecov-mcp`.
 
 ## Setup
@@ -79,4 +81,3 @@ before { setup_mcp_response_stub }
 ```sh
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | simplecov-mcp
 ```
-

data/docs/dev/README.md

@@ -0,0 +1,10 @@
+# Developer Documentation
+
+Resources for contributors working on SimpleCov MCP internals and release
+engineering.
+
+- [Architecture Overview](ARCHITECTURE.md) – subsystem layout and data flow
+- [Development Guide](DEVELOPMENT.md) – setup, testing, release workflow
+- [Branch Coverage Support](BRANCH_ONLY_COVERAGE.md) – implementation notes and limitations
+- [Architecture Decision Records](arch-decisions/README.md) – design history
+- [Presentations](presentations/simplecov-mcp-presentation.md) – slide deck for talks/demos