diff --git a/README.md b/README.md
index 835d2ef..05a4a05 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,323 @@
-# regex-humanizer
+# Regex Humanizer CLI
 
-A CLI tool that converts complex regular expressions into human-readable plain English descriptions with bidirectional conversion, example generation, and multi-flavor support.
\ No newline at end of file
+A CLI tool that converts complex regular expressions into human-readable plain English descriptions with bidirectional conversion, example generation, and multi-flavor support.
+
+## Overview
+
+Regex Humanizer helps developers understand and work with regular expressions by:
+
+- **Explaining** complex regex patterns in plain English
+- **Generating** concrete example strings that match patterns
+- **Converting** natural language descriptions to regex patterns
+- **Supporting** multiple regex flavors (PCRE, JavaScript, Python, Go)
+- **Building** patterns interactively through a guided wizard
+
+## Installation
+
+### From Source
+
+```bash
+git clone <repository-url>
+cd regex-humanizer
+pip install -e .
+```
+
+### Using pip
+
+```bash
+pip install regex-humanizer
+```
+
+### Development Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Explain a regex pattern
+
+```bash
+# Simple pattern
+regex-humanizer explain "^\w+@\w+\.\w+$"
+
+# With specific flavor
+regex-humanizer explain "hello" --flavor python
+
+# Verbose output
+regex-humanizer explain "\d{3}-\d{4}" --verbose
+
+# JSON output
+regex-humanizer explain "[a-z]+" --json
+```
+
+### Generate matching examples
+
+```bash
+# Generate example matches
+regex-humanizer generate "\d{3}-\d{4}"
+
+# Specify number of examples
+regex-humanizer generate "[abc]+" --count 10
+
+# JSON output
+regex-humanizer generate "\w+" --json
+```
+
+### Convert English to regex
+
+```bash
+# Basic conversion
+regex-humanizer from-english "a digit followed by a letter"
+
+# With flavor
+regex-humanizer from-english "one or more letters" --flavor javascript
+
+# JSON output
+regex-humanizer from-english "start of string followed by digits" --json
+```
+
+### Interactive pattern builder
+
+```bash
+# Start the wizard
+regex-humanizer build
+```
+
+## Commands
+
+### explain
+
+Explain a regex pattern in plain English.
+
+```bash
+regex-humanizer explain PATTERN [OPTIONS]
+```
+
+Options:
+- `--flavor TEXT`: Regex flavor (pcre, javascript, python, go) [default: pcre]
+- `--verbose/--simple`: Show detailed breakdown
+- `--json`: Output in JSON format
+
+### generate
+
+Generate example strings that match the pattern.
+
+```bash
+regex-humanizer generate PATTERN [OPTIONS]
+```
+
+Options:
+- `--flavor TEXT`: Regex flavor [default: pcre]
+- `-n, --count INTEGER`: Number of examples [default: 5]
+- `--json`: Output in JSON format
+
+### from-english
+
+Convert an English description to a regex pattern.
+
+```bash
+regex-humanizer from-english DESCRIPTION [OPTIONS]
+```
+
+Options:
+- `--flavor TEXT`: Target regex flavor [default: pcre]
+- `--json`: Output in JSON format
+
+### build
+
+Launch the interactive pattern builder wizard.
+
+```bash
+regex-humanizer build
+```
+
+### flavors
+
+List all supported regex flavors.
+
+```bash
+regex-humanizer flavors
+```
+
+### detect
+
+Detect the flavor of a regex pattern based on syntax.
+
+```bash
+regex-humanizer detect PATTERN
+```
+
+## Examples
+
+### Email pattern
+
+```bash
+$ regex-humanizer explain "^\w+@[a-z]+\.[a-z]+$"
+Pattern: ^\w+@[a-z]+\.[a-z]+$
+Flavor: pcre
+
+Description:
+the start of the string, one or more word characters, the literal character '@', one or more lowercase letters, the literal character '.', one or more lowercase letters, and the end of the string
+```
+
+### Phone number pattern
+
+```bash
+$ regex-humanizer generate "\d{3}-\d{3}-\d{4}"
+Pattern: \d{3}-\d{3}-\d{4}
+
+Matching examples:
+  1. 123-456-7890
+  2. 555-123-4567
+  3. 987-654-3210
+  4. 111-222-3333
+  5. 444-555-6666
+```
+
+### Complex pattern with groups
+
+```bash
+$ regex-humanizer explain "(?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})"
+Pattern: (?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})
+Flavor: pcre
+
+Description:
+a named 'year' group containing: exactly 4 digits, the literal character '-', a named 'month' group containing: exactly 2 digits, the literal character '-', and a named 'day' group containing: exactly 2 digits
+```
+
+## Features
+
+### Regex to English Conversion
+
+Parse any regex pattern and generate a human-readable explanation:
+- Literals and escaped characters
+- Character classes and ranges
+- Quantifiers (greedy, lazy, possessive)
+- Anchors (^, $, \b, \B)
+- Groups (capturing, non-capturing, named)
+- Alternations (|)
+- Special sequences (\d, \w, \s, etc.)
+
+### Example Match Generation
+
+Generate concrete strings that match a pattern:
+- Support for all pattern types
+- Multiple examples per pattern
+- Random generation for variety
+- Fallback to test string matching
+
+### Bidirectional Conversion
+
+Convert natural language to regex and back:
+- Parse English descriptions
+- Generate valid regex patterns
+- Round-trip validation
+
+### Multi-Flavor Support
+
+Support for PCRE, JavaScript, Python, and Go:
+- Feature detection per flavor
+- Compatibility warnings
+- Flavor-aware parsing
+
+### Interactive Wizard
+
+Build patterns step by step:
+- Guided interface
+- Real-time preview
+- Instant explanations
+- Edit and navigation support
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PYTHONPATH` | Python path for imports (set to `src`) |
+
+### Configuration Files
+
+- `.pre-commit-config.yaml`: Pre-commit hooks for code quality
+- `pyproject.toml`: Project configuration and dependencies
+
+## Development
+
+### Setup
+
+```bash
+git clone <repository-url>
+cd regex-humanizer
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=src
+
+# Run specific test file
+pytest tests/test_parser.py -v
+```
+
+### Linting
+
+```bash
+# flake8
+flake8 src/ tests/
+
+# mypy type checking
+mypy src/
+```
+
+### Code Formatting
+
+```bash
+# Black formatting
+black src/ tests/
+
+# isort imports
+isort src/ tests/
+```
+
+### Pre-commit Hooks
+
+```bash
+# Install pre-commit hooks
+pre-commit install
+
+# Run all hooks manually
+pre-commit run --all-files
+```
+
+## Testing Strategy
+
+The project includes comprehensive tests:
+
+- **Unit tests**: Parser, converter, examples, flavors modules
+- **Integration tests**: CLI commands end-to-end
+- **Test files**:
+  - `tests/test_parser.py`: Tokenization and AST tests
+  - `tests/test_converter.py`: English description tests
+  - `tests/test_examples.py`: Example generation tests
+  - `tests/test_flavors.py`: Flavor support tests
+  - `tests/test_cli.py`: CLI command tests
+
+## Error Handling
+
+The tool handles common errors gracefully:
+
+- **Invalid regex syntax**: Clear error messages with position info
+- **Unsupported features**: Warnings for flavor incompatibilities
+- **No matches found**: Alternative example generation
+- **Conversion loss**: Round-trip validation warnings
+
+## License
+
+MIT License