cov-loupe 3.0.0 → 4.0.0.pre

data/dev/prompts/validate/test-documentation-examples.md

@@ -0,0 +1,180 @@
+# Test Documentation Examples
+
+**Purpose:** Verify that all command examples in documentation work correctly and produce expected outputs.
+
+## When to Use This
+
+- After making documentation changes
+- Before releases
+- After CLI or API changes that might affect examples
+- When suspecting docs are out of sync with code
+
+## Scope
+
+### Files to Test
+
+Run all command examples found in:
+- `README.md`
+- `docs/user/**/*.md`
+- `docs/dev/**/*.md`
+
+### Files to Exclude
+
+Do NOT test examples in:
+- `docs/dev/arch-decisions/**/*.md`
+- `docs/dev/presentations/**/*.md`
+
+## Process
+
+### 1. Extract Command Examples
+
+Identify all code blocks that contain executable commands:
+- Bash/shell commands
+- CLI invocations
+- Code that should produce specific output
+
+Look for:
+- Code blocks marked with `bash`, `sh`, `shell`, or `console`
+- Inline code that appears to be runnable commands
+- Example command outputs
+
+### 2. Test Each Command
+
+For each command found:
+
+1. **Set up environment** (if needed):
+   - Install dependencies
+   - Create test files/fixtures
+   - Set environment variables
+
+2. **Execute the command** in an appropriate context:
+   - Use the correct working directory
+   - Ensure required files exist
+   - Handle commands that require specific prerequisites
+
+3. **Verify output**:
+   - Check exit code (0 for success unless failure is expected)
+   - Compare actual output with documented output
+   - Verify expected files are created
+   - Check for error messages if shown in docs
+
+4. **Clean up** (if needed):
+   - Remove temporary files
+   - Reset environment
+
+### 3. Document Failures
+
+For each failing example, record:
+
+- **File:** Which documentation file contains the failing example
+- **Line/Section:** Where in the file (approximate line or section heading)
+- **Command:** The exact command that failed
+- **Expected:** What the documentation shows should happen
+- **Actual:** What actually happened
+- **Error:** Any error messages
+- **Suggested Fix:** How to correct the documentation or code
+
+## Common Issues to Check
+
+### Syntax Changes
+- Command options that have changed (`--old-flag` → `--new-flag`)
+- Subcommands that have been renamed or removed
+- New required parameters
+
+### Path Assumptions
+- Commands that assume specific working directories
+- Relative vs absolute paths
+- File paths that may not exist in all environments
+
+### Output Format Changes
+- JSON structure changes
+- Table column changes
+- Different error message text
+
+### Prerequisites
+- Missing setup steps (e.g., "First run X before running Y")
+- Undocumented dependencies
+- Configuration that must be set
+
+### Version-Specific Examples
+- Examples that only work with specific versions
+- Deprecated features still documented
+
+## Output Format
+
+### If All Examples Pass
+
+Briefly report success:
+```
+Tested X command examples across Y documentation files.
+All examples executed successfully.
+```
+
+### If Examples Fail
+
+Create a detailed report with:
+
+```markdown
+# Documentation Example Test Results
+
+**Date:** YYYY-MM-DD
+**Tested Files:** X
+**Total Examples:** Y
+**Failed:** Z
+
+## Failures
+
+### README.md
+
+#### Line 42: cov-loupe list command
+**Command:**
+\`\`\`bash
+cov-loupe list --format json
+\`\`\`
+
+**Expected:**
+JSON output with coverage data
+
+**Actual:**
+```
+Error: unknown option '--format'
+```
+
+**Issue:**
+The `--format` flag has been replaced with `-f` or `--output-format`
+
+**Suggested Fix:**
+Update documentation to use:
+\`\`\`bash
+cov-loupe list --output-format json
+\`\`\`
+
+---
+
+### docs/user/getting-started.md
+
+#### Line 78: Running with custom resultset
+
+... (continue for each failure)
+
+## Summary
+
+- Update format flag in README.md line 42
+- Add missing setup step in getting-started.md before line 78
+- Fix output example in advanced-usage.md line 156 (JSON structure changed)
+```
+
+## Notes
+
+- **Don't modify code:** This is a validation task, not a fix task. Document what needs changing.
+- **Test in clean environment:** If possible, test in a fresh environment to catch missing setup steps.
+- **Check both success and failure examples:** If documentation shows an error example, verify it produces that error.
+- **Version compatibility:** Note if examples only work with specific versions.
+
+## Follow-Up Actions
+
+After identifying failures:
+1. Create issues for documentation fixes
+2. Update documentation files
+3. Consider adding automated tests for critical examples
+4. Re-run this validation after fixes

data/docs/QUICKSTART.md

@@ -0,0 +1,63 @@
+# Quick Start
+
+[Back to main README](index.md)
+
+Get up and running with cov-loupe in 3 steps.
+
+## 1. Install
+
+```sh
+gem install cov-loupe
+```
+
+## 2. Generate Coverage
+
+Run your test suite with SimpleCov enabled:
+
+```sh
+bundle exec rspec  # or your test command
+```
+
+This creates `coverage/.resultset.json`.
+
+## 3. View Coverage
+
+```sh
+cov-loupe
+```
+
+You'll see a table showing coverage for each file, sorted by highest coverage first (lowest at the bottom).
+
+## Common Commands
+
+```sh
+# Check a specific file
+cov-loupe summary lib/my_file.rb
+
+# See uncovered lines
+cov-loupe uncovered lib/my_file.rb
+
+# Get overall project stats
+cov-loupe totals
+
+# View all commands
+cov-loupe --help
+```
+
+## Next Steps
+
+- **[Installation Guide](user/INSTALLATION.md)** - Platform-specific setup, environment variables
+- **[CLI Usage](user/CLI_USAGE.md)** - Complete command reference
+- **[Examples](user/EXAMPLES.md)** - Common workflows and recipes
+- **[MCP Integration](user/MCP_INTEGRATION.md)** - Connect to AI assistants (Claude, ChatGPT)
+- **[Troubleshooting](user/TROUBLESHOOTING.md)** - Common issues and solutions
+
+## Integration with AI Assistants
+
+If you're using Claude Code, ChatGPT, or another MCP-compatible assistant:
+
+1. Install the MCP server (see [MCP Integration Guide](user/MCP_INTEGRATION.md))
+2. Use ready-made prompts from [Prompt Library](user/prompts/README.md)
+3. Let AI analyze your coverage and suggest improvements
+
+[Back to main README](index.md)

data/docs/assets/stylesheets/branding.css

@@ -0,0 +1,16 @@
+/* Increase logo size */
+.md-header__button.md-logo img,
+.md-header__button.md-logo svg {
+  height: 2.8rem; /* Increased from default */
+  width: auto;
+}
+
+/* Adjust header title to accommodate larger logo */
+.md-header__title {
+  margin-left: 0.5rem;
+}
+
+/* Optional: Add a subtle hover effect to the logo */
+.md-header__button.md-logo:hover {
+  opacity: 0.8;
+}

data/docs/assets/stylesheets/extra.css

@@ -0,0 +1,15 @@
+/* Enhance code blocks */
+.highlight {
+  border-radius: 0.2rem;
+}
+
+/* Improve table styling */
+table {
+  border-radius: 0.2rem;
+  overflow: hidden;
+}
+
+/* Add subtle shadows to content cards */
+.md-content {
+  box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05);
+}

data/docs/code_of_conduct.md

@@ -0,0 +1 @@
+{% include-markdown "../CODE_OF_CONDUCT.md" %}

data/docs/contributing.md

@@ -0,0 +1 @@
+{% include-markdown "../CONTRIBUTING.md" %}

data/docs/dev/ARCHITECTURE.md

@@ -1,28 +1,28 @@
 # Architecture
 
-[Back to main README](../README.md)
+[Back to main README](../index.md) | [Architecture Decision Records](arch-decisions/README.md)
 
 cov-loupe 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/cov_loupe/`, while adapters wrap that core for each runtime mode.
 
 ## Runtime Entry Points
 
 - **Executable** – `exe/cov-loupe` bootstraps the gem, enforces Ruby >= 3.2, and delegates to `CovLoupe.run(ARGV)`.
-- **Mode Negotiation** – `CovLoupe.run` inspects environment defaults from `COV_LOUPE_OPTS`, checks for CLI subcommands, and defaults to CLI mode when STDIN is a TTY. Otherwise it instantiates `CovLoupe::MCPServer` for MCP protocol communication over STDIO.
+- **Mode Negotiation** – `CovLoupe.run` inspects environment defaults from `COV_LOUPE_OPTS` and parses the `-m/--mode` flag. It defaults to CLI mode and instantiates `CovLoupe::CoverageCLI`. When `-m mcp` or `--mode mcp` is specified, it instantiates `CovLoupe::MCPServer` for MCP protocol communication over STDIO.
 - **Embedded Usage** – Applications embed the gem by instantiating `CovLoupe::CoverageModel` directly, optionally wrapping work in `CovLoupe.with_context` to install a library-oriented error handler.
 
 ## 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.
+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](../index.md#configuring-the-resultset) section in the main README.
 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.
+3. **Path relativizing** – `PathRelativizer` (powered by the centralized `PathUtils` module) 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 (`--staleness 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 (`--raise-on-stale true`) or simply mark rows as stale for display.
 
 ## Interfaces
 
 ### CLI (`CovLoupe::CoverageCLI`)
 
-- Builds on Ruby’s `OptionParser`, with global options such as `--resultset`, `--staleness`, `-fJ`, and `--source` modes.
+- Builds on Ruby’s `OptionParser`, with global options such as `--resultset`, `--raise-on-stale`, `-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.
@@ -30,7 +30,8 @@ cov-loupe is organized around a single coverage data model that feeds three deli
 ### MCP Server (`CovLoupe::MCPServer`)
 
 - Assembles a list of tool classes and mounts them in `MCP::Server` using STDIO transport.
-- Relies on the same core model; each tool instance recreates `CoverageModel` with the arguments provided by the MCP client, keeping the server stateless between requests.
+- Relies on the same core model; each MCP request creates a fresh `CoverageModel` instance, but the underlying coverage data is cached in a global `ModelDataCache` singleton. The cache automatically reloads when the resultset file changes (validated via file signature: mtime, subsecond mtime, size, inode, and MD5 digest).
+- Configuration precedence in MCP: per-request JSON parameters override CLI arguments passed when the server starts (including `COV_LOUPE_OPTS`), which in turn override built-in defaults.
 - Error handling delegates to `BaseTool.handle_mcp_error`, which swaps in the MCP-specific handler and emits `MCP::Tool::Response` objects.
 
 ### Library API
@@ -41,7 +42,7 @@ cov-loupe is organized around a single coverage data model that feeds three deli
 ## MCP Tool Stack
 
 - `CovLoupe::BaseTool` centralizes JSON schema definitions, error conversion, and response serialization for the MCP protocol.
-- Individual tools reside in `lib/cov_loupe/tools/` and follow a consistent shape: define an input schema, call into `CoverageModel`, then serialize via `respond_json`. Examples include `AllFilesCoverageTool`, `CoverageSummaryTool`, and `UncoveredLinesTool`.
+- Individual tools reside in `lib/cov_loupe/tools/` and follow a consistent shape: define an input schema, call into `CoverageModel`, then serialize via `respond_json`. Examples include `ListTool`, `CoverageSummaryTool`, and `UncoveredLinesTool`.
 - Tools are registered in `CovLoupe::MCPServer#run`. Adding a new tool only requires creating a subclass and appending it to that list.
 
 ## Error Handling & Logging
@@ -55,17 +56,61 @@ cov-loupe is organized around a single coverage data model that feeds three deli
 - `ErrorHandlerFactory` wires the appropriate handler per runtime: CLI, MCP server, or embedded library, each of which installs its handler inside a fresh `AppContext` before executing user work.
 - Diagnostics are written via `CovUtil.log` to `cov_loupe.log` in the current directory by default; override with CLI `--log-file`, set `CovLoupe.default_log_file` for future contexts, or temporarily tweak `CovLoupe.active_log_file` when a caller needs a different destination mid-run.
 
+## Output Character Mode
+
+cov-loupe provides a global output character mode that controls ASCII vs Unicode output across both CLI and MCP interfaces. This feature ensures compatibility with terminals and systems that cannot display Unicode characters while providing rich Unicode output (box-drawing characters, fancy tables) for environments that support it.
+
+### Configuration
+
+- **CLI flag** – `-O/--output-chars MODE` accepts `default`, `fancy`, or `ascii` (case-insensitive, with short forms `d`, `f`, `a`)
+- **MCP parameter** – Optional `output_chars` parameter in tool requests overrides server default
+- **Mode resolution** – `:default` resolves at runtime: UTF-8 terminal capability check for fancy, otherwise ASCII
+
+### Implementation
+
+- **Core conversion** – `OutputChars.convert` uses an internal transliteration map with `?` fallback for characters without ASCII equivalents
+- **Charsets** – Separate charset definitions for fancy (Unicode box-drawing) and ASCII modes
+- **Formatters** – All formatters (JSON, YAML, AmazingPrint, tables, source) respect the output_chars parameter
+  - JSON uses `JSON.generate(..., ascii_only: true)` for ASCII mode
+  - YAML and AmazingPrint post-process output through `OutputChars.convert`
+  - Tables use appropriate charset and convert cell contents
+  - Source output uses ASCII-safe markers (`+/-` instead of Unicode `✓/·`)
+
+### Scope of Conversion
+
+**Converted in ASCII mode:**
+- CLI error messages and option parser errors
+- Staleness error messages and file paths
+- Command literal strings (via `convert_text` helper in BaseCommand)
+- MCP tool JSON responses (via `respond_json` with `ascii_only: true`)
+- All formatted output (tables, source, JSON, YAML)
+
+**Not converted in ASCII mode:**
+- **Log files** – Preserved in original encoding for debugging fidelity. Log files are system/debugging artifacts, not user-facing output. Converting would lose exact file paths and error details needed for troubleshooting, create inconsistency between logged paths and actual filesystem paths, and provides no user value since logs are developer artifacts.
+- **Gem post-install message** – Intentionally left unchanged per requirements
+
+### Testing
+
+Comprehensive test coverage exists:
+- Mode resolution and normalization tests
+- Formatter tests for ASCII mode (JSON, YAML, AmazingPrint, tables, source)
+- CLI option parsing tests for `--output-chars` flag
+- MCP tool output mode tests
+- Staleness error message tests with Unicode file paths
+
 ## Configuration Surface
 
 - **Environment defaults** – `COV_LOUPE_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** – 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.
+- **Resultset overrides** – The location of the `.resultset.json` file can be specified via CLI options or in the MCP configuration. See [Configuring the Resultset](../index.md#configuring-the-resultset) for details.
+- **Tracked globs** – Glob patterns (e.g., `lib/**/*.rb`) that specify which files should have coverage. When provided, cov-loupe 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.
+- **Output character mode** – Global control of ASCII vs Unicode output via `-O/--output-chars` (CLI) or `output_chars` parameter (MCP). Default mode auto-detects terminal UTF-8 capability.
+- **Colorized source** – CLI-only flags (`--source`, `--context-lines`, `--color`) enhance human-readable reports when working locally.
 
 ## Repository Layout Highlights
 
 - `lib/cov_loupe/` – Core runtime (model, utilities, error handling, CLI, MCP server, tools).
 - `lib/cov_loupe.rb` – Primary public entry point required by gem consumers.
+- `lib/cov_loupe/path_utils.rb` – Centralized path normalization and expansion logic.
 - `docs/` – Audience-specific guides (`docs/user` for usage, `docs/dev` for contributors).
 - `spec/` – RSpec suite with fixtures under `spec/fixtures/` for deterministic coverage data.
 

data/docs/dev/DEVELOPMENT.md

@@ -1,6 +1,6 @@
 # Development Guide
 
-[Back to main README](../README.md)
+[Back to main README](../index.md)
 
 > **Note:** Commands like `cov-loupe` assume the gem is installed globally. If not, substitute `bundle exec exe/cov-loupe`.
 
@@ -39,15 +39,21 @@ rescue JSON::ParserError => e
 ```ruby
 module CovLoupe::Tools
   class MyTool < BaseTool
-    def self.name = 'my_tool'
-    def self.description = 'What this tool does'
-    
-    def self.call(path:, root: '.', resultset: nil, stale: 'off', error_mode: 'on', **)
-      model = CoverageModel.new(root: root, resultset: resultset, staleness: stale)
-      data = model.my_method_for(path)
-      respond_json(model.relativize(data), name: 'my_tool_output.json')
-    rescue => e
-      handle_mcp_error(e, name, error_mode: error_mode.to_sym)
+    description 'What this tool does'
+    input_schema(**input_schema_def)
+
+    def self.call(path:, root: nil, resultset: nil, raise_on_stale: nil,
+      error_mode: 'log', server_context:)
+      with_error_handling('MyTool', error_mode: error_mode) do
+        model = create_model(
+          server_context: server_context,
+          root: root,
+          resultset: resultset,
+          raise_on_stale: raise_on_stale
+        )
+        data = model.my_method_for(path)
+        respond_json(model.relativize(data), name: 'my_tool_output.json')
+      end
     end
   end
 end
@@ -73,11 +79,109 @@ before { setup_mcp_response_stub }
 
 **Coverage features:** Add to `CoverageModel` in `model.rb` or `CovUtil` in `util.rb`
 
+## Documentation Development
+
+This project uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) for documentation.
+
+### Installing MkDocs
+
+**Recommended: Using a Virtual Environment (all platforms)**
+
+Virtual environments isolate Python dependencies and don't require system-level permissions.
+
+```bash
+# Create virtual environment
+python3 -m venv .venv-docs
+
+# Activate it
+source .venv-docs/bin/activate  # macOS/Linux
+# Or on Windows: .venv-docs\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Deactivate when done (optional)
+deactivate
+```
+
+Note: Virtual environment directories (`.venv/`, `.venv-*/`, `venv/`) are already in `.gitignore`.
+
+**Alternative: System/User Installation**
+
+**macOS:**
+```bash
+# Using Homebrew
+brew install mkdocs
+pip3 install mkdocs-material mkdocs-awesome-pages-plugin pymdown-extensions
+
+# Or using pip only
+pip3 install -r requirements.txt
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+# Install pip if needed
+sudo apt update
+sudo apt install python3-pip
+
+# Install MkDocs and dependencies
+pip3 install -r requirements.txt
+
+# Add pip bin directory to PATH if mkdocs command not found
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+**Windows:**
+```powershell
+# Using pip (requires Python 3)
+pip install -r requirements.txt
+
+# Or install individually
+pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin pymdown-extensions
+```
+
+### Building Documentation
+
+```bash
+# If using virtual environment, activate it first
+source .venv-docs/bin/activate  # macOS/Linux
+# Or on Windows: .venv-docs\Scripts\activate
+
+# Build static site
+mkdocs build
+
+# Serve locally with live reload (opens at http://127.0.0.1:8000)
+mkdocs serve
+```
+
+### Documentation Structure
+
+- `docs/index.md` - Main landing page (derived from README.md)
+- `docs/user/` - User-facing documentation (installation, usage, examples)
+- `docs/dev/` - Developer documentation (architecture, contributing)
+- `mkdocs.yml` - MkDocs configuration and navigation structure
+
+### Adding Documentation
+
+1. Create or edit markdown files in the `docs/` directory
+2. Add new pages to the `nav` section in `mkdocs.yml`
+3. Test locally with `mkdocs serve`
+4. Commit changes along with your code changes
+
+### Troubleshooting MkDocs
+
+**Command not found after pip install:**
+- Ensure pip's bin directory is in your PATH
+- macOS: `export PATH="$HOME/Library/Python/3.x/bin:$PATH"`
+- Linux: `export PATH="$HOME/.local/bin:$PATH"`
+- Or run via Python: `python3 -m mkdocs serve`
+
 ## Troubleshooting
 
-**RVM + Codex macOS:** Currently not possible for Codex to run rspec when running on macOS with rvm-managed rubies - see [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+**RVM + Codex macOS:** Currently not possible for Codex to run rspec when running on macOS with rvm-managed rubies - see [Troubleshooting](../user/TROUBLESHOOTING.md)
 
 **MCP server testing:**
 ```sh
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | cov-loupe
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | cov-loupe -m mcp
 ```

data/docs/dev/FUTURE_ENHANCEMENTS.md

@@ -0,0 +1,14 @@
+# Future Enhancements
+
+[Back to main README](../index.md)
+
+## Coverage path lookup indexing
+
+### Problem
+Single-file tools (`summary`, `raw`, `detailed`, `uncovered`) call `CoverageLineResolver#resolve_key`, which normalizes every key in the coverage map on each lookup. That makes per-file queries O(n) in the number of files and can become O(n^2) across repeated MCP/CLI requests.
+
+### Proposed approach
+Precompute a normalized-key index once per resolver (or per cached model data). Use that index for O(1) lookups while preserving ambiguity detection when multiple original keys normalize to the same value.
+
+### Why this matters
+Large resultsets or frequent interactive queries can feel sluggish due to repeated normalization and full-map scans. Indexing would improve responsiveness without changing output semantics.

data/docs/dev/README.md

@@ -1,10 +1,11 @@
 # Developer Documentation
 
-Resources for contributors working on SimpleCov MCP internals and release
+[Back to main README](../index.md)
+
+Resources for contributors working on cov-loupe 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/cov-loupe-presentation.md) – slide deck for talks/demos

data/docs/dev/RELEASING.md

@@ -1,5 +1,7 @@
 # Release Process
 
+[Back to main README](../index.md)
+
 This document provides a checklist for releasing new versions of cov-loupe.
 
 ## Pre-Release Checklist

data/docs/dev/arch-decisions/README.md

@@ -1,6 +1,6 @@
 # Architecture Decision Records
 
-[Back to main README](../../README.md)
+[Back to main README](../../index.md) | [Architecture Overview](../ARCHITECTURE.md)
 
 ## What is an ADR?
 
@@ -37,11 +37,14 @@ Links to related code, issues, documentation, or other ADRs.
 
 ## Index of ADRs
 
-- [001: Dual-Mode Operation](001-x-arch-decision.md) - CLI vs MCP server mode detection
-- [002: Context-Aware Error Handling](002-x-arch-decision.md) - Mode-specific error handling strategy
-- [003: Coverage Staleness Detection](003-x-arch-decision.md) - Three-type staleness system
-- [004: Ruby Instance Eval for Success Predicates](004-x-arch-decision.md) - Dynamic Ruby evaluation approach
-- [005: No SimpleCov Runtime Dependency](005-x-arch-decision.md) - Superseded by the multi-suite merge work (runtime SimpleCov dependency)
+ADRs are organized by topic area rather than chronologically:
+
+- [Application Architecture](application-architecture.md) - Dual-mode operation (CLI/MCP) and context-aware error handling
+- [Coverage Data Quality](coverage-data-quality.md) - Staleness detection system
+- [Output Character Mode](output-character-mode.md) - Global ASCII vs Unicode output control
+- [Path Resolution](path-resolution.md) - Path matching strategy and cross-OS coverage support
+- [Policy Validation](policy-validation.md) - Success predicates using Ruby `instance_eval`
+- [SimpleCov Integration](simplecov-integration.md) - Dependency strategy and data loading (replaced)
 
 ## When to Create an ADR
 
@@ -54,7 +57,7 @@ Create an ADR when:
 ## Contributing
 
 When adding a new ADR:
-1. Use the next sequential number (e.g., `006-x-arch-decision.md`)
+1. Add it to the appropriate topic-based file, or create a new file if it covers a new area
 2. Follow the format outlined above
 3. Update this README's index
 4. Link to relevant code and documentation