diff --git a/README.md b/README.md
index e69de29..3d8b903 100644
--- a/README.md
+++ b/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.
diff --git a/images/user_interface.png b/images/user_interface.png
new file mode 100644
index 0000000..6e89b9a
Binary files /dev/null and b/images/user_interface.png differ