Add user interface screenshot to documentation

README.md

@@ -0,0 +1,277 @@
+# hosts - /etc/hosts Manager
+
+A modern Python TUI (Text User Interface) application for managing your system's `/etc/hosts` file with ease and safety.
+
+## Overview
+
+The `hosts` application provides a powerful, user-friendly terminal interface for viewing, editing, and managing your `/etc/hosts` file. It eliminates the need for manual text editing while providing advanced features like DNS resolution, entry validation, and comprehensive backup capabilities.
+
+## Features
+
+### 🔍 **Read-Only Mode (Default)**
+- **Two-pane interface**: List view with detailed entry information
+- **Smart parsing**: Handles all real-world hosts file formats
+- **Sorting capabilities**: Sort by IP address or hostname
+- **Filtering options**: Hide/show system default entries
+- **Search functionality**: Find entries by hostname, IP, or comment
+- **Configuration management**: Persistent settings with modal interface
+- **Live reload**: Automatically refresh when hosts file changes
+
+### ✏️ **Edit Mode (Permission-Protected)**
+- **Safe editing**: Automatic backups before any modifications
+- **Entry management**: Add, delete, and modify host entries
+- **Activation control**: Toggle entries active/inactive
+- **Reordering**: Move entries up/down with keyboard shortcuts
+- **Undo/Redo system**: Full operation history with Ctrl+Z/Ctrl+Y
+- **Atomic operations**: Safe file writing with rollback capability
+- **Permission management**: Secure sudo handling for system file access
+
+### 🛡️ **Safety & Reliability**
+- **Automatic backups**: Timestamped backups before modifications
+- **Change detection**: Track modifications with save confirmation
+- **Input validation**: Comprehensive IP and hostname validation
+- **Error handling**: Graceful error recovery with user feedback
+- **File integrity**: Preserve comments and formatting
+
+## Installation
+
+### Prerequisites
+- Python 3.13 or higher
+- [uv](https://docs.astral.sh/uv/) package manager
+
+### Run with uv
+```bash
+uvx git+https://git.s1q.dev/phg/hosts.git
+```
+
+### Setup alias
+```bash
+# Install uv if not already installed
+echo "alias hosts=\"uvx git+https://git.s1q.dev/phg/hosts.git\"" >> ~/.zshrc
+```
+
+## Usage
+
+### Basic Usage
+```bash
+# Launch the application
+uv run hosts
+
+# Or if installed globally
+hosts
+```
+
+### Interface Overview
+
+![User Interface](./images/user_interface.png)
+
+### Keyboard Shortcuts
+
+#### Navigation
+- `↑/↓`: Navigate entries
+- `Home/End`: Go to first/last entry
+- `Page Up/Down`: Navigate by page
+
+#### View Operations
+- `Ctrl+e`: Toggle between Read-only and Edit mode
+- `Ctrl+r`: Reload hosts file
+- `i`: Sort by IP address
+- `h`: Sort by hostname
+- `c`: Open configuration modal
+- `q` or `Ctrl+C`: Quit application
+
+#### Edit Mode (requires sudo)
+- `e`: Toggle Entry edit mode
+- `Space`: Toggle entry active/inactive
+- `Shift+↑/↓`: Move entry up/down
+- `n`: Add new entry
+- `d`: Delete selected entry
+- `r`: Update the current select DNS based Entry
+- `Shift+r`: Update all DNS based Entries
+- `Ctrl+z`: Undo last operation
+- `Ctrl+y`: Redo operation
+- `Ctrl+s`: Save changes
+
+## Configuration
+
+The application stores its configuration in `~/.config/hosts-manager/config.json`:
+
+```json
+{
+  "show_default_entries": true,
+  "default_sort_column": "ip",
+  "default_sort_reverse": false,
+  "backup_directory": "~/.config/hosts-manager/backups"
+}
+```
+
+### Configuration Options
+- **show_default_entries**: Show/hide system default entries (localhost, etc.)
+- **default_sort_column**: Default sorting column ("ip" or "hostname")
+- **default_sort_reverse**: Default sort direction
+- **backup_directory**: Location for automatic backups
+
+## Architecture
+
+The application follows a clean, layered architecture:
+
+```
+src/hosts/
+├── main.py              # Application entry point
+├── core/                # Business logic layer
+│   ├── models.py        # Data models (HostEntry, HostsFile)
+│   ├── parser.py        # File parsing and writing
+│   ├── manager.py       # Edit operations and permissions
+│   ├── config.py        # Configuration management
+│   ├── dns.py           # DNS resolution (planned)
+│   ├── commands.py      # Command pattern for undo/redo
+│   ├── filters.py       # Entry filtering and search
+│   └── import_export.py # Data import/export utilities
+└── tui/                 # User interface layer
+    ├── app.py           # Main TUI application
+    ├── styles.py        # Visual styling
+    ├── keybindings.py   # Keyboard shortcuts
+    └── *.py             # Modal dialogs and components
+```
+
+### Key Components
+
+- **HostEntry**: Immutable data class representing a single hosts entry
+- **HostsFile**: Container managing collections of entries with operations
+- **HostsParser**: File I/O operations with atomic writing and backup
+- **HostsManager**: Edit mode operations with permission management
+- **HostsManagerApp**: Main TUI application with Textual framework
+
+## Development
+
+### Setup Development Environment
+```bash
+# Clone and enter directory
+git clone https://github.com/yourusername/hosts.git
+cd hosts
+
+# Install development dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check
+uv run ruff format
+```
+
+### Testing
+
+The project maintains comprehensive test coverage with 150+ tests:
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run specific test modules
+uv run pytest tests/test_models.py
+uv run pytest tests/test_parser.py
+
+# Run with coverage
+uv run pytest --cov=src/hosts
+```
+
+### Test Coverage
+- **Models**: Data validation and serialization (27 tests)
+- **Parser**: File operations and parsing (15 tests)  
+- **Manager**: Edit operations and permissions (38 tests)
+- **Configuration**: Settings persistence (22 tests)
+- **TUI Components**: User interface (28 tests)
+- **Commands**: Undo/redo system (43 tests)
+- **Integration**: End-to-end workflows (additional tests)
+
+### Code Quality
+
+The project uses `ruff` for linting and formatting:
+
+```bash
+# Check code quality
+uv run ruff check
+
+# Format code
+uv run ruff format
+
+# Fix auto-fixable issues
+uv run ruff check --fix
+```
+
+## Security Considerations
+
+- **Sudo handling**: Secure elevation only when entering edit mode
+- **File validation**: Comprehensive input validation and sanitization
+- **Atomic operations**: Safe file writing to prevent corruption
+- **Backup system**: Automatic backups before any modifications
+- **Permission boundaries**: Clear separation between read and edit operations
+
+## Troubleshooting
+
+### Common Issues
+
+**Permission denied when entering edit mode:**
+```bash
+# Ensure you can run sudo
+sudo -v
+
+# Check file permissions
+ls -la /etc/hosts
+```
+
+**Configuration not saving:**
+```bash
+# Ensure config directory exists
+mkdir -p ~/.config/hosts-manager
+
+# Check directory permissions
+ls -la ~/.config/
+```
+
+**Application won't start:**
+```bash
+# Check Python version
+python3 --version
+
+# Verify uv installation
+uv --version
+
+# Install dependencies
+uv sync
+```
+
+## Contributing
+
+We welcome contributions! Please see our development setup above.
+
+### Contribution Guidelines
+
+1. **Fork the repository** and create a feature branch
+2. **Write tests** for new functionality
+3. **Ensure all tests pass** with `uv run pytest`
+4. **Follow code style** with `uv run ruff check`
+5. **Submit a pull request** with clear description
+
+### Future Enhancements
+
+- **DNS Resolution**: Automatic hostname-to-IP resolution
+- **Import/Export**: Support for different file formats
+- **Advanced Filtering**: Complex search and filter capabilities
+- **Performance Optimization**: Large file handling improvements
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Support
+
+- **Issues**: Report bugs and feature requests on GitHub Issues
+- **Documentation**: See the [project wiki](https://github.com/yourusername/hosts/wiki)
+- **Discussions**: Join community discussions on GitHub Discussions
+
+---
+
+**Note**: This application modifies system files. Always ensure you have proper backups and understand the implications of hosts file changes. The application includes safety features, but system administration knowledge is recommended.