docs: update documentation for dependency checking and pre-flight validation

Add check-deps command to installation guides, new dependency management
section to README, missing dependencies troubleshooting entries, changelog
entries for unreleased features, and update test counts to 902/40.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: druvus

CHANGELOG.md

@@ -7,7 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Dependency Checking**: New `nanorunner check-deps` command that reports the status
+  of all required and optional dependencies with conda install instructions.
+- **Pre-flight Validation**: Automatic validation before long-running operations
+  (`generate`, `download`) catches missing tools (badread, nanosim, datasets CLI)
+  before work begins, with actionable error messages.
+- **Subprocess Error Wrapping**: External tool failures (badread, nanosim) now produce
+  clear error messages including exit codes, stderr output, and install hints instead
+  of bare tracebacks.
+- **Centralized Install Hints**: New `deps.py` module provides a single source of truth
+  for dependency install instructions, replacing scattered hardcoded strings.
+- **Robust Backend Detection**: `is_available()` for badread and nanosim now verifies
+  tools can actually start (catches broken installs where the binary exists but
+  dependencies like edlib are missing).
+
 ### Changed
+- **Install Instructions**: Standardized all install hints to use conda/bioconda
+  channels instead of pip (e.g., `conda install -c conda-forge -c bioconda badread`).
 - **Breaking: Pipeline Adapters**: Removed `miniknife` adapter (fictional pipeline
   with no published tool). Renamed `nanometanf` adapter to `nanometa` to align with
   the published Nanometa Live tool. Both built-in adapters (`nanometa`, `kraken`) are

README.md

@@ -69,6 +69,7 @@ pip install -e .[enhanced,dev]
 ```bash
 nanorunner --version  # Should output: nanorunner 2.0.2
 nanorunner --help     # Display all available subcommands
+nanorunner check-deps       # Check all dependencies and show install hints
 nanorunner list-profiles    # Show built-in configuration profiles
 nanorunner list-generators  # Show available read generation backends
 nanorunner list-mocks       # Show available mock communities
@@ -391,14 +392,28 @@ Built-in adapters provide validation for multiple bioinformatics workflows:
 - **kraken**: Kraken2/KrakenUniq taxonomic classification pipeline
 - **Generic**: Customizable adapter for arbitrary pipeline requirements
 
+## Dependency Management
+
+NanoRunner's core functionality (replay mode, built-in read generation) has no external dependencies beyond the Python standard library. Optional tools extend its capabilities:
+
+| Dependency | Purpose | Install |
+|-----------|---------|---------|
+| psutil | Enhanced resource monitoring | `conda install -c conda-forge psutil` |
+| numpy | Vectorized read generation | `conda install -c conda-forge numpy` |
+| badread | Nanopore read simulation with error models | `conda install -c conda-forge -c bioconda badread` |
+| nanosim | Statistical read simulation | `conda install -c conda-forge -c bioconda nanosim` |
+| datasets | NCBI genome downloads (`--species`, `--mock`) | `conda install -c conda-forge ncbi-datasets-cli` |
+
+Use `nanorunner check-deps` to see the status of all dependencies and install instructions for missing ones. Pre-flight validation catches missing dependencies before long-running operations begin, providing actionable error messages.
+
 ## Technical Requirements
 
 - **Python**: Version 3.9 or higher
 - **Core dependencies**: Standard library only for basic functionality (including built-in read generation)
 - **Enhanced features**: Optional psutil dependency for resource monitoring
 - **Optional read generators**: badread and/or NanoSim for higher-fidelity read simulation
 - **Platform compatibility**: POSIX-compliant operating systems (Linux, macOS, Unix)
-- **Testing**: 730 tests across 37 test files
+- **Testing**: 902 tests across 40 test files
 
 ## Development and Contribution
 
@@ -457,7 +472,8 @@ Common issues and solutions:
 - **Python version errors**: Ensure Python 3.9+ is installed
 - **Permission denied**: Use `--user` flag or check target directory permissions
 - **Import errors**: Verify installation with `pip show nanorunner`
-- **Enhanced monitoring unavailable**: Install with `pip install "nanorunner[enhanced] @ git+..."`
+- **Missing dependencies**: Run `nanorunner check-deps` to identify missing tools and install instructions
+- **Enhanced monitoring unavailable**: Install psutil with `conda install -c conda-forge psutil`
 
 For detailed troubleshooting steps, see [docs/troubleshooting.md](docs/troubleshooting.md).
 

docs/README.md

@@ -38,7 +38,7 @@ Comprehensive guides and references for the NanoRunner nanopore sequencing simul
 - **[Testing Guide](testing.md)**: Comprehensive guide covering test categories, running tests, organization, and contributing
 
 ### Current Status
-- **Test Count**: 730 tests across 37 test files
+- **Test Count**: 902 tests across 40 test files
 - **Coverage**: 97% on core components
 
 ## Quick Links

docs/quickstart.md

@@ -22,6 +22,9 @@ nanorunner --version
 
 nanorunner --help
 # Shows all available subcommands
+
+nanorunner check-deps
+# Shows status of all dependencies with install hints for missing ones
 ```
 
 ---
@@ -488,7 +491,8 @@ nanorunner generate --mock zymo_d6300 -t /target
 # Replay with pipeline validation
 nanorunner replay -s /source -t /target --pipeline nanometa
 
-# List options
+# List options and check dependencies
+nanorunner check-deps
 nanorunner list-profiles
 nanorunner list-adapters
 nanorunner list-generators

docs/testing.md

@@ -6,7 +6,7 @@ This document provides a comprehensive guide to NanoRunner's test suite, includi
 
 NanoRunner has a comprehensive test suite designed to validate both individual components and complete workflows:
 
-- **Total Tests**: 730 tests across 37 test files
+- **Total Tests**: 902 tests across 40 test files
 - **Runtime**: ~45 seconds for non-slow suite
 - **Coverage**: 97% on core components
 
@@ -28,6 +28,7 @@ Test individual components in isolation with fast execution (<1 second per test)
 | `test_profiles.py` | Configuration profile system validation |
 | `test_mocks.py` | Mock community definitions, aliases, organism validation |
 | `test_species.py` | Species name resolution (GTDB/NCBI) |
+| `test_deps.py` | Dependency checking, install hints, pre-flight validation |
 
 ### Integration Tests
 
@@ -196,6 +197,7 @@ tests/
 ├── test_integration.py              # End-to-end tests
 ├── test_timing_integration.py       # Timing integration tests
 ├── test_edge_cases.py               # Edge case tests
+├── test_deps.py                     # Dependency checking and pre-flight
 ├── test_performance.py              # Performance benchmarks
 └── ...                              # Additional coverage files
 ```

docs/troubleshooting.md

@@ -71,6 +71,70 @@ pip install --user git+https://github.com/FOI-Bioinformatics/nanorunner.git
 
 ---
 
+## Missing Dependencies
+
+### Check All Dependencies
+
+Before investigating specific issues, run the dependency checker:
+
+```bash
+nanorunner check-deps
+```
+
+This shows the status of all required and optional dependencies with install instructions.
+
+### Badread Not Working
+
+**Symptom**: `badread exited with status 1` or `ModuleNotFoundError: No module named 'edlib'`
+
+**Explanation**: Badread may be installed but missing a Python dependency (e.g., edlib). NanoRunner verifies that backends can actually start, not just that their binary exists on PATH.
+
+**Solution**:
+```bash
+# Check dependency status
+nanorunner check-deps
+
+# Reinstall badread (includes all dependencies)
+conda install -c conda-forge -c bioconda badread
+```
+
+### NCBI Datasets CLI Not Found
+
+**Symptom**: `datasets CLI is required` when using `--species`, `--mock`, or `--taxid`
+
+**Solution**:
+```bash
+# Install NCBI datasets CLI
+conda install -c conda-forge ncbi-datasets-cli
+
+# Verify
+datasets --version
+```
+
+### NanoSim Not Working
+
+**Symptom**: `nanosim exited with status 1` or backend unavailable
+
+**Solution**:
+```bash
+# Install NanoSim
+conda install -c conda-forge -c bioconda nanosim
+
+# Verify
+nanorunner check-deps
+```
+
+### NumPy Not Installed
+
+**Symptom**: Slower read generation performance (falls back to pure Python)
+
+**Solution**:
+```bash
+conda install -c conda-forge numpy
+```
+
+---
+
 ## Runtime Issues
 
 ### Permission Denied on Target Directory
@@ -175,13 +239,16 @@ nanorunner replay -s /source -t /target --profile high_throughput
 **Solution**:
 ```bash
 # Install psutil
-pip install psutil
+conda install -c conda-forge psutil
 
 # Or install with enhanced extras
 pip install "nanorunner[enhanced] @ git+https://github.com/FOI-Bioinformatics/nanorunner.git@main"
 
 # Verify psutil
 python -c "import psutil; print('OK')"
+
+# Or check all dependencies at once
+nanorunner check-deps
 ```
 
 ### Progress Bar Not Displaying