cov-loupe 3.0.0 → 4.0.0.pre

data/docs/dev/arch-decisions/path-resolution.md

@@ -0,0 +1,90 @@
+# Path Resolution Strategy
+
+[Back to ADR Index](README.md)
+
+## Cross-OS Coverage Data Support
+
+### Status
+**Accepted** (2025-12-26)
+
+### Context
+
+SimpleCov's `.resultset.json` files contain file paths as keys in the coverage data hash. These paths are typically absolute paths from the machine where tests were run. Different operating systems use different path separators:
+- Unix/Linux/macOS: `/`
+- Windows: `\` (backslash)
+
+Early versions of cov-loupe included path normalization logic that converted backslashes to forward slashes, enabling cross-platform path matching. This was motivated by a theoretical use case: analyzing a `.resultset.json` file generated on one OS (e.g., Windows) on a different OS (e.g., Linux/macOS).
+
+Upon closer examination, this cross-OS scenario is unrealistic for several reasons:
+
+1. **CI/CD workflows** – While coverage files might be generated in CI (often Linux), developers typically either:
+   - Re-run tests locally to generate fresh coverage
+   - View coverage reports rendered by SimpleCov's HTML formatter
+   - Use hosted coverage services (Codecov, Coveralls)
+
+2. **Docker development** – When tests run in containers, volume mounting ensures paths already match the host environment
+
+3. **Path structure differences** – Cross-OS paths differ in more ways than just separators (drive letters, root paths, etc.), making simple separator normalization insufficient
+
+4. **Same-machine path variations** – The legitimate use case is handling different working directories or relative vs absolute paths on the *same* machine, not across different OSes
+
+### Decision
+
+**Do not support analyzing `.resultset.json` files across different operating systems.**
+
+Specifically:
+- Normalize backslashes to forward slashes on Windows only
+- Apply case-insensitive path matching on Windows (filesystem is case-insensitive)
+- Apply case-sensitive path matching on Unix (filesystem is case-sensitive)
+- Keep path resolution focused on same-OS scenarios:
+  - Exact absolute path matching
+  - Relative path matching (stripping project root)
+- Trust that paths in coverage data use the native separator for the OS where cov-loupe runs
+
+### Consequences
+
+**Benefits:**
+- **Simpler code** – No need for path separator normalization logic
+- **Clearer semantics** – Path matching behavior is more predictable
+- **Fewer edge cases** – No ambiguity around mixed separator styles
+- **Honest API** – We don't promise cross-OS compatibility we can't fully deliver
+
+**Trade-offs:**
+- Users cannot analyze Windows `.resultset.json` files on Linux/macOS or vice versa
+  - This is acceptable because this scenario is impractical anyway
+  - Users who encounter this should re-run tests in their current environment
+
+**No impact on:**
+- Same-OS path resolution (absolute, relative)
+- Normal development workflows
+- CI/CD integration
+- Docker/container-based development
+
+### Implementation
+
+Path normalization is centralized in the `PathUtils` module (`lib/cov_loupe/path_utils.rb`). It handles:
+- Normalizing path separators (backslashes to forward slashes on Windows)
+- Case normalization for case-insensitive volumes (autodetected or explicit)
+- Path cleaning
+
+`CoverageLineResolver` delegates all path normalization to `PathUtils.normalize`, avoiding scattered platform checks and keeping the resolver logic focused on lookup strategies.
+
+#### Path Comparison Strategy
+
+Path comparison uses a **normalize-for-comparison-only** approach rather than normalize-and-store:
+
+- **Original paths are preserved** - `PathUtils.expand` preserves the original case to avoid corrupting displayed file paths
+- **Normalization happens at comparison time** - The `normalized_start_with?` helper method normalizes both paths internally for comparison but doesn't modify the originals
+- **Boundary checking** - Prevents false matches where a path starts with a prefix string but isn't actually within that directory (e.g., `/home/user/project` should not match `/home/user/project-backup/file.rb`)
+
+This approach ensures:
+1. User-visible paths maintain original casing for better UX
+2. Path matching works correctly on case-insensitive volumes (Windows, most macOS)
+3. Mixed path separators (forward slash vs backslash) are handled transparently
+4. Directory boundary checking prevents incorrect prefix matches
+
+### References
+
+- Implementation: `lib/cov_loupe/resolvers/coverage_line_resolver.rb` (delegates to `PathUtils`)
+- Central Logic: `lib/cov_loupe/path_utils.rb`
+- Related tests removed: `spec/resolvers/coverage_line_resolver_spec.rb` (cross-OS separator normalization context)

data/docs/dev/arch-decisions/{004-x-arch-decision.md → policy-validation.md}

@@ -1,14 +1,18 @@
-# ADR 004: Ruby `instance_eval` for Success Predicates
+# Policy Validation
 
-[Back to main README](../../README.md)
+[Back to main README](../../index.md)
 
-## Status
+This document describes how cov-loupe allows users to define and enforce custom coverage policies through success predicates.
+
+## Ruby `instance_eval` for Success Predicates
+
+### Status
 
 Accepted
 
-## Context
+### Context
 
-SimpleCov MCP needed a mechanism for users to define custom coverage policies beyond simple percentage thresholds. Different projects have different requirements:
+cov-loupe needed a mechanism for users to define custom coverage policies beyond simple percentage thresholds. Different projects have different requirements:
 
 - Some want all files above 80%, others allow a few files below threshold
 - Some need different thresholds for different directories (e.g., 90% for API code, 60% for legacy)
@@ -22,7 +26,7 @@ We considered several approaches:
 3. **Ruby file evaluation**: Load and execute arbitrary Ruby code that returns a callable predicate
 4. **Sandboxed DSL**: Use a restricted Ruby environment (e.g., `$SAFE` levels, isolated VMs)
 
-### Key Requirements
+#### Key Requirements
 
 - Flexibility: Support arbitrarily complex coverage policies
 - Simplicity: Easy for users to write and understand
@@ -30,7 +34,7 @@ We considered several approaches:
 - CI/CD integration: Clear exit codes (0 = pass, 1 = fail, 2 = error)
 - Access to coverage data: Predicates need access to the full `CoverageModel` API
 
-### Why Not a Custom DSL?
+#### Why Not a Custom DSL?
 
 A custom DSL would be:
 - Limited in expressiveness (hard to predict all future use cases)
@@ -38,7 +42,7 @@ A custom DSL would be:
 - More maintenance burden (parsing, validation, documentation)
 - Still vulnerable to injection if it allowed any dynamic computation
 
-### Why Not Sandboxing?
+#### Why Not Sandboxing?
 
 Ruby's sandboxing options are limited:
 - `$SAFE` levels were deprecated and removed in Ruby 2.7+
@@ -46,13 +50,13 @@ Ruby's sandboxing options are limited:
 - Any Turing-complete sandbox can be escaped given enough effort
 - True security requires not executing untrusted code at all
 
-## Decision
+### Decision
 
 We chose to **evaluate Ruby files using `instance_eval`** with prominent security warnings rather than attempting to create a false sense of security through incomplete sandboxing.
 
-### Implementation
+#### Implementation
 
-The implementation is in `lib/cov_loupe/cli.rb:191-214`:
+The implementation is in `lib/cov_loupe/cli.rb` (`CoverageCLI#load_success_predicate`):
 
 ```ruby
 def load_success_predicate(path)
@@ -97,11 +101,11 @@ rescue => e
 end
 ```
 
-### Security Model: Treat as Executable Code
+#### Security Model: Treat as Executable Code
 
 Rather than pretending to sandbox untrusted code, we treat success predicates **exactly like any other Ruby code in the project**:
 
-1. **Prominent warnings** in documentation (examples/success_predicates/README.md:5-17):
+1. **Prominent warnings** in documentation (highlighted near the top of `examples/success_predicates/README.md`):
    ```
    ⚠️ SECURITY WARNING
 
@@ -116,14 +120,14 @@ Rather than pretending to sandbox untrusted code, we treat success predicates **
 3. **CI/CD best practices**: Same permissions model as running tests themselves
 4. **Example predicates**: Well-documented examples showing safe patterns
 
-### Predicate API
+#### Predicate API
 
 Success predicates must be callable (lambda, proc, or object with `#call` method):
 
 **Lambda example:**
 ```ruby
 ->(model) do
-  model.all_files.all? { |f| f['percentage'] >= 80 }
+  model.list.all? { |f| f['percentage'] >= 80 }
 end
 ```
 
@@ -133,7 +137,7 @@ end
 
 class CoveragePolicy
   def call(model)
-    api_files = model.all_files.select { |f| f['file'].start_with?('lib/api/') }
+    api_files = model.list['files'].select { |f| f['file'].start_with?('lib/api/') }
     api_files.all? { |f| f['percentage'] >= 90 }
   end
 end
@@ -142,14 +146,14 @@ AllFilesAboveThreshold.new
 ```
 
 The predicate receives a full `CoverageModel` instance with access to:
-- `all_files(tracked_globs:, sort_order:)` - All file coverage data
+- `list(tracked_globs:, sort_order:)` - All file coverage data
 - `summary_for(path)` - Coverage summary for a specific file
 - `uncovered_for(path)` - Uncovered lines for a specific file
 - `detailed_for(path)` - Per-line coverage data
 
-## Consequences
+### Consequences
 
-### Positive
+#### Positive
 
 1. **Maximum flexibility**: Users can express arbitrarily complex coverage policies using full Ruby
 2. **Familiar tooling**: Users can debug predicates with standard Ruby tools (pry, byebug, etc.)
@@ -158,20 +162,20 @@ The predicate receives a full `CoverageModel` instance with access to:
 5. **Composability**: Users can require other libraries, define helper methods, etc.
 6. **Excellent examples**: We provide 5+ well-documented example predicates
 
-### Negative
+#### Negative
 
 1. **Security responsibility**: Users must understand the security implications
 2. **Potential misuse**: Users might mistakenly trust untrusted predicate files
 3. **No isolation**: Buggy predicates can access/modify anything in the system
 4. **Documentation burden**: Must clearly communicate security model
 
-### Trade-offs
+#### Trade-offs
 
 - **Versus custom DSL**: More powerful and debuggable, but requires user awareness of security
 - **Versus plugin architecture**: Simpler (no gem dependencies, no protocol to learn), but same security profile
 - **Versus incomplete sandboxing**: Honest about capabilities rather than security theater
 
-### Threat Model
+#### Threat Model
 
 This approach is **appropriate** when:
 - Predicate files are stored in version control with code review
@@ -183,7 +187,7 @@ This approach is **inappropriate** when:
 - Allowing users to upload predicates via web interface
 - Running in a multi-tenant environment without isolation
 
-### Future Considerations
+#### Future Considerations
 
 If demand arises for truly untrusted predicate execution, alternatives include:
 
@@ -193,11 +197,11 @@ If demand arises for truly untrusted predicate execution, alternatives include:
 
 However, for the primary use case (CI/CD policy enforcement), the current approach is simpler and more flexible than these alternatives.
 
-## References
+### References
 
-- Implementation: `lib/cov_loupe/cli.rb:191-214` (load predicate), `lib/cov_loupe/cli.rb:179-189` (execute)
-- Security warnings: `examples/success_predicates/README.md:5-17`
+- Implementation: `lib/cov_loupe/cli.rb` (`CoverageCLI#load_success_predicate` and `#run_success_predicate`)
+- Security warnings: `examples/success_predicates/README.md`
 - Example predicates: `examples/success_predicates/*.rb`
 - CoverageModel API: `lib/cov_loupe/model.rb`
-- CLI config: `lib/cov_loupe/cli_config.rb:18` (success_predicate field)
-- Option parsing: `lib/cov_loupe/option_parser_builder.rb` (--success-predicate flag)
+- CLI config: `lib/cov_loupe/cli_config.rb` (`success_predicate` field)
+- Option parsing: `lib/cov_loupe/option_parser_builder.rb` (`--success-predicate` flag)

data/docs/dev/arch-decisions/{005-x-arch-decision.md → simplecov-integration.md}

@@ -1,22 +1,26 @@
-# ADR 005: No SimpleCov Runtime Dependency
+# SimpleCov Integration
 
-[Back to main README](../../README.md)
+[Back to main README](../../index.md)
 
-## Status
+This document describes how cov-loupe integrates with SimpleCov and manages its dependency on the SimpleCov gem.
 
-Replaced – cov-loupe now requires SimpleCov at runtime so that multi-suite resultsets can be merged using SimpleCov’s combine helpers.
+## SimpleCov Runtime Dependency
 
-## Context
+### Status
 
-SimpleCov MCP provides tooling for inspecting SimpleCov coverage reports. When designing the gem, we had to decide whether to depend on SimpleCov as a runtime dependency.
+**Replaced** – cov-loupe now requires SimpleCov at runtime so that multi-suite resultsets can be merged using SimpleCov's combine helpers.
 
-### Alternative Approaches
+### Original Context
+
+cov-loupe provides tooling for inspecting SimpleCov coverage reports. When designing the gem, we had to decide whether to depend on SimpleCov as a runtime dependency.
+
+#### Alternative Approaches
 
 1. **Runtime dependency on SimpleCov**: Use SimpleCov's API to read and process coverage data
 2. **Development-only dependency**: Read SimpleCov's `.resultset.json` files directly without requiring SimpleCov at runtime
 3. **Support multiple coverage formats**: Parse coverage data from multiple tools (SimpleCov, Coverage, etc.)
 
-### Key Considerations
+#### Key Considerations
 
 **Dependency weight**: SimpleCov itself has dependencies:
 - `docile` (~> 1.1)
@@ -25,7 +29,7 @@ SimpleCov MCP provides tooling for inspecting SimpleCov coverage reports. When d
 
 **Use case separation**:
 - SimpleCov is needed when **running tests** to collect coverage
-- SimpleCov MCP is needed when **inspecting coverage** after tests complete
+- cov-loupe is needed when **inspecting coverage** after tests complete
 - These are temporally separated activities
 
 **Deployment contexts**:
@@ -38,33 +42,32 @@ SimpleCov MCP provides tooling for inspecting SimpleCov coverage reports. When d
 - The format is simple JSON with predictable structure
 - Breaking changes would affect all SimpleCov users, so the format is unlikely to change
 
-## Decision
+### Original Decision
 
-We chose to **make SimpleCov a development dependency only** and read `.resultset.json` files directly using Ruby's standard library JSON parser.
+We initially chose to **make SimpleCov a development dependency only** and read `.resultset.json` files directly using Ruby's standard library JSON parser.
 
-### Implementation
+### Revision: SimpleCov as Runtime Dependency
 
-The gem only depends on `mcp` at runtime (cov-loupe.gemspec:26):
-```ruby
-# Runtime deps (stdlib: json, time, pathname)
-spec.add_runtime_dependency 'mcp', '~> 0.3'
-spec.add_development_dependency 'simplecov', '~> 0.21'
-```
+cov-loupe now depends on SimpleCov at runtime for the following reasons:
+
+1. **Multi-suite merging**: Projects using multiple test suites (e.g., RSpec + Minitest) produce separate coverage results that must be merged using SimpleCov's `SimpleCov::ResultMerger.merge_results`
+2. **Consistent calculations**: SimpleCov's coverage percentage algorithms handle edge cases that are difficult to replicate correctly
+3. **Format compatibility**: Changes to SimpleCov's internal data structures are automatically handled by using its API
+
+### Current Implementation
+
+cov-loupe currently depends on `amazing_print`, `mcp`, and `simplecov` at runtime.
 
-Coverage data is read directly from JSON files (lib/cov_loupe/model.rb:34-42):
+Coverage data is read directly from JSON files by `CovLoupe::CoverageModel#load_coverage_data`:
 ```ruby
-rs = CovUtil.find_resultset(@root, resultset: resultset)
-raw = JSON.parse(File.read(rs))
-# SimpleCov typically writes a single test suite entry to .resultset.json
-# Find the first entry that has coverage data (skip comment entries)
-_suite, data = raw.find { |k, v| v.is_a?(Hash) && v.key?('coverage') }
-raise "No test suite with coverage data found in resultset file: #{rs}" unless data
-cov = data['coverage'] or raise "No 'coverage' key found in resultset file: #{rs}"
-@cov = cov.transform_keys { |k| File.absolute_path(k, @root) }
-@cov_timestamp = (data['timestamp'] || data['created_at'] || 0).to_i
+rs = Resolvers::ResolverHelpers.find_resultset(@root, resultset: resultset)
+loaded = ResultsetLoader.load(resultset_path: rs)
+coverage_map = loaded.coverage_map or raise(CoverageDataError, "No 'coverage' key found in resultset file: #{rs}")
+@cov = coverage_map.transform_keys { |k| File.absolute_path(k, @root) }
+@cov_timestamp = loaded.timestamp
 ```
 
-Coverage calculations use simple algorithms (lib/cov_loupe/util.rb:42-71):
+Coverage calculations use simple algorithms in `CovLoupe::CoverageCalculator` (`summary`, `uncovered`, `detailed`):
 ```ruby
 def summary(arr)
   total = 0
@@ -121,9 +124,9 @@ Where:
 
 ### Resultset Discovery
 
-We implement flexible discovery of `.resultset.json` files (lib/cov_loupe/util.rb:6-10):
+We implement flexible discovery of `.resultset.json` files via `Resolvers::ResultsetPathResolver::DEFAULT_CANDIDATES`:
 ```ruby
-RESULTSET_CANDIDATES = [
+DEFAULT_CANDIDATES = [
   '.resultset.json',
   'coverage/.resultset.json',
   'tmp/.resultset.json'
@@ -132,9 +135,9 @@ RESULTSET_CANDIDATES = [
 
 This supports common SimpleCov configurations without requiring SimpleCov to be loaded.
 
-## Consequences
+### Consequences
 
-### Positive
+#### Positive (Original Development-Only Approach)
 
 1. **Lightweight installation**: No transitive dependencies beyond `mcp` gem
 2. **Deployment flexibility**: Can analyze coverage in environments without test dependencies
@@ -143,7 +146,7 @@ This supports common SimpleCov configurations without requiring SimpleCov to be
 5. **CI/CD optimization**: Analysis jobs don't need full test suite dependencies
 6. **Production-safe**: Can be deployed to production environments if needed (e.g., for monitoring)
 
-### Negative
+#### Negative (Original Development-Only Approach)
 
 1. **Format dependency**: Tightly coupled to SimpleCov's JSON format
 2. **Breaking changes risk**: If SimpleCov changes `.resultset.json` structure, we must adapt
@@ -151,18 +154,18 @@ This supports common SimpleCov configurations without requiring SimpleCov to be
 4. **Duplicate logic**: Coverage percentage calculations reimplemented (though simple)
 5. **Maintenance**: Must track SimpleCov format changes manually
 
-### Trade-offs
+#### Trade-offs (Current Runtime Dependency Approach)
 
-- **Versus runtime dependency**: Lighter weight but less resilient to format changes
+- **Versus development-only dependency**: Heavier installation footprint, but better multi-suite support and format compatibility
 - **Versus multi-format support**: Simpler implementation but locked to SimpleCov ecosystem
-- **Versus using SimpleCov API**: More flexible deployment but requires understanding the file format
+- **Versus custom merging logic**: More reliable but requires SimpleCov at runtime
 
 ### Risk Mitigation
 
 1. **Format stability**: SimpleCov has maintained `.resultset.json` compatibility for years
 2. **Simple format**: JSON structure is straightforward and unlikely to change dramatically
 3. **Development dependency**: We still use SimpleCov in our own tests, so format changes would be detected immediately
-4. **Documentation**: CLAUDE.md documents the format dependency explicitly
+4. **Documentation**: AGENTS.md documents the format dependency explicitly
 5. **Error handling**: Robust error messages when format doesn't match expectations
 
 ### Format Evolution Strategy
@@ -176,14 +179,14 @@ If SimpleCov's format changes:
 
 - Only supports SimpleCov (not Coverage gem, other tools)
 - Assumes standard `.resultset.json` locations
-- No support for merged coverage from multiple test runs (SimpleCov handles this before writing JSON)
+- Multi-suite merging requires SimpleCov runtime dependency
 - No support for branch coverage (SimpleCov feature not widely used yet)
 
-## References
+### References
 
-- Gemspec dependencies: `cov-loupe.gemspec:26-28`
-- JSON parsing: `lib/cov_loupe/model.rb:34-57`
-- Coverage calculations: `lib/cov_loupe/util.rb:42-71`
-- Resultset discovery: `lib/cov_loupe/util.rb:6-10`, `lib/cov_loupe/util.rb:34-36`
+- Gemspec dependencies: `cov-loupe.gemspec` (`spec.add_dependency` entries)
+- JSON parsing: `lib/cov_loupe/resultset_loader.rb` (`ResultsetLoader.load`)
+- Coverage calculations: `lib/cov_loupe/coverage_calculator.rb` (`CoverageCalculator.summary`, `.uncovered`, `.detailed`)
+- Resultset discovery: `lib/cov_loupe/resolvers/resultset_path_resolver.rb` (`ResultsetPathResolver::DEFAULT_CANDIDATES`)
 - SimpleCov format documentation: https://github.com/simplecov-ruby/simplecov
 - Development usage: Uses SimpleCov in `spec/spec_helper.rb` to test itself

data/docs/dev/presentations/cov-loupe-presentation.md

@@ -1,4 +1,4 @@
-[Back to main README](../../README.md)
+[Back to main README](../../index.md)
 
 ---
 marp: true
@@ -9,7 +9,7 @@ backgroundColor: #fff
 color: #333
 ---
 
-# SimpleCovMCP
+# CovLoupe
 ### MCP Server, CLI, and Library for SimpleCov Ruby Test Coverage 
 
 - Keith Bennett
@@ -17,7 +17,7 @@ color: #333
 
 ---
 
-## What is SimpleCov MCP?
+## What is cov-loupe?
 
 A **three-in-one** gem that makes SimpleCov coverage data accessible to:
 
@@ -59,7 +59,7 @@ This code base requires a Ruby version >= 3.2.0, because this is required by the
 
 ```bash
 # Test the MCP server manually
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"lib/cov_loupe/model.rb"}}}' | cov-loupe
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"lib/cov_loupe/model.rb"}}}' | cov-loupe -m mcp
 ```
 
 **What AI agents can do:**
@@ -73,12 +73,13 @@ echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"coverage_s
 
 | Tool                      | Purpose                    | Example CLI Command                                  |
 |---------------------------|----------------------------|------------------------------------------------------|
-| `all_files_coverage_tool` | Project-wide coverage data | `cov-loupe list`                                 |
+| `list_tool` | Project-wide coverage data | `cov-loupe list`                                 |
 | `coverage_detailed_tool`  | Per-line hit counts        | `cov-loupe detailed lib/cov_loupe/model.rb`  |
 | `coverage_raw_tool`       | Raw SimpleCov lines array  | `cov-loupe raw lib/cov_loupe/model.rb`       |
 | `coverage_summary_tool`   | Get coverage % for a file  | `cov-loupe summary lib/cov_loupe/model.rb`   |
 | `coverage_table_tool`     | Formatted coverage table   | `cov-loupe list`                                 |
 | `coverage_totals_tool`    | Aggregated line totals     | `cov-loupe totals`                               |
+| `validate_tool`           | Validate coverage policy   | `cov-loupe validate coverage_policy.rb`          |
 | `help_tool`               | Tool usage guidance        | `cov-loupe --help`                               |
 | `uncovered_lines_tool`    | Find missing test coverage | `cov-loupe uncovered lib/cov_loupe/cli.rb`   |
 | `version_tool`            | Display version info       | `cov-loupe version`                              |
@@ -89,14 +90,14 @@ echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"coverage_s
 ### 
 
 ```bash
-# Show all files, worst coverage first
+# Show all files, best coverage first
 cov-loupe
 
 # Focus on a specific file
 cov-loupe summary lib/cov_loupe/cli.rb
 
 # Find untested lines with source context
-cov-loupe uncovered lib/cov_loupe/cli.rb --source=uncovered --source-context 3
+cov-loupe uncovered lib/cov_loupe/cli.rb --source=uncovered --context-lines 3
 
 # JSON for scripts
 cov-loupe -fJ | jq '.files[] | select(.percentage < 80)'
@@ -124,7 +125,7 @@ cov-loupe --resultset coverage-all/
 cov-loupe --sort-order d
 
 # Staleness checking (file newer than coverage?)
-cov-loupe --staleness error
+cov-loupe --raise-on-stale true
 
 # Track new files missing from coverage
 cov-loupe --tracked-globs "lib/**/tools/*.rb"
@@ -141,7 +142,7 @@ require 'cov_loupe'
 model = CovLoupe::CoverageModel.new
 
 # Get project overview
-files = model.all_files
+files = model.list
 puts "Lowest coverage: #{files.first['percentage']}%"
 
 # Focus on specific concerns
@@ -162,7 +163,7 @@ puts "Missing lines: #{uncovered['uncovered'].inspect}"
 ```ruby
 require 'cov_loupe'
 
-files = CovLoupe::CoverageModel.new.all_files
+files = CovLoupe::CoverageModel.new.list
 critical, other = files.partition { |f| f['file'].include?('/lib/critical/') }
 
 fails = critical.select { |f| f['percentage'] < 100.0 } + 
@@ -192,18 +193,19 @@ lib/cov_loupe
 ├── model.rb
 ├── path_relativizer.rb
 ├── staleness_checker.rb
+├── version.rb
 ├── tools
-│ ├── all_files_coverage_tool.rb
+│ ├── list_tool.rb
 │ ├── coverage_detailed_tool.rb
 │ ├── coverage_raw_tool.rb
 │ ├── coverage_summary_tool.rb
 │ ├── coverage_table_tool.rb
 │ ├── coverage_totals_tool.rb
+│ ├── validate_tool.rb
 │ ├── help_tool.rb
 │ ├── uncovered_lines_tool.rb
 │ └── version_tool.rb
-├── util.rb
-└── version.rb
+└── util.rb
 ```
 
 **Clean separation:** CLI ↔ Model ↔ MCP Tools

data/docs/examples/mcp-inputs.md

@@ -0,0 +1,3 @@
+# MCP Input Examples
+
+{% include-markdown "../../examples/mcp-inputs/README.md" %}

data/docs/examples/prompts.md

@@ -0,0 +1,3 @@
+# Prompt Examples
+
+{% include-markdown "../../examples/prompts/README.md" %}

data/docs/examples/success_predicates.md

@@ -0,0 +1,3 @@
+# Success Predicate Examples
+
+{% include-markdown "../../examples/success_predicates/README.md" %}