cov-loupe 3.0.0

data/docs/user/MCP_INTEGRATION.md

@@ -0,0 +1,490 @@
+# MCP Integration Guide
+
+[Back to main README](../README.md)
+
+## Table of Contents
+
+- [What is MCP?](#what-is-mcp)
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [Setup by Client](#setup-by-client)
+- [Available MCP Tools](#available-mcp-tools)
+- [Testing Your Setup](#testing-your-setup)
+- [Troubleshooting](#troubleshooting)
+
+## What is MCP?
+
+The Model Context Protocol (MCP) is a standard for integrating tools and data sources with AI assistants. By running cov-loupe as an MCP server, you enable AI coding assistants to:
+
+- Query coverage data for files
+- Identify uncovered code
+- Analyze coverage gaps
+- Suggest improvements based on coverage data
+
+### Why Use MCP with Coverage Tools?
+
+AI assistants can help you:
+- **Prioritize testing** - "Which files need coverage most urgently?"
+- **Understand gaps** - "Why is this file's coverage low?"
+- **Generate tests** - "Write tests for uncovered lines in this file"
+- **Track progress** - "Has coverage improved since last commit?"
+
+## Prerequisites
+
+- **Ruby >= 3.2** (required by MCP gem dependency)
+- **cov-loupe installed** - See [Installation Guide](INSTALLATION.md)
+- **simplecov gem >= 0.21** - Needed when a resultset contains multiple suites (loaded lazily)
+- **Coverage data** - Run tests to generate `coverage/.resultset.json`
+- **MCP-compatible client** - Claude Code, Cursor, Codex, etc.
+
+## Quick Start
+
+### 1. Install cov-loupe
+
+```sh
+gem install cov-loupe
+```
+
+### 2. Verify Installation
+
+```sh
+# Find the executable path (needed for MCP configuration)
+which cov-loupe
+
+# Test it works
+cov-loupe version
+```
+
+### 3. Configure Your AI Assistant
+
+See [Setup by Client](#setup-by-client) below for specific instructions.
+
+### 4. Generate Coverage Data
+
+```sh
+# Run your test suite
+bundle exec rspec  # or your test command
+
+# Verify coverage file exists
+ls coverage/.resultset.json
+```
+
+> **Multi-suite note:** If the resultset contains several suites (e.g., `RSpec` and `Cucumber`), cov-loupe lazily loads the `simplecov` gem and merges them before answering coverage queries. Staleness checks currently use the newest suite’s timestamp, so treat multi-suite freshness warnings as advisory until per-file timestamps are introduced.
+>
+> Only suites stored in a *single* `.resultset.json` are merged automatically. If your test runs produce multiple resultset files, merge them (e.g., via `SimpleCov::ResultMerger.merge_and_store`) and point cov-loupe at the combined file.
+
+> Multifile support may be added in a future version (post an issue if you want this).
+
+### 5. Test the MCP Server
+
+```sh
+# Test manually
+echo '''{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}''' | cov-loupe
+```
+
+You should see a JSON-RPC response with version information.
+
+## Setup by Client
+
+### Claude Code
+
+**Current Status:** Claude Code has a bug in its MCP client that prevents it from working with spec-compliant MCP servers like cov-loupe. Claude Code will automatically fall back to using the CLI interface.
+
+**Bug Report:** [Claude Code Issue #8239](https://github.com/anthropics/claude-code/issues/8239)
+
+**Workaround:** Use the CLI interface, which provides the same functionality:
+```sh
+# Instead of MCP tools, use CLI
+cov-loupe list
+cov-loupe summary lib/cov_loupe/cli.rb
+```
+
+**Configuration (for when bug is fixed):**
+
+Using the Claude CLI tool:
+
+```sh
+# Basic setup (if cov-loupe is in default PATH)
+claude mcp add cov-loupe cov-loupe
+
+# With rbenv/asdf (use absolute path)
+claude mcp add cov-loupe /Users/yourname/.rbenv/shims/cov-loupe
+
+# With RVM wrapper (recommended for stability)
+rvm wrapper ruby-3.3.8 cov-loupe cov-loupe
+claude mcp add cov-loupe /Users/yourname/.rvm/wrappers/ruby-3.3.8/cov-loupe
+
+# For user-wide configuration (default is local)
+claude mcp add --scope user cov-loupe cov-loupe
+
+# For project-specific configuration
+claude mcp add --scope project cov-loupe cov-loupe
+```
+
+**Verify configuration:**
+```sh
+# List configured MCP servers
+claude mcp list
+
+# Get server details
+claude mcp get cov-loupe
+
+# Remove if needed
+claude mcp remove cov-loupe
+```
+
+**Important Notes:**
+- Default scope is `local` (current project)
+- Use `--scope user` for global config, `--scope project` for project-specific
+- The executable path is tied to Ruby version with version managers
+- If you change Ruby versions, remove and re-add the configuration
+
+### Cursor / Codex
+
+Using the Codex CLI:
+
+```sh
+# Basic setup (if cov-loupe is in default PATH)
+codex mcp add cov-loupe --command cov-loupe
+
+# With rbenv/asdf (use absolute path)
+codex mcp add cov-loupe --command /Users/yourname/.rbenv/shims/cov-loupe
+
+# With RVM wrapper (recommended for stability)
+rvm wrapper ruby-3.3.8 cov-loupe cov-loupe
+codex mcp add cov-loupe --command /Users/yourname/.rvm/wrappers/ruby-3.3.8/cov-loupe
+
+# List configured servers
+codex mcp list
+
+# Show server details
+codex mcp get cov-loupe
+
+# Remove if needed
+codex mcp remove cov-loupe
+```
+
+**Find your executable path:**
+```sh
+which cov-loupe
+```
+
+### Gemini
+
+Using the Gemini CLI:
+
+```sh
+# Add MCP server
+gemini mcp add cov-loupe /Users/yourname/.rbenv/shims/cov-loupe
+
+# Or with RVM
+gemini mcp add cov-loupe /Users/yourname/.rvm/wrappers/ruby-3.3.8/cov-loupe
+
+# List configured servers
+gemini mcp list
+
+# Remove if needed
+gemini mcp remove cov-loupe
+```
+
+### Generic MCP Client
+
+For any MCP client that uses JSON configuration:
+
+```json
+{
+  "mcpServers": {
+    "cov-loupe": {
+      "command": "/path/to/cov-loupe",
+      "args": [],
+      "env": {
+        "COV_LOUPE_OPTS": "--resultset coverage"
+      }
+    }
+  }
+}
+```
+
+**Environment variables you can set:**
+
+- `COV_LOUPE_OPTS` - Default CLI options (though less useful for MCP mode)
+
+## Available MCP Tools
+
+### Tool Catalog
+
+cov-loupe exposes 10 MCP tools:
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `coverage_summary_tool` | File coverage summary | `path` |
+| `coverage_detailed_tool` | Per-line coverage | `path` |
+| `coverage_raw_tool` | Raw SimpleCov array | `path` |
+| `uncovered_lines_tool` | List uncovered lines | `path` |
+| `all_files_coverage_tool` | Project-wide coverage | `sort_order`, `tracked_globs` |
+| `coverage_totals_tool` | Aggregated line totals | `tracked_globs` |
+| `coverage_table_tool` | Formatted coverage table | `sort_order` |
+| `validate_tool` | Validate coverage policies | `code` or `file` |
+| `help_tool` | Tool discovery | (none) |
+| `version_tool` | Version information | (none) |
+
+### JSON Response Format
+
+For tools that return structured data, `cov-loupe` serializes the data as a JSON string and returns it inside a `text` part of the MCP response.
+
+**Example:**
+```json
+{
+  "type": "text",
+  "text": "{"coverage_summary":{"covered":10,"total":20,"percentage":50.0}}"
+}
+```
+
+**Reasoning:**
+While returning JSON in a `resource` part with `mimeType: "application/json"` is more semantically correct, major MCP clients (including Google's Gemini and Anthropic's Claude) were found to not support this format, causing validation errors. They expect a `resource` part to contain a `uri`.
+
+To ensure maximum compatibility, the decision was made to use a simple `text` part. This is a pragmatic compromise that has proven to be reliable across different clients.
+
+**Further Reading:**
+This decision was informed by discussions with multiple AI models. For more details, see these conversations:
+- [Perplexity AI Discussion](https://www.perplexity.ai/search/title-resolving-a-model-contex-IfpFWU1FR5WQXQ8HcQctyg#0)
+- [ChatGPT Discussion](https://chatgpt.com/share/68e4d7e1-cad4-800f-80c2-58b33bfc31cb)
+
+### Common Parameters
+
+All file-specific tools accept these parameters:
+
+- `path` (required for file tools) - File path (relative or absolute)
+- `root` (optional) - Project root directory (default: `.`)
+- `resultset` (optional) - Path to the `.resultset.json` file. See [Configuring the Resultset](../README.md#configuring-the-resultset) for details.
+- `staleness` (optional) - Staleness mode: `"off"` (default) or `"error"`
+- `error_mode` (optional) - Error handling: `"off"`, `"log"` (default), `"debug"`
+
+### Tool Details
+
+#### Per-File Tools
+
+These tools analyze individual files. All require `path` parameter.
+
+**`coverage_summary_tool`** - Covered/total/percentage summary
+```json
+{"file": "...", "summary": {"covered": 12, "total": 14, "percentage": 85.71}, "stale": false}
+```
+
+**`uncovered_lines_tool`** - List uncovered line numbers
+```json
+{"file": "...", "uncovered": [5, 9, 12], "summary": {...}, "stale": false}
+```
+
+**`coverage_detailed_tool`** - Per-line hit counts
+```json
+{"file": "...", "lines": [{"line": 1, "hits": 1, "covered": true}, ...], "summary": {...}, "stale": false}
+```
+
+**`coverage_raw_tool`** - Raw SimpleCov lines array
+```json
+{"file": "...", "lines": [1, 0, null, 5, 2, null, 1], "stale": false}
+```
+
+#### Project-Wide Tools
+
+**`all_files_coverage_tool`** - Coverage for all files
+- Parameters: `sort_order` (`ascending`|`descending`), `tracked_globs` (array)
+- Returns: `{"files": [...], "counts": {"total": N, "ok": N, "stale": N}}`
+
+**`coverage_totals_tool`** - Aggregated line totals
+- Parameters: `tracked_globs` (array), `staleness`
+- Returns: `{"lines":{"total":N,"covered":N,"uncovered":N},"percentage":Float,"files":{"total":N,"ok":N,"stale":N}}`
+
+**`coverage_table_tool`** - Formatted ASCII table
+- Parameters: `sort_order` (`ascending`|`descending`)
+- Returns: Plain text table
+
+#### Policy Validation Tools
+
+**`validate_tool`** - Validate coverage against custom policies
+- Parameters: Either `code` (Ruby string) OR `file` (path to Ruby file), plus optional `root`, `resultset`, `staleness`, `error_mode`
+- Returns: `{"result": Boolean}` where `true` means policy passed, `false` means failed
+- Security Warning: Predicates execute as arbitrary Ruby code with full system privileges. Only use predicate files from trusted sources.
+- Examples:
+  - Check if all files have at least 80% coverage: `{"code": "->(m) { m.all_files.all? { |f| f['percentage'] >= 80 } }"}`
+  - Run coverage policy from file: `{"file": "coverage_policy.rb"}`
+
+#### Utility Tools
+
+**`help_tool`** - Tool discovery
+**`version_tool`** - Version information
+
+## Example Prompts for AI Assistants
+
+### Coverage Analysis
+
+```
+Using cov-loupe, show me a table of all files and their coverage percentages.
+```
+
+```
+Using cov-loupe, find files with less than 80% coverage and tell me which ones to prioritize.
+```
+
+```
+Using cov-loupe, analyze the coverage for lib/cov_loupe/tools/ and suggest improvements.
+```
+
+### Finding Coverage Gaps
+
+```
+Using cov-loupe, show me the uncovered lines in lib/cov_loupe/base_tool.rb and explain what they do.
+```
+
+```
+Using cov-loupe, find the most important uncovered code in lib/cov_loupe/tools/coverage_detailed_tool.rb.
+```
+
+### Test Generation
+
+```
+Using cov-loupe, find uncovered lines in lib/cov_loupe/staleness_checker.rb and write RSpec tests for them.
+```
+
+```
+Using cov-loupe, analyze coverage gaps in lib/cov_loupe/tools/ and generate test cases.
+```
+
+### Coverage Reporting
+
+```
+Using cov-loupe, create a markdown report of:
+- Files with worst coverage
+- Most critical coverage gaps
+- Recommended action items
+```
+
+## Testing Your Setup
+
+### Manual Testing via Command Line
+
+Test the MCP server responds to JSON-RPC:
+
+```sh
+# Test version tool (simplest)
+echo '''{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}''' | cov-loupe
+
+# Test summary tool
+echo '''{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"lib/cov_loupe/model.rb"}}}''' | cov-loupe
+
+# Test help tool
+echo '''{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"help_tool","arguments":{}}}''' | cov-loupe
+```
+
+**Important:** JSON-RPC messages must be on a single line. Multi-line JSON will cause parse errors.
+
+### Testing in AI Assistant
+
+Once configured, try these prompts in your AI assistant:
+
+1. **Basic connectivity:**
+   ```
+   Using cov-loupe, show me the version.
+   ```
+
+2. **List tools:**
+   ```
+   Using cov-loupe, what tools are available?
+   ```
+
+3. **Simple query:**
+   ```
+   Using cov-loupe, show me all files with coverage.
+   ```
+
+If these work, your setup is correct!
+
+### Checking Logs
+
+The MCP server logs to `cov_loupe.log` in the current directory by default.
+
+```sh
+# Watch logs in real-time
+tail -f cov_loupe.log
+
+# View recent errors
+grep ERROR cov_loupe.log | tail -20
+```
+
+To override the default log file location, specify the `--log-file` argument wherever and however you configure your MCP server. For example, to log to a different file path, include `--log-file /path/to/logfile.log` in your server configuration. To log to standard error, use `--log-file stderr`.
+
+**Note:** Logging to `stdout` is not permitted in MCP mode.
+
+## Troubleshooting
+
+### CLI Fallback
+
+**Important:** If the MCP server doesn't work, you can use the CLI directly with the `-fJ` flag.
+
+See the **[CLI Fallback for LLMs Guide](CLI_FALLBACK_FOR_LLMS.md)** for:
+- Complete command reference and MCP tool mappings
+- Sample prompt to give your LLM
+- JSON output examples
+- Tips for using CLI as an MCP alternative
+
+### Common Issues
+
+**Server Won't Start**
+```sh
+which cov-loupe                            # Verify executable exists
+ruby -v                                         # Check Ruby >= 3.2
+cov-loupe version                          # Test basic functionality
+```
+
+**Path Issues with Version Managers**
+```sh
+which cov-loupe                            # Use this absolute path in MCP config
+# RVM: Create wrapper for stability
+rvm wrapper ruby-3.3.8 cov-loupe cov-loupe
+```
+
+**Tools Not Appearing**
+1. Restart AI assistant after config changes
+2. Check logs: `tail -f cov_loupe.log`
+3. Try explicit tool names in prompts
+4. Verify MCP server status in assistant
+
+**JSON-RPC Parse Errors**
+- Ensure JSON is on a single line (no newlines)
+- Test manually: `echo '{"jsonrpc":"2.0",...}' | cov-loupe`
+
+## Advanced Configuration
+
+### Enable Debug Logging
+
+For troubleshooting, add error mode when configuring the server:
+
+```sh
+# Claude Code
+claude mcp add cov-loupe cov-loupe --error-mode debug
+
+# Codex
+codex mcp add cov-loupe --command cov-loupe --args "--error-mode" --args "debug"
+
+# Gemini
+gemini mcp add cov-loupe "$(which cov-loupe) --error-mode debug"
+```
+
+### Project-Specific vs. Global Configuration
+
+**Global configuration** (all projects):
+- Claude: `claude mcp add --scope user cov-loupe ...`
+- Codex: `codex mcp add` (uses global config by default)
+- Gemini: `gemini mcp add` (uses global config)
+
+**Project-specific** (one project):
+- Claude: `claude mcp add --scope project cov-loupe ...` (default is `local`)
+- Codex/Gemini: Create `.codex/config.toml` or `.gemini/config.toml` in project root (manual)
+
+## Next Steps
+
+- **[CLI Fallback for LLMs](CLI_FALLBACK_FOR_LLMS.md)** - Using CLI when MCP isn't available
+- **[CLI Usage](CLI_USAGE.md)** - Complete CLI reference
+- **[Examples](EXAMPLES.md)** - Example prompts and workflows
+- **[Troubleshooting](TROUBLESHOOTING.md)** - Detailed troubleshooting guide

data/docs/user/README.md

@@ -0,0 +1,14 @@
+# User Documentation
+
+Guides for installing, configuring, and using SimpleCov MCP in day-to-day
+workflows.
+
+- [Installation](INSTALLATION.md) – environment setup across platforms
+- [CLI Usage](CLI_USAGE.md) – command reference with examples
+- [Examples](EXAMPLES.md) – common coverage workflows
+- [Advanced Usage](ADVANCED_USAGE.md) – resultset paths, staleness, predicates
+- [Error Handling](ERROR_HANDLING.md) – modes, exceptions, logging
+- [MCP Integration](MCP_INTEGRATION.md) – configuring AI assistants
+- [CLI Fallback for LLMs](CLI_FALLBACK_FOR_LLMS.md) – when MCP isn't available
+- [Library API](LIBRARY_API.md) – embedding the gem in Ruby code
+- [Troubleshooting](TROUBLESHOOTING.md) – diagnostics for common issues

data/docs/user/TROUBLESHOOTING.md

@@ -0,0 +1,197 @@
+# Troubleshooting Guide
+
+[Back to main README](../README.md)
+
+## Table of Contents
+
+- [Running Issues](#running-issues)
+- [Coverage Data Issues](#coverage-data-issues)
+- [MCP Server Issues](#mcp-server-issues)
+- [Development Issues](#development-issues)
+- [Diagnostic Commands](#diagnostic-commands)
+
+## Running Issues
+
+### Running the Test Suite with RVM (Codex macOS)
+
+Codex's macOS sandbox forbids `/bin/ps`; RVM shells need it. When you run `bundle exec rspec` there, the shell falls back to macOS Ruby 2.6 and Bundler dies with `Gem::Resolver::APISet::GemParser` errors.
+
+**Workarounds:**
+
+- Run outside the macOS sandbox (Codex on Ubuntu, Gemini, Claude Code, local shells) or use a version manager that does not invoke `ps`.
+- Or execute RSpec with explicit RVM paths:
+  ```bash
+  PATH="$HOME/.rvm/gems/ruby-3.4.5@cov-loupe/bin:$HOME/.rvm/rubies/ruby-3.4.5/bin:$PATH" \
+    GEM_HOME="$HOME/.rvm/gems/ruby-3.4.5@cov-loupe" \
+    GEM_PATH="$HOME/.rvm/gems/ruby-3.4.5@cov-loupe:$HOME/.rvm/gems/ruby-3.4.5@global" \
+    $HOME/.rvm/rubies/ruby-3.4.5/bin/bundle exec rspec
+  ```
+- Use a different AI coding agent and/or operating system.
+
+## Coverage Data Issues
+
+### Missing `coverage/.resultset.json`
+
+`cov-loupe` only reads coverage data; it never generates it. If you see "Could not find .resultset.json":
+
+1. Run the test suite with SimpleCov enabled (default project setup already enables it).
+   ```bash
+   bundle exec rspec
+   ls coverage/.resultset.json
+   ```
+2. If your coverage lives elsewhere, point the tools at it:
+   ```bash
+   cov-loupe --resultset build/coverage/.resultset.json
+   # or
+   export COV_LOUPE_OPTS="--resultset build/coverage"
+   ```
+
+### Stale Coverage Errors
+
+`--staleness error` (or `staleness: 'error'`) compares file mtimes and line counts to the coverage snapshot. When it fails:
+
+- Regenerate coverage (`bundle exec rspec`) so the snapshot matches current sources.
+- Or drop back to warning-only behaviour using `--staleness off` / `staleness: 'off'`.
+
+If you only care about a subset of files, supply `--tracked-globs` (CLI) or `tracked_globs:` (API) so new files outside those globs do not trigger staleness.
+
+### "No coverage data found for file"
+
+The model looks up files by absolute path, then cwd-relative path, then basename. If you still hit this error:
+
+1. Verify the file is listed in the coverage table (`cov-loupe list | grep model.rb`).
+2. Use the exact project-relative path that SimpleCov recorded (case-sensitive, no symlinks).
+3. If the file truly never executes under tests, add coverage or exclude it from your workflow.
+
+## MCP Server Issues
+
+### MCP Integration Not Working
+
+**Symptoms:**
+- AI assistant reports "Could not connect to MCP server"
+- AI says "I don't have access to cov-loupe tools"
+
+**Diagnostic steps:**
+
+1. **Verify executable exists and works:**
+   ```bash
+   which cov-loupe
+   cov-loupe version
+   ```
+
+2. **Test MCP server mode manually:**
+   ```bash
+   echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | cov-loupe
+   ```
+   Should return JSON-RPC response.
+
+3. **Verify MCP server is configured:**
+   ```bash
+   claude mcp list  # For Claude Code
+   codex mcp list   # For Codex
+   tail -f cov_loupe.log  # Check logs
+   ```
+
+4. **Restart AI assistant** - Config changes often require restart
+
+5. **Use absolute path in MCP config:**
+   ```bash
+   # Find absolute path
+   which cov-loupe
+
+   # Update your MCP client config to use this path
+   ```
+
+6. **Use CLI as fallback:**
+
+   If MCP still isn't working, you can use the CLI with `-fJ` flag instead.
+   See **[CLI Fallback for LLMs](CLI_FALLBACK_FOR_LLMS.md)** for complete guidance.
+
+### Path Issues with Version Managers
+
+**Symptom:** Works in terminal but not in MCP client.
+
+**Cause:** MCP client doesn't have your shell environment (PATH, RVM, etc.).
+
+**Solution:** Use absolute paths in MCP configuration:
+
+```bash
+# For rbenv/asdf
+which cov-loupe
+# Use this path in MCP config
+
+# For RVM, create wrapper
+rvm wrapper ruby-3.3.8 cov-loupe cov-loupe
+# Use: ~/.rvm/wrappers/ruby-3.3.8/cov-loupe
+```
+
+## Development Issues
+
+### Test Suite Failures
+
+**Symptom:** `bundle exec rspec` fails with coverage errors.
+
+**Common causes:**
+
+1. **Stale coverage data** - Delete `coverage/` directory and re-run
+2. **SimpleCov not loaded** - Check `spec/spec_helper.rb` requires SimpleCov
+3. **Wrong Ruby version** - Verify Ruby >= 3.2
+
+## Diagnostic Commands
+
+Before reporting an issue, run these diagnostic commands and include the output:
+
+```bash
+# System info
+ruby -v
+gem -v
+bundle -v
+
+# cov-loupe info
+gem list cov-loupe
+which cov-loupe
+cov-loupe version
+
+# Test basic functionality
+cov-loupe --help
+cov-loupe list 2>&1
+
+# Check coverage data
+ls -la coverage/.resultset.json
+head -20 coverage/.resultset.json
+
+# Test MCP mode
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | cov-loupe 2>&1
+```
+
+## Getting More Help
+
+If the above doesn't solve your problem:
+
+1. **Check error mode** - Run with `--error-mode debug` for full stack traces:
+   ```bash
+   cov-loupe --error-mode debug summary lib/cov_loupe/cli.rb
+   ```
+
+2. **Check logs:**
+   ```bash
+   # MCP server logs
+   tail -50 cov_loupe.log
+
+   # Or specify custom log location
+   cov-loupe --log-file /tmp/debug.log summary lib/cov_loupe/cli.rb
+   ```
+
+3. **Search existing issues:**
+   https://github.com/keithrbennett/cov-loupe/issues
+
+4. **Report a bug:**
+   Include output from [Diagnostic Commands](#diagnostic-commands) above
+
+## Related Documentation
+
+- [Installation Guide](INSTALLATION.md) - Setup and PATH configuration
+- [CLI Usage](CLI_USAGE.md) - Command-line options and examples
+- [CLI Fallback for LLMs](CLI_FALLBACK_FOR_LLMS.md) - Using CLI when MCP isn't available
+- [MCP Integration](MCP_INTEGRATION.md) - MCP server configuration
+- [Error Handling](ERROR_HANDLING.md) - Understanding error modes