docs: update CLAUDE.md with new make commands

Author: S1M0N38

CLAUDE.md

@@ -4,112 +4,78 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Development Commands
 
-### Linting and Type Checking
+### Quick Start with Makefile
 
-```bash
-# Run ruff linter and formatter
-ruff check .
-ruff check --select I --fix .
-ruff format .
-
-# Run markdown formatter
-mdformat .
-
-# Run type checker
-basedpyright
-```
-
-### Testing
-
-**IMPORTANT**: Tests require Balatro to be running in the background. Use `./balatro.sh --status` to check if the game is running.
+The project includes a comprehensive Makefile with all development workflows. Run `make help` to see all available commands:
 
 ```bash
-# Run all tests (requires Balatro to be running) - stops after first failure
-pytest
+# Show all available commands with descriptions
+make help
 
-# Run specific test file - stops after first failure
-pytest tests/lua/test_api_functions.py
+# Quick development workflow (format + lint + typecheck)
+make dev
 
-# Run tests with verbose output - stops after first failure
-pytest -vx
+# Complete workflow including tests
+make all
 
-# Run tests on specific port
-pytest --port 12347 tests/lua/endpoints/test_cash_out.py
+# Install development dependencies
+make install-dev
 ```
 
-#### Parallel Testing with Multiple Balatro Instances
-
-The test suite supports running tests in parallel across multiple Balatro instances. This dramatically reduces test execution time by distributing tests across multiple game instances.
-
-**Setup for Parallel Testing:**
-
-1. **Check existing instances and start multiple Balatro instances on different ports**:
-
-    ```bash
-    # First, check if any instances are already running
-    ./balatro.sh --status
-
-    # If you need to kill all existing instances first:
-    ./balatro.sh --kill
-    ```
+### Code Quality and Linting
 
-    ```bash
-    # Start two instances with a single command
-    ./balatro.sh -p 12346 -p 12347
-
-    # With performance optimizations for faster testing
-    ./balatro.sh --fast -p 12346
-
-    # Headless mode for server environments
-    ./balatro.sh --headless -p 12346
+```bash
+make lint              # Check code with ruff linter
+make lint-fix          # Auto-fix linting issues
+make format            # Format code with ruff
+make format-md         # Format markdown files
+make typecheck         # Run type checker
+make quality           # Run all quality checks
+```
 
-    # Fast Headless mode on 4 instances (recommended configuration)
-    ./balatro.sh --headless --fast -p 12346 -p 12347 -p 12348 -p 12349
-    ```
+### Testing
 
-2. **Run tests in parallel**:
+```bash
+make test              # Run tests with single instance (auto-starts if needed)
+make test-parallel     # Run tests on 4 instances (auto-starts if needed)
+make test-teardown     # Kill all Balatro instances
+make test-verbose      # Run tests with verbose output
+make coverage          # Generate coverage reports
+```
 
-    ```bash
-    # Two workers (faster than single instance)
-    pytest -n 4 --port 12346 --port 12347 tests/lua/
+**Testing Features:**
 
-    # Four workers (maximum parallelization)
-    pytest -n 4 --port 12346 --port 12347 --port 12348 --port 12349 tests/lua/
-    ```
+- **Auto-start**: Both `test` and `test-parallel` automatically start Balatro instances if not running
+- **Parallel speedup**: `test-parallel` provides ~4x speedup with 4 workers
+- **Instance management**: Tests keep instances running after completion
+- **Port isolation**: Each worker uses its dedicated Balatro instance (ports 12346-12349)
 
-**Benefits:**
+**Usage:**
 
-- **Faster test execution**: ~4x speedup with 4 parallel workers
-- **Port isolation**: Each worker uses its dedicated Balatro instance
+- `make test` - Simple single-instance testing (auto-handles everything)
+- `make test-parallel` - Fast parallel testing (auto-handles everything)
+- `make test-teardown` - Clean up when done testing
 
 **Notes:**
 
-- Each Balatro instance must be running on a different port before starting tests
-- Tests automatically distribute across available workers
 - Monitor logs for each instance: `tail -f logs/balatro_12346.log`
 - Logs are automatically created in the `logs/` directory with format `balatro_PORT.log`
 
-#### Test Prerequisites and Workflow
-
-0. **Check existing instances first**:
+### Documentation
 
 ```bash
-# Check if Balatro instances are already running
-./balatro.sh --status
-
-# If instances are running on needed ports, you can proceed with testing
-# If you need to kill all running instances and start fresh:
-./balatro.sh --kill
+make docs-serve        # Serve documentation locally
+make docs-build        # Build documentation
+make docs-clean        # Clean documentation build
 ```
 
-### Documentation
+### Build and Maintenance
 
 ```bash
-# Serve documentation locally
-mkdocs serve
-
-# Build documentation
-mkdocs build
+make install           # Install package dependencies
+make install-dev       # Install with development dependencies
+make build             # Build package for distribution
+make clean             # Clean all build artifacts and caches
 ```
 
 ## Architecture Overview