diff --git a/README.md b/README.md
index bfb5fe6..6cc3460 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,344 @@
 # i18n-guardian
 
-Automated i18n linter and fixer CLI tool
\ 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.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-67%2F67%20passing-green.svg)]()
+
+A powerful CLI tool that automatically scans codebases for internationalization (i18n) issues like hardcoded strings, missing translation keys, and inconsistent locale patterns. It intelligently auto-detects i18n libraries in use, suggests proper translation key names following project conventions, and can auto-fix common issues with diff-based review before applying changes.
+
+## Features
+
+- **Auto i18n Library Detection**: Automatically detects react-intl, i18next, vue-i18n, gettext, python-gettext, and Flask-Babel
+- **Hardcoded String Detection**: Scans source code for strings that should be translated, excluding URLs, emails, regex patterns, and existing i18n calls
+- **Smart Translation Key Generation**: Generates proper translation keys following project naming conventions (snake_case, kebab-case, camelCase, PascalCase)
+- **Diff-based Preview**: Shows exactly what changes will be made before applying fixes
+- **Auto-fix Capability**: Automatically replaces hardcoded strings with proper i18n function calls
+- **Custom Rules**: Configure exclusions, thresholds, and naming patterns via YAML configuration
+- **CI/CD Integration**: JSON output format and appropriate exit codes for CI/CD pipeline integration
+- **Multi-language Support**: Supports JavaScript, TypeScript, Python (extensible architecture)
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install i18n-guardian
+```
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/i18n-guardian.git
+cd i18n-guardian
+pip install -e ".[dev]"
+```
+
+### Verification
+
+```bash
+i18n-guardian --version
+```
+
+## Quick Start
+
+### 1. Initialize Configuration
+
+```bash
+i18n-guardian init
+```
+
+This creates a `.i18n-guardian.yaml` configuration file in your project root.
+
+### 2. Scan for Hardcoded Strings
+
+```bash
+i18n-guardian scan
+```
+
+### 3. Preview Changes (Dry Run)
+
+```bash
+i18n-guardian fix --dry-run
+```
+
+### 4. Apply Fixes
+
+```bash
+i18n-guardian fix
+```
+
+## Commands
+
+### scan
+
+Scan the codebase for hardcoded strings that should be translated.
+
+```bash
+i18n-guardian scan [OPTIONS]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--output, -o` | Output format: `text` or `json` |
+| `--exclude` | Additional exclude patterns (glob) |
+| `--min-length` | Minimum string length to flag (default: 3) |
+| `--verbose, -v` | Enable verbose output |
+| `--path, -p` | Path to scan (defaults to current directory) |
+
+### fix
+
+Auto-fix i18n issues by replacing hardcoded strings with i18n function calls.
+
+```bash
+i18n-guardian fix [OPTIONS]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview changes without applying |
+| `--output, -o` | Output format: `text` or `json` |
+| `--verbose, -v` | Enable verbose output |
+| `--path, -p` | Path to scan (defaults to current directory) |
+
+### init
+
+Initialize a new configuration file.
+
+```bash
+i18n-guardian init [OPTIONS]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--output, -o` | Output file path (default: `.i18n-guardian.yaml`) |
+
+### check
+
+Check i18n compliance (ideal for CI/CD pipelines).
+
+```bash
+i18n-guardian check [OPTIONS]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--fail-level` | Minimum level to fail: `error`, `warning`, or `info` |
+| `--output, -o` | Output format: `text` or `json` |
+| `--verbose, -v` | Enable verbose output |
+| `--path, -p` | Path to scan (defaults to current directory) |
+
+## Configuration
+
+Create a `.i18n-guardian.yaml` file in your project root:
+
+```yaml
+# i18n Library Configuration
+i18n_library: react-intl  # Optional: auto-detected if not specified
+i18n_functions:
+  - formatMessage
+  - t
+  - $t
+
+# Scanning Options
+min_string_length: 3  # Minimum string length to flag
+key_style: snake_case  # snake_case, kebab-case, camelCase, PascalCase
+key_prefix: null  # Optional prefix for all generated keys
+
+# File Patterns
+include_patterns:
+  - "**/*.py"
+  - "**/*.js"
+  - "**/*.ts"
+  - "**/*.jsx"
+  - "**/*.tsx"
+
+exclude_patterns:
+  - "**/node_modules/**"
+  - "**/.git/**"
+  - "**/venv/**"
+  - "**/__pycache__/**"
+  - "**/dist/**"
+  - "**/build/**"
+
+# Output Options
+output_format: text  # text or json
+fail_level: error  # error, warning, or info
+```
+
+### Configuration Precedence
+
+1. `--config` CLI option (highest priority)
+2. `.i18n-guardian.yaml` in scan directory
+3. `i18n-guardian.yaml` in scan directory
+4. `~/.i18n-guardian.yaml` (home directory)
+5. Default values (lowest priority)
+
+## Supported i18n Libraries
+
+| Library | Detected By | Key Format |
+|---------|-------------|------------|
+| react-intl | package.json, webpack config, imports | Object keys |
+| i18next | i18n config, imports | Nested keys |
+| vue-i18n | Vue imports, plugins | Dot notation |
+| gettext | .po/.pot files | Message IDs |
+| python-gettext | gettext imports | Message IDs |
+| Flask-Babel | Flask app imports | Message IDs |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success (no violations) |
+| 1 | Error (invalid config, missing files, etc.) |
+| 2 | Violations found (for `check` command) |
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Check i18n Compliance
+  run: i18n-guardian check --output json --fail-level error
+```
+
+### GitLab CI
+
+```yaml
+i18n-check:
+  image: python:3.12
+  script:
+    - pip install i18n-guardian
+    - i18n-guardian check --output json --fail-level error
+```
+
+### Jenkins
+
+```groovy
+pipeline {
+    agent any
+    stages {
+        stage('Check i18n') {
+            steps {
+                sh 'pip install i18n-guardian && i18n-guardian check --output json'
+            }
+        }
+    }
+}
+```
+
+### Gitea Actions
+
+```yaml
+- name: i18n Check
+  run: i18n-guardian check --output json --fail-level error
+```
+
+## Key Generation
+
+i18n-guardian generates translation keys based on:
+
+1. **Text Content**: The string text is normalized and converted to the chosen key style
+2. **File Path**: Keys include path-based prefixes (e.g., `components_button_submit`)
+3. **Context**: Optional context information can be included
+4. **Uniqueness**: Duplicate keys are automatically numbered
+
+### Key Styles
+
+```yaml
+# snake_case (default)
+welcome_message
+
+# kebab-case
+welcome-message
+
+# camelCase
+welcomeMessage
+
+# PascalCase
+WelcomeMessage
+```
+
+## Architecture
+
+```
+i18n_guardian/
+├── cli.py           # Click CLI entry point
+├── config/          # Configuration loading and management
+│   └── __init__.py
+├── detectors/       # i18n library detection
+│   ├── base.py
+│   ├── react_intl.py
+│   ├── i18next.py
+│   ├── vue_i18n.py
+│   ├── gettext.py
+│   └── python_gettext.py
+├── scanners/        # String scanning
+│   ├── string_scanner.py
+│   └── __init__.py
+├── keygen/          # Key generation
+│   └── key_generator.py
+├── parsers/         # Code parsing (tree-sitter)
+├── diff/            # Diff generation for preview
+├── utils/           # Utility functions
+└── version.py
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/i18n-guardian.git
+cd i18n-guardian
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ -v --cov=i18n_guardian --cov-report=term-missing
+
+# Run specific test file
+pytest tests/test_cli.py -v
+```
+
+### Linting
+
+```bash
+ruff check i18n_guardian/ tests/
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
+
+## Support
+
+- **Issues**: Report bugs and feature requests on the [issue tracker](https://7000pct.gitea.bloupla.net/7000pctAUTO/i18n-guardian/issues)
+- **Documentation**: See this README and the [wiki](https://7000pct.gitea.bloupla.net/7000pctAUTO/i18n-guardian/wiki)