diff --git a/CLAUDE.md b/CLAUDE.md
index c8b46c9..45af3e5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -16,6 +16,40 @@ This document outlines coding standards, architectural principles, and developme
 - **Documentation**: Code must be well-documented with explanations of WHY, not just what
 - **Validation**: Shell scripts must pass `shellcheck` validation
 
+## Build System and Development Workflow
+
+### Make Targets
+The project uses a comprehensive Makefile for build automation:
+
+#### Core Build Commands
+- `make build` - Build main skyview binary
+- `make build-all` - Build all binaries (skyview, beast-dump, skyview-data)
+- `make clean` - Clean build artifacts
+- `make dev` - Run in development mode
+- `make run` - Build and run the main binary
+
+#### Code Quality Commands
+- `make test` - Run all tests
+- `make lint` - Run golangci-lint (if available)
+- `make format` - Format code with go fmt
+- `make vet` - Run go vet static analysis
+- `make check` - Run all quality checks (format, vet, lint, test)
+
+#### Package Management
+- `make deb` - Build Debian package
+- `make deb-install` - Install Debian package (requires sudo)
+- `make deb-remove` - Remove installed Debian package (requires sudo)
+- `make deb-clean` - Clean Debian build artifacts
+
+#### Container Support
+- `make docker-build` - Build Docker image
+- `make podman-build` - Build Podman image (preferred for rootless containers)
+
+### Required Build Environment
+- **CGO_ENABLED=1**: Required for SQLite3 database support
+- **Go Modules**: Use `make install-deps` to ensure dependencies are current
+- **Version Injection**: Version is automatically injected from git tags
+
 ## SkyView Architecture Guidelines
 
 ### Core Features
@@ -39,6 +73,11 @@ This document outlines coding standards, architectural principles, and developme
 - **ui-manager**: User interface controls and event handling
 - **websocket**: Real-time data streaming from server
 
+#### Command Line Tools
+- **skyview**: Main server application
+- **beast-dump**: Raw ADS-B message debugging utility
+- **skyview-data**: Database management and status tools
+
 ### Performance Requirements
 
 #### Message Processing
@@ -51,12 +90,33 @@ This document outlines coding standards, architectural principles, and developme
 - **Indexing**: Use proper indexes to avoid N+1 queries
 - **Fast Lookups**: ICAO country resolution must be efficient
 - **Bounded History**: Implement automatic cleanup of stale data
+- **SQLite Integration**: Use embedded SQLite with CGO support
+
+## Development Process
+
+### Pre-commit Checks
+Always run before committing:
+```bash
+make check  # Runs format, vet, lint, and test
+```
+
+### Testing Strategy
+- **Unit Tests**: Test individual components and functions
+- **Integration Tests**: Test component interactions
+- **Performance Tests**: Validate throughput requirements
+- **Manual Testing**: Verify aviation-specific scenarios
+
+### Continuous Integration
+- All code changes must pass `make check`
+- Debian packages must build successfully
+- Container builds must complete without errors
 
 ## Documentation Standards
 
 ### Required Documentation
 - **Architecture**: Keep `docs/ARCHITECTURE.md` current with system design changes
 - **User Guide**: Maintain up-to-date `README.md` with features and usage instructions  
+- **Database Schema**: Document database structure in `docs/DATABASE.md`
 - **External References**: Link to ICAO docs, ADS-B standards, and other resources
 - **Code Comments**: Explain complex algorithms, especially CPR decoding and data fusion logic
 
@@ -80,6 +140,16 @@ This document outlines coding standards, architectural principles, and developme
 - Include Debian package builds in releases
 - Provide comprehensive release notes with feature descriptions
 - Tag releases properly for easy version tracking
+- **Version Updates**: When creating releases, update ALL version references:
+  - Web pages and HTML templates
+  - Man pages and documentation
+  - Debian package control files
+  - Configuration examples
+
+### Container Strategy
+- **Prefer Podman**: Use rootless Podman over Docker when possible
+- **Build Format**: Use `BUILDAH_FORMAT=docker` for Podman containers to support health status
+- **Multi-stage Builds**: Optimize container size with proper layering
 
 ## Aviation Domain Considerations
 
@@ -101,7 +171,33 @@ This document outlines coding standards, architectural principles, and developme
 - Provide clear visual indicators for data quality and source reliability
 - Handle edge cases that could confuse air traffic interpretation
 
+## User Experience Guidelines
+
+### Mobile Responsiveness
+- All future UX changes should consider mobile-friendly design
+- Never sacrifice desktop/non-mobile functionality for mobile compatibility
+- Implement progressive enhancement where possible
+- Test on multiple screen sizes and orientations
+
+### Performance Expectations
+- Real-time updates must remain smooth with 100+ aircraft
+- Map interactions should be responsive even under high load
+- Database queries must complete within acceptable timeouts
+- WebSocket connections should handle network interruptions gracefully
+
+## Security and Safety
+
+### Process Management
+- **Critical**: Never terminate processes using xargs
+- Always verify process identity before stopping/killing
+- Exercise extreme caution with system-level operations
+
+### Data Validation
+- Validate all input data, especially from external ADS-B sources
+- Implement rate limiting for external data sources
+- Sanitize user inputs in web interface
+- Log security-relevant events appropriately
+
 ---
 
-These guidelines ensure SkyView remains reliable, maintainable, and suitable for aviation use while supporting continued development and enhancement.
-- All future changes to the UX should keep in mind a gradual move to a mobile friendly design, but not at the cost of a working and useful UI for non-mobile clients.
\ No newline at end of file
+These guidelines ensure SkyView remains reliable, maintainable, and suitable for aviation use while supporting continued development and enhancement. All development work should follow these standards to maintain code quality and system reliability.
\ No newline at end of file