diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 20b9c065..d8be3c13 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,59 +1,74 @@
 # Contributing to voice-mode
 
-Thank you for your interest in contributing to voice-mode! This guide will help you get started with development.
+Thank you for your interest in contributing to voice-mode! This guide will help you get started with making your first contribution.
+
+## Contribution Workflow
+
+Based on the project's development patterns, here's the typical workflow for contributions:
+
+1. **Fork and Clone**
+
+   - Fork the repository to your GitHub account
+   - Clone your fork locally
+   - Add the upstream repository as a remote
+
+2. **Set Up Development Environment**
+
+   - Follow the [Development Setup Guide](docs/tutorials/development-setup.md) for installation
+   - Ensure all tests pass before making changes
+
+3. **Create a Feature Branch**
+
+   - Use descriptive branch names (e.g., `feature/add-new-voice`, `fix/audio-playback-issue`)
+   - Branch from the main branch
+
+4. **Make Your Changes**
+
+   - Follow the existing code style and patterns
+   - Add tests for new functionality
+   - Update documentation if needed
+
+5. **Test Your Changes**
+
+   - Run the full test suite with `make test` or `uv run pytest`
+   - Test manually with different configurations
+   - Ensure no regressions in existing functionality
+
+6. **Commit Your Changes**
+
+   - Use conventional commit messages (see Commit Messages section below)
+   - Keep commits focused and atomic
+   - Write clear, descriptive commit messages
+
+7. **Submit a Pull Request**
+
+   - Push your branch to your fork
+   - Open a PR against the main repository
+   - Provide a clear description of changes and motivation
+   - Link any related issues
 
 ## Development Setup
 
-### Prerequisites
-
-- Python 3.10 or higher
-- [Astral UV](https://github.com/astral-sh/uv) - Package manager (install with `curl -LsSf https://astral.sh/uv/install.sh | sh`)
-- Git
-- A working microphone and speakers (for testing)
-- System dependencies (see README.md for OS-specific instructions)
-
-### Getting Started
-
-1. **Clone the repository**
-   ```bash
-   git clone https://github.com/mbailey/voicemode.git
-   cd voicemode
-   ```
-
-2. **Create a virtual environment**
-   ```bash
-   uv venv
-   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-   ```
-
-3. **Install in development mode**
-   ```bash
-   uv pip install -e .
-   uv pip install -e .[dev,test]
-   ```
-
-4. **Set up environment variables**
-   ```bash
-   # Set your API key
-   export OPENAI_API_KEY=your-key-here
-   
-   # Voice Mode will auto-generate ~/.voicemode/voicemode.env on first run
-   # You can edit this file to customize configuration
-   ```
+For detailed setup instructions, please see the [Development Setup Guide](docs/tutorials/development-setup.md).
 
-## Running Tests
+### Quick Start
 
-```bash
-# Run all tests
-pytest
+1. Clone the repository
+2. Create and activate a virtual environment with `uv venv`
+3. Install with `uv pip install -e .[dev,test]`
+4. Run tests with `uv run pytest` or `make test`
 
-# Run with coverage
-pytest --cov=voice_mode
+For troubleshooting and detailed instructions, refer to the [Development Setup Guide](docs/tutorials/development-setup.md).
 
-# Run specific test file
-pytest tests/test_server_syntax.py
+## Running Tests
+
+```bash
+# Quick start - run all tests
+uv run pytest
 ```
 
+For detailed testing options (coverage, specific files, parallel execution), see the [Testing section in the Development Setup Guide](docs/tutorials/development-setup.md#running-tests).
+
 ## Code Style
 
 - We use standard Python formatting conventions
@@ -63,46 +78,79 @@ pytest tests/test_server_syntax.py
 
 ## Testing Locally
 
-### Testing with MCP
+For local testing instructions including MCP integration and audio testing, see the [Manual Testing section](docs/tutorials/development-setup.md#manual-testing).
 
-1. Update `.mcp.json` to point to your development version
-2. Run `mcp` to test the connection
-3. Use the voice tools to verify functionality
+## Code Style
 
-### Testing Audio
+We use standard Python formatting conventions with Black and Ruff:
 
 ```bash
-# Test TTS and audio playback
-python -c "from voice_mode.core import text_to_speech; import asyncio; asyncio.run(text_to_speech(...))"
-```
+# Format code
+black voice_mode tests
 
-## Making Changes
+# Run linter
+ruff check voice_mode tests
+
+# Fix linting issues
+ruff check --fix voice_mode tests
+```
 
-1. Create a feature branch
-   ```bash
-   git checkout -b feature/your-feature-name
-   ```
+- Keep imports organized (stdlib, third-party, local)
+- Add type hints where appropriate
+- Document functions with docstrings
+- Follow existing patterns in the codebase
 
-2. Make your changes
-3. Run tests to ensure nothing is broken
-4. Commit with descriptive messages
-5. Push and create a pull request
+## Pre-commit Hooks
 
-## Debugging
+For automated code quality checks:
 
-Enable debug mode for detailed logging:
 ```bash
-export VOICEMODE_DEBUG=true
+# Install pre-commit
+pip install pre-commit
+
+# Install hooks
+pre-commit install
+
+# Run manually
+pre-commit run --all-files
 ```
 
-Debug recordings are saved to `~/.voicemode/audio/`
+## Commit Messages
+
+Follow conventional commits format for clear project history:
+
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation changes
+- `test:` Test additions or changes
+- `refactor:` Code refactoring
+- `chore:` Maintenance tasks
+
+Examples:
+
+- `feat: add support for custom voice models`
+- `fix: resolve audio playback issue on macOS`
+- `docs: update installation instructions`
+
+## Pull Request Process
+
+1. **Fork the repository** on GitHub OR create a branch
+2. **Create your feature branch** from main
+3. **Make changes with tests** - ensure new features have test coverage
+4. **Run the full test suite** to verify nothing is broken
+5. **Submit your pull request** with:
+   - Clear title and description
+   - Link to any related issues
+   - Description of testing performed
+   - Any breaking changes noted
+
+## Debugging
+
+For debugging instructions and troubleshooting, see the [Debugging section in the Development Setup Guide](docs/tutorials/development-setup.md#debugging).
 
 ## Common Development Tasks
 
-- **Update dependencies**: Edit `pyproject.toml` and run `uv pip install -e .`
-- **Build package**: `make build-package`
-- **Run tests**: `make test`
-- **Run linting**: `make lint` (if configured)
+For common tasks like building packages, updating dependencies, and running tests, see the [Common Development Tasks section](docs/tutorials/development-setup.md#common-development-tasks).
 
 ## Questions?
 
diff --git a/docs/tutorials/development-setup.md b/docs/tutorials/development-setup.md
index dcd2894d..121ba682 100644
--- a/docs/tutorials/development-setup.md
+++ b/docs/tutorials/development-setup.md
@@ -1,6 +1,5 @@
 # Development Setup
 
-
 *Note: These docs need review.*
 
 This guide covers setting up VoiceMode for development, including building from source, configuring your IDE, and contributing to the project.
@@ -24,15 +23,36 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
 pip install uv
 ```
 
-## Cloning the Repository
+## Quick Start (Recommended)
+
+The Makefile provides convenient targets for all common development tasks:
+
+```bash
+# Clone the repository
+git clone https://github.com/mbailey/voicemode
+cd voicemode
+
+# Install with development dependencies (creates venv automatically)
+make dev-install
+
+# Run tests to verify setup
+make test
+```
+
+That's it! The Makefile handles virtual environment creation, dependency installation, and test setup automatically.
+
+## Manual Setup (Alternative Method)
+
+If you prefer to set things up manually or need more control:
 
 ```bash
 # Clone the repository
 git clone https://github.com/mbailey/voicemode
 cd voicemode
 
-# Install in development mode
-uv tool install -e .
+# Create and activate virtual environment
+uv tool install -e .[dev,test]
+
 ```
 
 ## Development Workflow
@@ -55,8 +75,31 @@ uvx --from dist/voice_mode-*.whl voice-mode
 
 ### Running Tests
 
+#### Using Makefile (Recommended)
+
+The Makefile provides comprehensive test targets (see `make help`):
+
 ```bash
-# Run all tests
+# Run unit tests with pytest
+make test
+
+# Run tests with coverage report
+make coverage
+
+# Run all tests (including slow/manual)
+make test-all
+```
+
+#### Manual Testing (Alternative)
+
+If you prefer running tests directly:
+
+```bash
+# Using uv run (no activation needed)
+uv run pytest
+
+# using python
+source .venv/bin/activate
 pytest
 
 # Run with coverage
@@ -85,7 +128,7 @@ voicemode kokoro start
 
 ## Project Structure
 
-```
+```ini
 voicemode/
 ├── voice_mode/           # Main package
 │   ├── __init__.py
@@ -182,7 +225,7 @@ pytest tests/integration/test_whisper.py
 ### Manual Testing
 
 ```bash
-# Test voice conversation
+# Test voice conversation with debug output
 voice-mode converse --debug
 
 # Test specific tool
@@ -192,79 +235,108 @@ voice-mode test-tool converse
 VOICEMODE_TTS_BASE_URLS=http://localhost:8880/v1 voice-mode converse
 ```
 
-## Contributing
+### Testing Service Installations
 
-### Code Style
+Update your local '.voicemode.env' file to overide the default path `~/.voicemode`
 
-We use Black for formatting and Ruff for linting:
+```bash
+echo "VOICEMODE_BASE_DIR=/tmp/.voicemode" >> .voicemode.env
+```
+
+Use temporary directories when testing installers to prevent affecting your production setup in `~/.voicemode/services/`:
 
 ```bash
-# Format code
-black voice_mode tests
 
-# Run linter
-ruff check voice_mode tests
+# Test Whisper installation
+voicemode whisper install --force --install-dir /tmp/.voicemode/services/whisper/ --model large-v3-turbo
 
-# Fix linting issues
-ruff check --fix voice_mode tests
+# Test Kokoro installation
+voicemode kokoro install --force --install-dir /tmp/.voicemode/services/kokoro/ 
+
+# Test LiveKit installation
+voicemode livekit install --force --install-dir /tmp/.voicemode/services/livekit/ --port 7881
 ```
 
-### Pre-commit Hooks
+## Contributing
 
-```bash
-# Install pre-commit
-pip install pre-commit
+For guidelines on contributing to the project, including code style, commit conventions, and the pull request process, please see the [Contributing Guide](/CONTRIBUTING.md).
+
+## Makefile Commands Reference
+
+The Makefile is the primary tool for development tasks. Run `make help` for a comprehensive list of available targets.  Here is a sample of commonly used targets:
 
-# Install hooks
-pre-commit install
+### Essential Development Commands
 
-# Run manually
-pre-commit run --all-files
+```bash
+make help          # Show all available targets
+make dev-install   # Install package with development dependencies
+make test          # Run unit tests
+make clean         # Remove build artifacts and caches
 ```
 
-### Commit Messages
+### Testing & Coverage
 
-Follow conventional commits:
-- `feat:` New feature
-- `fix:` Bug fix
-- `docs:` Documentation
-- `test:` Tests
-- `refactor:` Code refactoring
-- `chore:` Maintenance
+```bash
+make test          # Run unit tests with pytest
+make coverage      # Run tests with coverage report
+make coverage-html # Generate and open HTML coverage report
+make test-unit     # Run unit tests only
+make test-integration # Run integration tests
+make test-all      # Run all tests (including slow/manual)
+make test-parallel # Run tests in parallel
+```
 
-### Pull Request Process
+### Building & Publishing
 
-1. Fork the repository
-2. Create feature branch
-3. Make changes with tests
-4. Run test suite
-5. Submit pull request
+```bash
+make build-package # Build Python package for PyPI
+make build-dev     # Build development package with auto-versioning
+make test-package  # Test package installation
+```
 
-## Makefile Commands
+### Documentation
 
 ```bash
-# Development
-make dev           # Install in dev mode
-make test         # Run tests
-make lint         # Run linters
-make format       # Format code
-
-# Building
-make build        # Build package
-make clean        # Clean build artifacts
-
-# Services
-make install-services  # Install local services
-make start-services   # Start local services
-make stop-services    # Stop local services
-
-# Documentation
-make docs         # Build documentation
-make docs-serve   # Serve docs locally
+make docs    # Build documentation
+make docs-serve    # Serve documentation locally (http://localhost:8000)
+make docs-build    # Build documentation site
+make docs-check    # Check documentation for errors (strict mode)
 ```
 
 ## Troubleshooting Development Issues
 
+### Common Issues
+
+#### "pytest: command not found"
+
+This happens when the virtual environment isn't activated. Solutions:
+
+- Use `make test` which handles everything automatically
+- Use `uv run pytest` instead (no activation needed)
+- Activate the venv: `source .venv/bin/activate`
+
+#### pyenv/VIRTUAL_ENV conflicts
+
+If you see warnings about VIRTUAL_ENV not matching the project environment:
+
+- This is usually harmless - uv will use the project's `.venv`
+- To avoid the warning, deactivate any other Python environments first
+
+#### Verifying Installation
+
+To check if everything is installed correctly:
+
+```bash
+# Check if pytest is installed
+uv run pytest --version
+
+# Check if voice_mode is installed in editable mode
+uv pip list | grep voice-mode
+
+# Run a simple test
+uv run pytest tests/test_server_syntax.py -v
+```
+
 ### Import Errors
 
 ```bash