diff --git a/README.md b/README.md
index 57cab06..1fec705 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,244 @@
-# shell-safe-validator
+# Shell Safe Validator
 
-Shell script safety validator CLI tool that detects dangerous patterns, security vulnerabilities, and enforces best practices
\ No newline at end of file
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
+[![PyPI Version](https://img.shields.io/badge/pypi-v0.1.0-red)](https://pypi.org/project/shell-safe-validator/)
+
+A CLI tool that validates shell scripts and commands for safety issues before execution. It detects dangerous patterns like `rm -rf` with variables, unquoted variables, potential injection vulnerabilities, and missing error handling, suggesting safer alternatives with explanations.
+
+## Features
+
+- **Pattern-based dangerous command detection**: Identifies risky commands like `rm -rf` with variables, `sudo` without full path, `cp` without `-i`
+- **Security vulnerability scanning**: Detects command injection, path traversal, and shell metacharacter injection
+- **Best practices validation**: Checks for `set -e`, `set -u`, proper error handling, and quoted variables
+- **Interactive safe-mode execution**: Execute validated commands safely with confirmation prompts
+- **Configurable rule customization**: Load custom rules from YAML/JSON config files
+
+## Installation
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/shell-safe-validator.git
+cd shell-safe-validator
+pip install -e .
+```
+
+### From PyPI (coming soon)
+
+```bash
+pip install shell-safe-validator
+```
+
+## Usage
+
+### Validate a Shell Script
+
+```bash
+shell-safe-validator validate script.sh
+```
+
+### Check a Single Command
+
+```bash
+shell-safe-validator check "rm -rf $VAR"
+```
+
+### Execute Safely with Confirmation
+
+```bash
+shell-safe-validator safe-exec "rm -rf /tmp/old_files"
+```
+
+### Use Custom Configuration
+
+```bash
+shell-safe-validator validate script.sh --config custom_rules.yaml
+```
+
+## Commands
+
+### validate
+
+Validate a shell script file for safety issues.
+
+```bash
+shell-safe-validator validate [OPTIONS] FILE
+```
+
+Options:
+- `--config`: Path to custom rules YAML file
+- `--severity`: Minimum severity level to report (low, medium, high, critical)
+- `--output-format`: Output format (text, json, compact)
+
+### check
+
+Check a single shell command for safety issues.
+
+```bash
+shell-safe-validator check [OPTIONS] COMMAND
+```
+
+Options:
+- `--severity`: Minimum severity level to report
+- `--output-format`: Output format (text, json, compact)
+
+### safe-exec
+
+Execute a command safely with validation and confirmation.
+
+```bash
+shell-safe-validator safe-exec [OPTIONS] COMMAND
+```
+
+Options:
+- `--dry-run`: Show what would be executed without running
+- `--force`: Skip confirmation prompt
+
+## Configuration
+
+### Default Rules
+
+The tool comes with comprehensive default rules stored in `config/default_rules.yaml`. These rules cover:
+
+- **Critical**: Dangerous deletion commands, eval with variables, unrestricted sudo
+- **High**: Unquoted variables, command injection patterns, path traversal
+- **Medium**: Missing safety flags, improper error handling
+- **Low**: Style suggestions and best practices
+
+### Custom Rules
+
+You can create custom rule files in YAML format:
+
+```yaml
+rules:
+  - id: CUSTOM001
+    name: Custom Rule Name
+    pattern: rm -rf \$\w+
+    severity: critical
+    message: Custom message
+    suggestion: Use a safer alternative
+```
+
+### Configuration File Precedence
+
+1. `.shell-safe-validator.yaml` (project-level)
+2. `~/.config/shell-safe-validator/rules.yaml` (user-level)
+3. `config/default_rules.yaml` (built-in defaults)
+
+## Examples
+
+### Basic Validation
+
+```bash
+$ shell-safe-validator check "rm -rf $DIR"
+[CRITICAL] Dangerous deletion with variable
+  Command: rm -rf $DIR
+  Suggestion: Avoid using variables with rm -rf. Use absolute paths or verify the variable content first.
+```
+
+### Script Validation
+
+```bash
+$ shell-safe-validator validate deploy.sh
+Validating deploy.sh...
+
+[HIGH] ? Line 15:
+  Command: cp $SRC_DIR/* $DEST_DIR/
+  Matched: $SRC_DIR
+  Unquoted variable can cause word splitting and glob expansion
+  Suggestion: Always quote variables: "$VAR" instead of $VAR
+
+[MEDIUM] ? Line 23:
+  Command: npm install
+  Matched: npm install
+  Command without error handling
+  Suggestion: Add error handling with '|| exit 1' or '&&' operator
+
+Validation complete: 2 issue(s) found (0 critical, 1 high, 1 medium, 0 low)
+```
+
+### Safe Execution
+
+```bash
+$ shell-safe-validator safe-exec "mkdir -p /tmp/test"
+Warning: Command has 1 issue(s)
+  [LOW] Script missing shebang line
+Execute: mkdir -p /tmp/test
+⚠️  This command will create a directory. Proceed? [y/N]: y
+Command executed successfully
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/shell-safe-validator.git
+cd shell-safe-validator
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest tests/ -v
+pytest tests/ --cov=src
+```
+
+### Project Structure
+
+```
+shell-safe-validator/
+├── src/
+│   ├── __init__.py           # Package root
+│   ├── cli.py                # CLI entry point
+│   ├── models/               # Data models
+│   │   ├── __init__.py
+│   │   ├── finding.py        # Finding model
+│   │   ├── rule.py           # Rule model
+│   │   └── severity.py       # Severity enum
+│   ├── validators/           # Validation modules
+│   │   ├── __init__.py
+│   │   ├── patterns.py       # Pattern-based detection
+│   │   ├── security.py       # Security vulnerability scanning
+│   │   └── best_practices.py # Best practices validation
+│   ├── config/               # Configuration loading
+│   │   ├── __init__.py
+│   │   └── loader.py         # Config loader
+│   └── utils/                # Utility functions
+│       ├── __init__.py
+│       └── shell_parser.py   # Shell parsing utilities
+├── tests/
+│   ├── __init__.py
+│   ├── test_cli.py
+│   ├── test_config.py
+│   ├── test_utils.py
+│   └── test_validators/
+│       ├── __init__.py
+│       ├── test_patterns.py
+│       ├── test_security.py
+│       └── test_best_practices.py
+├── config/
+│   └── default_rules.yaml
+├── pyproject.toml
+├── LICENSE
+└── README.md
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Inspired by shellcheck and similar static analysis tools
+- Built with Click for CLI and PyYAML for configuration