diff --git a/README.md b/README.md
index a58eab9..b7b3cb7 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,220 @@
-# config-convert-cli
+# ConfigConvert CLI
 
-A CLI tool for bidirectional conversion between JSON, YAML, TOML, and ENV config formats with smart type inference, validation, flatten/unflatten operations, schema generation, and automatic shell completion support.
\ No newline at end of file
+A powerful CLI tool for bidirectional conversion between JSON, YAML, TOML, and ENV config formats with smart type inference, validation, flatten/unflatten operations, schema generation, and automatic shell completion support.
+
+## Features
+
+- **Bidirectional Conversion**: Convert between any combination of supported formats
+- **Smart Type Inference**: Automatically detect and convert string values to appropriate Python types
+- **Syntax Validation**: Validate syntax of input files before conversion
+- **Flatten/Unflatten**: Transform nested structures to/from dot-notation keys
+- **Schema Generation**: Generate JSON Schema from parsed configurations
+- **Shell Completion**: Built-in support for bash, zsh, and fish completions
+- **Offline Operation**: Runs entirely offline with minimal dependencies
+- **Rich Output**: Beautiful terminal output using Rich library
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install config-convert-cli
+```
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/config-convert-cli.git
+cd config-convert-cli
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Convert between formats
+
+```bash
+# Convert JSON to YAML
+config-convert convert input.json --to yaml -o output.yaml
+
+# Convert YAML to JSON with custom indentation
+config-convert convert config.yaml --from yaml --to json --indent 4
+
+# Convert ENV to JSON
+config-convert convert .env --from env --to json
+
+# Read from stdin
+cat config.json | config-convert convert --stdin --from json --to yaml
+
+# Pretty print output
+config-convert convert config.json --to yaml --indent 2
+```
+
+### Validate syntax
+
+```bash
+# Validate a config file
+config-convert validate config.yaml
+
+# Validate from stdin
+echo '{"name": "test"}' | config-convert validate --stdin --format json
+```
+
+### Flatten nested structures
+
+```bash
+# Flatten nested JSON to ENV format
+config-convert flatten config.json --output flat.env
+
+# Flatten to another structured format
+config-convert flatten config.json --format yaml
+```
+
+### Unflatten to nested structures
+
+```bash
+# Unflatten ENV to JSON
+config-convert unflatten flat.env --format json --output nested.json
+```
+
+### Generate JSON Schema
+
+```bash
+# Generate schema from config
+config-convert schema config.json -o schema.json
+
+# Generate and display schema
+config-convert schema config.json
+```
+
+### List supported formats
+
+```bash
+config-convert formats
+```
+
+## Supported Formats
+
+| Format | Extensions | Read | Write |
+|--------|------------|------|-------|
+| JSON   | .json      | Yes  | Yes   |
+| YAML   | .yaml, .yml| Yes  | Yes   |
+| TOML   | .toml      | Yes  | Yes   |
+| ENV    | .env       | Yes  | Yes   |
+
+## Shell Completion
+
+### Bash
+
+```bash
+# Install completions for current user
+config-convert --install-completion bash
+
+# Or source directly
+source <(config-convert --show-completion bash)
+```
+
+### Zsh
+
+```bash
+config-convert --install-completion zsh
+```
+
+### Fish
+
+```bash
+config-convert --install-completion fish
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| CONFIG_CONVERT_THEME | Color theme for Rich output | default |
+| CONFIG_CONVERT_INDENT | Default indentation for output | 2 |
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments |
+| 3 | File not found |
+| 4 | Syntax error in input |
+| 5 | Conversion error |
+
+## Development
+
+### Setup
+
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest --cov=config_convert --cov-report=term-missing
+
+# Run linting
+ruff check .
+```
+
+### Project Structure
+
+```
+config-convert-cli/
+├── config_convert/
+│   ├── __init__.py
+│   ├── cli.py
+│   ├── converters/
+│   │   ├── __init__.py
+│   │   ├── base.py
+│   │   ├── json_converter.py
+│   │   ├── yaml_converter.py
+│   │   ├── toml_converter.py
+│   │   └── env_converter.py
+│   ├── utils/
+│   │   ├── __init__.py
+│   │   ├── type_inference.py
+│   │   ├── flatten.py
+│   │   └── schema.py
+│   └── validators/
+│       ├── __init__.py
+│       └── syntax.py
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py
+│   ├── test_cli.py
+│   ├── test_converters/
+│   ├── test_type_inference.py
+│   ├── test_flatten.py
+│   ├── test_schema.py
+│   ├── test_validators.py
+│   └── fixtures/
+├── scripts/
+│   └── completions.py
+├── pyproject.toml
+├── requirements.txt
+└── README.md
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests and linting
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.