diff --git a/README.md b/README.md
index 21dcd86..89ef820 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,196 @@
-# local-ai-commit-reviewer
+# Local AI Commit Reviewer CLI
 
-A CLI tool that reviews Git commits locally using lightweight LLMs (Ollama/MLX) before pushing
\ 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+-blue.svg)](https://www.python.org/downloads/)
+[![Gitea Actions](https://7000pct.gitea.bloupla.net/api/7000pctAUTO/local-ai-commit-reviewer/status/main?branch=main&style=flat)](https://7000pct.gitea.bloupla.net/7000pctAUTO/local-ai-commit-reviewer/actions)
+
+A CLI tool that reviews Git commits locally using lightweight LLMs (Ollama/MLX) before pushing. It analyzes staged changes, provides inline suggestions, and integrates with Git workflows while preserving code privacy through local processing.
+
+## Quick Start
+
+```bash
+# Install the tool
+pip install local-ai-commit-reviewer
+
+# Review staged changes before committing
+aicr review
+
+# Install pre-commit hook
+aicr install-hook
+
+# Review a specific commit
+aicr review --commit <sha>
+```
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install local-ai-commit-reviewer
+```
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/local-ai-commit-reviewer.git
+cd local-ai-commit-reviewer
+pip install -e .
+```
+
+### Prerequisites
+
+- Python 3.10+
+- [Ollama](https://ollama.ai/) running locally (or MLX for Apple Silicon)
+- Git
+
+## Configuration
+
+Create a `.aicr.yaml` file in your project root:
+
+```yaml
+llm:
+  endpoint: "http://localhost:11434"
+  model: "codellama"
+  timeout: 120
+
+review:
+  strictness: "balanced"
+
+hooks:
+  enabled: true
+  fail_on_critical: true
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AICR_LLM_ENDPOINT` | Custom LLM API endpoint | `http://localhost:11434` |
+| `AICR_MODEL` | Model name for reviews | `codellama` |
+| `AICR_CONFIG_PATH` | Path to config file | `.aicr.yaml` |
+| `AICR_NO_COLOR` | Disable colored output | `false` |
+
+## Usage
+
+### Review Staged Changes
+
+```bash
+# Review all staged changes
+aicr review
+
+# Review with strict mode
+aicr review --strictness strict
+
+# Review with permissive mode (only critical issues)
+aicr review --strictness permissive
+
+# Output as JSON
+aicr review --output json
+
+# Output as Markdown
+aicr review --output markdown
+```
+
+### Review Specific Commit
+
+```bash
+aicr review --commit abc123def
+```
+
+### Git Hook Integration
+
+```bash
+# Install pre-commit hook in current repository
+aicr install-hook --local
+
+# Install globally (for new repositories)
+aicr install-hook --global
+
+# Skip the hook
+git commit --no-verify
+```
+
+### Configuration Management
+
+```bash
+# Show current configuration
+aicr config --list
+
+# Set a configuration option
+aicr config --set llm.model "llama2"
+
+# Show config file path
+aicr config --path
+```
+
+### Model Management
+
+```bash
+# List available models
+aicr models
+
+# Check Ollama status
+aicr status
+```
+
+## Supported Languages
+
+- Python
+- JavaScript / TypeScript
+- Go
+- Rust
+- Java
+- C / C++
+- Ruby
+- PHP
+- Swift
+- Kotlin
+- Scala
+
+## Strictness Levels
+
+| Level | Description |
+|-------|-------------|
+| `permissive` | Only critical security and bug issues |
+| `balanced` | Security, bugs, and major style issues |
+| `strict` | All issues including performance and documentation |
+
+## Error Resolution
+
+| Error | Resolution |
+|-------|------------|
+| LLM connection refused | Start Ollama: `ollama serve` |
+| Model not found | Pull model: `ollama pull <model>` |
+| Not a Git repository | Run from within a Git repo |
+| No staged changes | Stage files: `git add <files>` |
+| Git hook permission denied | `chmod +x .git/hooks/pre-commit` |
+
+## Development
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run linting
+ruff check src/
+black src/ tests/
+
+# Type checking
+mypy src/
+```
+
+## 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.