cov-loupe 3.0.0 → 4.0.0.pre

data/docs/user/ADVANCED_USAGE.md

@@ -1,22 +1,25 @@
 # Advanced Usage Guide
 
-[Back to main README](../README.md)
+[Back to main README](../index.md)
 
 > Examples use `clp`, an alias pointed at the demo fixture with partial coverage:
-> `alias clp='cov-loupe --root docs/fixtures/demo_project'`
-> Swap `clp` with `cov-loupe` if you want to target your own project/resultset.
+> 
+> `alias clp='cov-loupe -R docs/fixtures/demo_project' # (-R = --root_dir)`
+> 
+> Replace `clp` with `cov-loupe` if you want to target your own project/resultset.
 
 ## Table of Contents
 
 - [Advanced MCP Integration](#advanced-mcp-integration)
-- [Staleness Detection & Validation](#staleness-detection--validation)
+- [Staleness Detection & Validation](#staleness-detection-validation)
 - [Advanced Path Resolution](#advanced-path-resolution)
 - [Error Handling Strategies](#error-handling-strategies)
 - [Custom Ruby Integration](#custom-ruby-integration)
-- [CI/CD Integration Patterns](#cicd-integration-patterns)
-- [Advanced Filtering & Glob Patterns](#advanced-filtering--glob-patterns)
+- [CI/CD Integration](#cicd-integration)
+- [Advanced Filtering & Glob Patterns](#advanced-filtering-glob-patterns)
 - [Performance Optimization](#performance-optimization)
 - [Custom Output Processing](#custom-output-processing)
+- [Multi-Suite Coverage Merging](#multi-suite-coverage-merging)
 
 ---
 
@@ -45,63 +48,74 @@ The MCP server uses structured error responses:
 
 The MCP server logs to `cov_loupe.log` in the current directory by default.
 
-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`.
 
-**Note:** Logging to `stdout` is not permitted in MCP mode.
+**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 since it would interfere with the request processing.
 
 ### Testing MCP Server Manually
 
-Use JSON-RPC over stdin to test the MCP server:
+Use JSON-RPC over stdin to test the MCP server. **Note:** CLI flags set defaults for MCP tool calls, but per-request JSON parameters still win. Use `-R`/`-r` when you want server-wide defaults, or pass `root`/`resultset` per request.
 
 ```sh
-# Get version
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | clp
+# Get version (no parameters needed)
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | cov-loupe -m mcp
 
-# Get file summary
-echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"app/models/order.rb"}}}' | clp
+# Get file summary (include root parameter in JSON)
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"app/models/order.rb","root":"docs/fixtures/demo_project"}}}' | cov-loupe -m mcp
 
-# List all files with sorting
-echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"all_files_coverage_tool","arguments":{"sort_order":"ascending"}}}' | clp
+# List all files with sorting (include root parameter)
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_tool","arguments":{"sort_order":"ascending","root":"docs/fixtures/demo_project"}}}' | cov-loupe -m mcp
 
-# Get uncovered lines
-echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"uncovered_lines_tool","arguments":{"path":"app/controllers/orders_controller.rb"}}}' | clp
+# Get uncovered lines (include root parameter)
+echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"uncovered_lines_tool","arguments":{"path":"app/controllers/orders_controller.rb","root":"docs/fixtures/demo_project"}}}' | cov-loupe -m mcp
 ```
 
+**Why not use `clp` alias here?** `clp` is useful for CLI subcommands, but MCP calls run a long-lived server process. You can pass `-R` at startup to set defaults, or set `root` explicitly in each JSON request when you want to be explicit or override the defaults.
+
+---
+
+## Sorting Coverage Lists with n/a Entries
+
+When a file has no executable lines, its coverage percentage is reported as `n/a`. In list outputs, `n/a` entries are grouped separately from numeric percentages. The default descending sort order places `n/a` entries above `100%` coverage so they appear earlier in the list, while still keeping low numeric percentages toward the bottom for attention.
+
+If you need to treat `n/a` differently, post-process the JSON output from `list` or `list_tool` and apply your own sort or filtering rules.
+
 ---
 
 ## Staleness Detection & Validation
 
-### Understanding Staleness Modes
+### Understanding Staleness Checks
 
-Staleness checking prevents using outdated coverage data. Two modes are available:
+Staleness checking prevents using outdated coverage data. The behavior is controlled by the boolean `raise_on_stale` setting:
 
-**Mode: `off` (default)**
-- No validation, fastest operation
-- Coverage data used as-is
-- Stale indicators still computed but don't block operations
+**`raise_on_stale: false` (default)**
+- Coverage data is returned even if stale
+- Stale indicators are still computed
+- Best for exploratory reporting
 
-**Mode: `error`**
-- Strict validation enabled
-- Raises errors if coverage is outdated
-- Perfect for CI/CD pipelines
+**`raise_on_stale: true`**
+- Raises errors when stale coverage is detected
+- Recommended for CI/CD enforcement
 
 ### File-Level Staleness
 
 A file is considered stale when any of the following are true:
-1. Source file modified after coverage generation
+1. Source file modified after coverage generation (requires timestamps - see [Timestamp Warnings](#timestamp-warnings))
 2. Line count differs from coverage array length
 3. File exists in coverage but deleted from filesystem
 
 **CLI Usage:**
 ```sh
-# Fail if any file is stale (option before subcommand)
-clp --staleness error summary app/models/order.rb
+# Fail if the file is stale
+clp -S true summary app/models/order.rb  # -S = --raise-on-stale
 ```
 
 **Ruby API:**
 ```ruby
 model = CovLoupe::CoverageModel.new(
-  staleness: 'error'
+  raise_on_stale: true
 )
 
 begin
@@ -119,30 +133,31 @@ end
 Detects system-wide staleness issues:
 
 **Conditions Checked:**
-1. **Newer files** - Any tracked file modified after coverage
+1. **Newer files** - Any tracked file modified after coverage (requires timestamps - see [Timestamp Warnings](#timestamp-warnings))
 2. **Missing files** - Tracked files with no coverage data
 3. **Deleted files** - Coverage exists for non-existent files
 
 **CLI Usage:**
-```sh
-# Track specific patterns
-clp --staleness error \
-  -g "lib/payments/**/*.rb" \
-  -g "lib/ops/jobs/**/*.rb"  # -g = --tracked-globs
 
-# Combine with JSON output for parsing
-clp --staleness error -fJ list > stale-check.json
+You can see if _any_ files in the project are stale by running the (implicit here) `list` command
+with `--raise-on-stale` and checking the exit code:
+
+```sh
+$ cov-loupe -S true list
+Coverage data stale (project): CovLoupe::CoverageDataProjectStaleError
+Coverage  - time: 2025-12-10T18:23:00Z (local 2025-12-11T02:23:00+08:00)
+Newer files (1):  - lib/cov_loupe/version.rb
+Resultset - /path/to/project/coverage/.resultset.json
+$ echo $?
+1
 ```
 
 **Ruby API:**
 ```ruby
-model = CovLoupe::CoverageModel.new(
-  staleness: 'error',
-  tracked_globs: ['lib/payments/**/*.rb', 'lib/ops/jobs/**/*.rb']
-)
+model = CovLoupe::CoverageModel.new(raise_on_stale: true)
 
 begin
-  files = model.all_files(check_stale: true)
+  model.list(raise_on_stale: true)
 rescue CovLoupe::CoverageDataProjectStaleError => e
   puts "Newer files: #{e.newer_files.join(', ')}"
   puts "Missing from coverage: #{e.missing_files.join(', ')}"
@@ -150,39 +165,62 @@ rescue CovLoupe::CoverageDataProjectStaleError => e
 end
 ```
 
-### Staleness in CI/CD
+### Timestamp Warnings
 
-Staleness checking is particularly useful in CI/CD pipelines to ensure coverage data is fresh:
+When coverage data lacks timestamps (e.g., manually created resultsets or older SimpleCov versions), cov-loupe displays a warning in both CLI and MCP modes:
 
-```sh
-# Run tests to generate coverage
-bundle exec rspec
+```
+WARNING: Coverage timestamps are missing. Time-based staleness checks were skipped.
+Files may appear "ok" even if source code is newer than the coverage data.
+Check your coverage tool configuration to ensure timestamps are recorded.
+```
 
-# Validate coverage freshness (fails with exit code 1 if stale)
-clp --staleness error -g "lib/**/*.rb"
+**What this means:**
+- Time-based staleness checks (the `"newer"` indicator) cannot run without timestamps
+- Files modified after coverage collection won't be flagged as stale
+- Only line count mismatches and missing files will be detected
+- The `timestamp_status` field in JSON output will show `"missing"` instead of `"ok"`
 
-# Export validated data for CI artifacts
-clp -fJ list > coverage.json
-```
+**Where it appears:**
+- **CLI table format:** After the coverage table in `list` output
+- **CLI JSON format:** After JSON output, and in the `timestamp_status` field
+- **MCP mode:** In `coverage_table_tool` output after the exclusions summary
+- **MCP JSON:** In the `timestamp_status` field of `list_tool` responses
+
+**How to fix:**
+
+Modern SimpleCov versions automatically include timestamps in `.resultset.json`. If you see this warning:
 
-The `--staleness error` flag causes the command to exit with a non-zero status when coverage is outdated, making it suitable for pipeline failure conditions.
+1. Ensure SimpleCov is up to date (`gem update simplecov`)
+2. Regenerate coverage data (`bundle exec rspec`)
+3. If using custom resultset generation, ensure timestamps are included
+
+**Example timestamp in `.resultset.json`:**
+```json
+{
+  "RSpec": {
+    "coverage": { ... },
+    "timestamp": 1704067200
+  }
+}
+```
 
 ---
 
 ## Advanced Path Resolution
 
-### Multi-Strategy Path Matching
+### Path Matching Strategy
 
-Path resolution order:
+Path resolution uses two strategies in order:
 
-1. **Exact absolute path match**
-2. **Relative path resolution from root**
+1. **Exact absolute path match** - Direct lookup using the full path
+2. **Relative path resolution** - Strips project root and retries with relative path
 
 ```ruby
-model = CovLoupe::CoverageModel.new(root: '/project')
+model = CovLoupe::CoverageModel.new(root: '/path/to/project')
 
-model.summary_for('/project/app/models/order.rb')  # Absolute
-model.summary_for('app/models/order.rb')           # Relative
+model.summary_for('/path/to/project/app/models/order.rb')  # Absolute
+model.summary_for('app/models/order.rb')                   # Relative
 ```
 
 ### Working with Multiple Projects
@@ -190,19 +228,19 @@ model.summary_for('app/models/order.rb')           # Relative
 ```ruby
 # Project A
 model_a = CovLoupe::CoverageModel.new(
-  root: '/projects/service-a',
-  resultset: '/projects/service-a/coverage/.resultset.json'
+  root: '/path/to/projects/service-a',
+  resultset: '/path/to/projects/service-a/coverage/.resultset.json'
 )
 
 # Project B
 model_b = CovLoupe::CoverageModel.new(
-  root: '/projects/service-b',
-  resultset: '/projects/service-b/tmp/coverage/.resultset.json'
+  root: '/path/to/projects/service-b',
+  resultset: '/path/to/projects/service-b/tmp/coverage/.resultset.json'
 )
 
 # Compare coverage
-coverage_a = model_a.all_files
-coverage_b = model_b.all_files
+coverage_a = model_a.list
+coverage_b = model_b.list
 ```
 
 
@@ -240,7 +278,7 @@ require 'cov_loupe'
 
 begin
   model = CovLoupe::CoverageModel.new(
-    root: '/project',
+    root: '/path/to/project',
     resultset: '/nonexistent/.resultset.json'
   )
 rescue CovLoupe::FileError => e
@@ -276,7 +314,13 @@ cli = CovLoupe::CoverageCLI.new(error_handler: CustomErrorHandler.new)
 
 ### Building Custom Coverage Policies
 
-Use the `validate` subcommand to enforce custom coverage policies in CI/CD. Example predicates are in [`examples/success_predicates/`](../../examples/success_predicates/).
+Use the `validate` subcommand to enforce custom coverage policies in CI/CD.
+Example predicates are in [`examples/success_predicates/`](../examples/success_predicates.md).
+
+The predicate can be any Ruby object that responds to `call` and accepts a `CoverageModel`
+as its argument. This is usually a lambda (proc), but it can also be a nonlambda proc, a class,
+or an instance with a `call` method. The predicate should return a truthy value for success 
+or `false`/`nil` for failure.
 
 > **⚠️ SECURITY WARNING**
 >
@@ -295,7 +339,7 @@ Use the `validate` subcommand to enforce custom coverage policies in CI/CD. Exam
 **Quick Usage:**
 ```sh
 # All files must be >= 80%
-clp validate examples/success_predicates/all_files_above_threshold_predicate.rb
+clp validate examples/success_predicates/list_above_threshold_predicate.rb
 
 # Total project coverage >= 85%
 clp validate examples/success_predicates/project_coverage_minimum_predicate.rb
@@ -304,7 +348,7 @@ clp validate examples/success_predicates/project_coverage_minimum_predicate.rb
 clp validate coverage_policy.rb
 
 # Inline string mode
-clp validate -i '->(m) { m.all_files.all? { |f| f["percentage"] >= 80 } }'
+clp validate -i '->(m) { m.list["files"].all? { |f| f["percentage"] >= 80 } }'
 ```
 
 **Creating a predicate:**
@@ -312,7 +356,7 @@ clp validate -i '->(m) { m.all_files.all? { |f| f["percentage"] >= 80 } }'
 # coverage_policy.rb
 ->(model) do
   # All files must have >= 80% coverage
-  model.all_files.all? { |f| f['percentage'] >= 80 }
+  model.list['files'].all? { |f| f['percentage'] >= 80 }
 end
 ```
 
@@ -323,7 +367,7 @@ end
 class CoveragePolicy
   def call(model)
     threshold = 80
-    low_files = model.all_files.select { |f| f['percentage'] < threshold }
+    low_files = model.list['files'].select { |f| f['percentage'] < threshold }
 
     if low_files.empty?
       puts "✓ All files have >= #{threshold}% coverage"
@@ -344,26 +388,27 @@ CoveragePolicy.new
 - `1` - Predicate returned falsy (fail)
 - `2` - Predicate raised an error
 
-See [examples/success_predicates/README.md](../../examples/success_predicates/README.md) for more examples.
+See [examples/success_predicates/README.md](../examples/success_predicates.md) for more examples.
 
 ### Path Relativization
 
 Convert absolute paths to relative for cleaner output:
 
 ```ruby
-model = CovLoupe::CoverageModel.new(root: '/project')
+model = CovLoupe::CoverageModel.new(root: '/path/to/project')
 
 # Get data with absolute paths
 data = model.summary_for('app/models/order.rb')
-# => { 'file' => '/project/app/models/order.rb', ... }
+# => { 'file' => '/path/to/project/app/models/order.rb', ... }
 
 # Relativize paths
 relative_data = model.relativize(data)
 # => { 'file' => 'app/models/order.rb', ... }
 
-# Works with arrays too
-files = model.all_files
-relative_files = model.relativize(files)
+# Works with list payloads too
+list_result = model.list
+relative_list = model.relativize(list_result)
+relative_files = relative_list['files']
 ```
 
 ---
@@ -376,7 +421,7 @@ The CLI is designed for CI/CD use with features that integrate naturally into pi
 
 - **Exit codes**: Non-zero on failure, making it suitable for pipeline failure conditions
 - **JSON output**: `-fJ` format for parsing by CI tools and custom processing
-- **Staleness checking**: `--stale error` to fail on outdated coverage data
+- **Staleness checking**: `--raise-on-stale true` to fail on outdated coverage data
 - **Success predicates**: Custom Ruby policies for coverage enforcement
 
 ### Basic CI Pattern
@@ -386,7 +431,7 @@ The CLI is designed for CI/CD use with features that integrate naturally into pi
 bundle exec rspec
 
 # 2. Validate coverage freshness (fails with exit code 1 if stale)
-clp --staleness error -g "lib/**/*.rb"
+clp -S true -g "lib/**/*.rb"
 
 # 3. Export data for CI artifacts or further processing
 clp -fJ list > coverage.json
@@ -419,37 +464,67 @@ For platform-specific integration examples (GitHub Actions, GitLab CI, Jenkins,
 
 ### Tracked Globs Overview
 
-Tracked globs serve two purposes:
-1. **Filter output** - Only show matching files
-2. **Validate coverage** - Ensure new files have coverage
+**Default behavior:** By default, `--tracked-globs` is empty (`[]`), which means all files in the coverage resultset are shown. This ensures transparency—you see exactly what SimpleCov measured without any filtering.
+
+**Why opt-in filtering?**
+- **Coverage results are not hidden** - Results are not excluded because their filespecs did not match default tracked globs
+- **Meaningful validation** - `missing_tracked_files` only flags files you explicitly expect to have coverage
+- **Project flexibility** - Different projects use different directory structures
+
+**Important:** Files lacking any coverage at all (not loaded during tests) will not appear in the resultset and therefore won't be visible with the default empty array. To detect such files, you must set `--tracked-globs` to match the files you expect to have coverage.
+
+**Two purposes of tracked globs:**
+1. **Exclude unwanted results** - Only show files from the resultset that match the patterns
+2. **Include files with or without coverage** - Report files that match the patterns but aren't in the resultset (reported in `missing_tracked_files` for `list`, `missing_from_coverage` for `totals`)
+
+**Best practice:** Set `COV_LOUPE_OPTS` to match your SimpleCov `track_files` configuration:
+
+```ruby
+# spec_helper.rb
+SimpleCov.start do
+  add_filter '/spec/'
+  track_files 'lib/**/*.rb'
+  track_files 'app/**/*.rb'
+end
+```
+
+```sh
+# Shell config (.bashrc, .zshrc, etc.)
+export COV_LOUPE_OPTS="--tracked-globs lib/**/*.rb,app/**/*.rb"
+```
+
+This alignment ensures:
+- `list` and `totals` output matches SimpleCov's scope
+- `missing_tracked_files` (in `list`) reports files that SimpleCov should track but hasn't measured
+- No surprises from default patterns that don't match your project
 
 ### Pattern Syntax
 
 Uses Ruby's `File.fnmatch` with extended glob support:
 
 ```sh
-# Single directory
---tracked-globs "lib/**/*.rb"
+# Single directory, recursive
+-g "lib/**/*.rb"
 
 # Multiple patterns
---tracked-globs "lib/payments/**/*.rb" --tracked-globs "lib/ops/jobs/**/*.rb"
+-g "lib/payments/**/*.rb" -g "lib/ops/jobs/**/*.rb"
 
-# Exclude patterns (use CLI filtering)
-clp -fJ list | jq '.files[] | select(.file | test("spec") | not)'
+# Exclude patterns (use CLI filtering to exclude ops jobs)
+clp -fJ list | jq '.files[] | select(.file | test("ops") | not)'
 
 # Ruby alternative:
 clp -fJ list | ruby -r json -e '
-  JSON.parse($stdin.read)["files"].reject { |f| f["file"].include?("spec") }.each do |f|
+  JSON.parse($stdin.read)["files"].reject { |f| f["file"].include?("ops") }.each do |f|
     puts JSON.pretty_generate(f)
   end
 '
 
 # Rexe alternative:
-clp -fJ list | rexe -ij -mb -oJ 'self["files"].reject { |f| f["file"].include?("spec") }'
+clp -fJ list | rexe -ij -mb -oJ 'self["files"].reject { |f| f["file"].include?("ops") }'
 
 # Complex patterns
---tracked-globs "lib/{models,controllers}/**/*.rb"
---tracked-globs "app/**/concerns/*.rb"
+-g "lib/{models,controllers}/**/*.rb"
+-g "app/**/concerns/*.rb"
 ```
 
 ### Use Cases
@@ -466,7 +541,7 @@ clp -g "lib/domain/**/*.rb" list
 **2. Ensure New Files Have Coverage:**
 ```sh
 # Fail if any tracked file lacks coverage
-clp --staleness error -g "lib/features/**/*.rb"
+clp -S true -g "lib/features/**/*.rb"
 ```
 
 **3. Multi-tier Reporting:**
@@ -483,22 +558,22 @@ done
 model = CovLoupe::CoverageModel.new
 
 # Filter files in output
-api_files = model.all_files(
+api_files = model.list(
   tracked_globs: ['lib/api/**/*.rb']
-)
+)['files']
 
 # Multi-pattern filtering
-core_files = model.all_files(
+core_files = model.list(
   tracked_globs: [
     'lib/core/**/*.rb',
     'lib/domain/**/*.rb'
   ]
-)
+)['files']
 
 # Validate specific subsystems
 begin
-  model.all_files(
-    check_stale: true,
+  model.list(
+    raise_on_stale: true,
     tracked_globs: ['lib/critical/**/*.rb']
   )
 rescue CovLoupe::CoverageDataProjectStaleError => e
@@ -519,13 +594,13 @@ The `CoverageModel` reads `.resultset.json` once at initialization:
 ```ruby
 # Good: Single model for multiple queries
 model = CovLoupe::CoverageModel.new
-files = model.all_files
+files = model.list['files']
 file1 = model.summary_for('lib/a.rb')
 file2 = model.summary_for('lib/b.rb')
 
 # Bad: Re-reads coverage for each operation
 model1 = CovLoupe::CoverageModel.new
-files = model1.all_files
+files = model1.list['files']
 
 model2 = CovLoupe::CoverageModel.new
 file1 = model2.summary_for('lib/a.rb')
@@ -554,13 +629,13 @@ Use `tracked_globs` to reduce data processing:
 
 ```ruby
 # Bad: Filter after loading all data
-all_files = model.all_files
-api_files = all_files.select { |f| f['file'].include?('api') }
+list = model.list['files']
+api_files = list.select { |f| f['file'].include?('api') }
 
 # Good: Filter during query
-api_files = model.all_files(
+api_files = model.list(
   tracked_globs: ['lib/api/**/*.rb']
-)
+)['files']
 ```
 
 ### Caching Coverage Models
@@ -591,7 +666,7 @@ class CoverageCache
 end
 
 cache = CoverageCache.new
-model = cache.model_for('/project')
+model = cache.model_for('/path/to/project')
 ```
 
 ---
@@ -605,7 +680,7 @@ model = cache.model_for('/project')
 require 'csv'
 
 model = CovLoupe::CoverageModel.new
-files = model.all_files
+files = model.list['files']
 
 CSV.open('coverage.csv', 'w') do |csv|
   csv << ['File', 'Coverage %', 'Lines Covered', 'Total Lines', 'Stale']
@@ -648,7 +723,9 @@ template = ERB.new(<<~HTML)
 HTML
 
 model = CovLoupe::CoverageModel.new
-files = model.relativize(model.all_files)
+list_result = model.list
+relative_list = model.relativize(list_result)
+files = relative_list['files']
 File.write('coverage.html', template.result(binding))
 ```
 
@@ -659,13 +736,13 @@ The CLI supports annotated source viewing:
 ```sh
 # Show uncovered lines with context
 clp uncovered app/models/order.rb \
-  --source uncovered \
-  --source-context 3
+  -s uncovered \
+  -c 3  # -s = --source, -c = --context-lines
 
 # Show full file with coverage annotations
 clp uncovered app/models/order.rb \
-  --source full \
-  --source-context 0
+  -s full \
+  -c 0
 ```
 
 **Programmatic Source Annotation:**
@@ -748,7 +825,7 @@ require 'net/http'
 require 'json'
 
 model = CovLoupe::CoverageModel.new
-files = model.all_files
+files = model.list['files']
 
 coveralls_data = {
   repo_token: ENV['COVERALLS_REPO_TOKEN'],
@@ -768,6 +845,22 @@ Net::HTTP.post(uri, coveralls_data.to_json, {
 
 ---
 
+## Multi-Suite Coverage Merging
+
+### How It Works
+
+When a `.resultset.json` file contains multiple test suites (e.g., RSpec + Cucumber), `cov-loupe` automatically merges them using SimpleCov's combine logic. All covered files from every suite become available to the CLI, library, and MCP tools.
+
+**Performance:** Single-suite projects avoid loading SimpleCov at runtime. Multi-suite resultsets trigger a lazy SimpleCov load only when needed, keeping the tool fast for the simpler coverage configurations.
+
+### Current Limitations
+
+**Staleness checks:** When suites are merged, we keep a single "latest suite" timestamp. This matches prior behavior but may under-report stale files if only some suites were re-run after a change. Use `--raise-on-stale` (or `-S`) on the CLI, `raise_on_stale: true` via the Ruby API, or the MCP tool parameter to turn these warnings into hard failures. A per-file timestamp refinement is planned; until then, treat multi-suite staleness flags as advisory rather than definitive.
+
+**Multiple resultset files:** Only suites stored inside a *single* `.resultset.json` are merged automatically. If your project produces separate resultset files (e.g., different CI jobs writing `coverage/job1/.resultset.json`, `coverage/job2/.resultset.json`), you must merge them yourself before pointing `cov-loupe` at the combined file.
+
+---
+
 ## Additional Resources
 
 - [CLI Usage Guide](CLI_USAGE.md)

data/docs/user/CLI_FALLBACK_FOR_LLMS.md

@@ -1,5 +1,7 @@
 # CLI Fallback for LLMs
 
+[Back to main README](../index.md)
+
 When the MCP server integration isn't working or available, LLMs can use the `cov-loupe` CLI directly with the `-fJ` flag to get the same coverage data that the MCP tools provide.
 
 ## Overview