diff --git a/CLAUDE.md b/CLAUDE.md
index dfea887..503f705 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -847,14 +847,40 @@ The correct command uses the local `cli/package_skill.py` in the repository root
 - **Modern packaging**: PEP 621 compliant with proper dependency management
 - **MCP Integration**: 9 tools for Claude Code Max integration
 
+**CLI Architecture (Git-style subcommands):**
+- **Entry point**: `src/skill_seekers/cli/main.py` - Unified CLI dispatcher
+- **Subcommands**: scrape, github, pdf, unified, enhance, package, upload, estimate
+- **Design pattern**: Main CLI routes to individual tool entry points (delegates to existing main() functions)
+- **Backward compatibility**: Individual tools (`skill-seekers-scrape`, etc.) still work directly
+- **Key insight**: The unified CLI modifies sys.argv and calls existing main() functions to maintain compatibility
+
 **Development Workflow:**
 1. **Install**: `pip install -e .` (editable mode for development)
-2. **Run tests**: `pytest tests/` (391 tests)
+2. **Run tests**:
+   - All tests: `pytest tests/ -v`
+   - Specific test file: `pytest tests/test_scraper_features.py -v`
+   - With coverage: `pytest tests/ --cov=src/skill_seekers --cov-report=term --cov-report=html`
+   - Single test: `pytest tests/test_scraper_features.py::test_detect_language -v`
 3. **Build package**: `uv build` or `python -m build`
 4. **Publish**: `uv publish` (PyPI)
+5. **Run single config test**: `skill-seekers scrape --config configs/react.json --dry-run`
+
+**Test Architecture:**
+- **Test files**: 27 test files covering all features (see `tests/` directory)
+- **CI Matrix**: Tests run on Ubuntu + macOS with Python 3.10, 3.11, 3.12
+- **Coverage**: 39% code coverage (427 tests passing)
+- **Key test categories**:
+  - `test_scraper_features.py` - Core scraping functionality
+  - `test_mcp_server.py` - MCP integration (9 tools)
+  - `test_unified.py` - Multi-source scraping (18 tests)
+  - `test_github_scraper.py` - GitHub repository analysis
+  - `test_pdf_scraper.py` - PDF extraction
+  - `test_integration.py` - End-to-end workflows
+- **IMPORTANT**: Must run `pip install -e .` before tests (src/ layout requirement)
 
 **Key Points:**
 - Output is cached and reusable in `output/` (git-ignored)
 - Enhancement is optional but highly recommended
 - All 24 configs are working and tested
 - CI workflow requires `pip install -e .` to install package before running tests
+- Never skip tests - all tests must pass before commits (per user instructions)