diff --git a/README.md b/README.md
index 274dbf1..84329e3 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,275 @@
-# local-commit-message-generator
+# Local Commit Message Generator
 
-A CLI tool that generates conventional commit messages by analyzing staged git changes. Runs completely offline using pattern matching.
\ No newline at end of file
+[![CI Status](https://7000pct.gitea.bloupla.net/7000pctAUTO/local-commit-message-generator/actions/workflows/ci.yml/badge.svg)](https://7000pct.gitea.bloupla.net/7000pctAUTO/local-commit-message-generator/actions)
+[![Version](https://img.shields.io/pypi/v/local-commit-message-generator.svg)](https://pypi.org/project/local-commit-message-generator/)
+[![Python](https://img.shields.io/pypi/pyversions/local-commit-message-generator.svg)](https://pypi.org/project/local-commit-message-generator/)
+[![License](https://img.shields.io/pypi/l/MIT.svg)](https://opensource.org/licenses/MIT)
+
+A CLI tool that generates conventional commit messages by analyzing staged git changes. Runs completely offline using pattern matching to detect changes and produce standardized commit messages.
+
+## Features
+
+- **Auto-detect commit type**: Automatically detects `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` based on file patterns
+- **Scope detection**: Detects scopes from changed directories
+- **Customizable templates**: Define your own commit message format via configuration
+- **Git hook integration**: Automatically generate commit messages on `git commit`
+- **Offline operation**: Runs completely offline with no external dependencies
+- **Multiple scopes**: Supports comma-separated scopes for changes across multiple directories
+
+## Installation
+
+### From Source
+
+```bash
+# Clone and install
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/local-commit-message-generator.git
+cd local-commit-message-generator
+pip install -e .
+```
+
+### Using pip
+
+```bash
+pip install local-commit-message-generator
+```
+
+## Quick Start
+
+1. Stage your changes:
+   ```bash
+   git add src/
+   ```
+
+2. Generate a commit message:
+   ```bash
+   commit-gen generate
+   ```
+
+3. Or preview what the message would be:
+   ```bash
+   commit-gen preview
+   ```
+
+## Usage
+
+### Commands
+
+#### generate
+Generate and display a commit message from staged changes.
+```bash
+commit-gen generate
+```
+
+#### preview
+Preview the commit message without printing it directly.
+```bash
+commit-gen preview
+```
+
+#### status
+Show current staged changes status.
+```bash
+commit-gen status
+```
+
+#### install-hook
+Install the prepare-commit-msg git hook for automatic message generation.
+```bash
+commit-gen install-hook
+```
+
+#### uninstall-hook
+Remove the git hook.
+```bash
+commit-gen uninstall-hook
+```
+
+#### config
+Manage configuration settings.
+```bash
+commit-gen config show              # Show current configuration
+commit-gen config set-template "custom: {description}"  # Set template
+commit-gen config reset            # Reset to defaults
+```
+
+## Configuration
+
+The tool uses `~/.local_commit_gen.toml` for configuration.
+
+### Default Configuration
+
+```toml
+template = "{type}{scope}: {description}"
+description_length = 72
+max_files = 5
+include_file_list = true
+file_list_template = "\n\nFiles changed:\n{files}"
+
+[type_rules]
+feat = ["src/", "lib/", "app/", "controllers/", "models/"]
+fix = ["src/", "lib/", "bug", "fix", "issue", "hotfix"]
+docs = [".md", ".rst", "docs/", "documentation/"]
+style = [".css", ".scss", ".sass", ".less", "styles/"]
+refactor = ["refactor/", "rewrite/", "restructure/"]
+test = ["test/", "tests/", "__tests__/", ".test.", ".spec."]
+chore = ["package.json", "pyproject.toml", "requirements", ".gitignore", "Makefile"]
+perf = ["performance/", "perf/", "optimize/", "optimization/"]
+ci = [".github/", ".gitlab-ci.yml", ".travis.yml", "Jenkinsfile", "tox.ini"]
+build = ["build/", "webpack/", "vite.config", "babel.config", "rollup.config"]
+```
+
+### Custom Templates
+
+Template variables available:
+- `{type}` - Commit type (feat, fix, docs, etc.)
+- `{scope}` - Commit scope in parentheses
+- `{description}` - Generated description
+- `{body}` - Extended body text
+- `{files}` - List of changed files
+
+Example:
+```toml
+template = "[{type}] ({scope}): {description}\n\n{files}"
+```
+
+### Custom Type Rules
+
+Define patterns to match for each commit type:
+
+```toml
+[type_rules]
+feat = ["src/features/", "myapp/"]
+fix = ["bugfix/", "hotfix/"]
+```
+
+### Scope Mapping
+
+Map directories to custom scope names:
+
+```toml
+[scopes]
+"app/features/auth" = "auth"
+"app/features/payments" = "payments"
+```
+
+## Git Hook Integration
+
+Install the prepare-commit-msg hook to automatically generate commit messages:
+
+```bash
+commit-gen install-hook
+```
+
+The hook will:
+1. Generate a commit message based on staged changes
+2. Write it to the commit message file
+3. Let you edit before finalizing
+
+To uninstall:
+```bash
+commit-gen uninstall-hook
+```
+
+## Examples
+
+### Feature Change
+```bash
+$ git add src/features/user.py
+$ commit-gen generate
+feat(user): add user.py
+```
+
+### Bug Fix
+```bash
+$ git add src/utils.py
+$ commit-gen generate
+fix(utils): update utils.py
+```
+
+### Documentation Update
+```bash
+$ git add README.md docs/guide.md
+$ commit-gen generate
+feat(docs): add files
+
+Files changed:
+  - README.md
+  - docs/guide.md
+```
+
+### Multiple Scopes
+```bash
+$ git add src/cli.py lib/core.py
+$ commit-gen generate
+feat(cli,lib): add files
+
+Files changed:
+  - src/cli.py
+  - lib/core.py
+```
+
+## Development
+
+### Setup
+
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # or `venv\Scripts\activate` on Windows
+
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v --cov=src --cov-report=term-missing
+
+# Run linting
+ruff check .
+```
+
+### Project Structure
+
+```
+local-commit-message-generator/
+├── src/
+│   ├── __init__.py       # Package init, version
+│   ├── analyzer.py      # Git change analysis
+│   ├── cli.py           # CLI interface
+│   ├── config.py        # Configuration management
+│   ├── generator.py     # Message generation logic
+│   ├── hooks.py         # Git hook integration
+│   └── templates.py     # Template management
+├── tests/
+│   ├── test_analyzer.py
+│   ├── test_cli.py
+│   ├── test_config.py
+│   ├── test_generator.py
+│   ├── test_hooks.py
+│   └── test_templates.py
+├── pyproject.toml
+├── README.md
+└── LICENSE
+```
+
+## Error Handling
+
+### "Not in git repository"
+Make sure you're running the command from within a git repository.
+
+### "No staged changes found"
+Run `git add <files>` to stage your changes before generating a commit message.
+
+### "Hook installation failed"
+Check that you have write permissions to the `.git/hooks/` directory.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `pytest tests/ -v`
+5. Submit a pull request
+
+## License
+
+MIT License