diff --git a/README.md b/README.md
index ec08e86..b9c8e03 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,258 @@
 # gitignore-generator-cli
 
-A CLI tool that generates .gitignore files by specifying technologies/frameworks. Supports 100+ frameworks via gitignore.io integration with offline caching.
\ No newline at end of file
+A CLI tool that generates `.gitignore` files by specifying technologies/frameworks. Supports 100+ frameworks via gitignore.io integration with offline caching.
+
+[![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.8+-blue.svg)](https://www.python.org/downloads/)
+
+## Features
+
+- **Generate .gitignore** - Combine patterns from multiple tech stacks
+- **Auto-detect** - Scan project files and suggest appropriate tech stacks
+- **Preview mode** - Preview generated content before writing
+- **Offline caching** - Fast access to patterns with configurable cache expiration
+- **Custom patterns** - Add your own patterns to generated output
+- **100+ frameworks** - Full support via gitignore.io API
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install gitignore-generator-cli
+```
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/gitignore-generator-cli.git
+cd gitignore-generator-cli
+pip install -e .
+```
+
+## Quick Start
+
+### Generate .gitignore for specific technologies
+
+```bash
+# Generate for Node.js and Python
+gitignore-generator generate node python
+
+# Generate and save to .gitignore
+gitignore-generator generate node python -o .gitignore
+
+# Preview without writing
+gitignore-generator generate node python --preview
+```
+
+### Auto-detect project type
+
+```bash
+# Detect and suggest
+gitignore-generator detect
+
+# Detect and generate
+gitignore-generator detect --preview
+gitignore-generator detect -o .gitignore
+```
+
+### List supported technologies
+
+```bash
+# List all
+gitignore-generator list
+
+# Filter by name
+gitignore-generator list python
+```
+
+### Show patterns for a technology
+
+```bash
+gitignore-generator show node
+```
+
+## Commands
+
+### generate
+
+Generate .gitignore for specified tech stacks.
+
+```bash
+gitignore-generator generate [OPTIONS] TECH...
+
+Options:
+  -o, --output PATH     Output file path (default: stdout)
+  --preview             Preview without writing
+  --add-pattern TEXT    Add custom pattern (can be used multiple times)
+  --force-refresh       Force refresh from API, bypass cache
+  --merge               Merge with existing .gitignore
+```
+
+Examples:
+```bash
+gitignore-generator generate node python django
+gitignore-generator generate node -o .gitignore --preview
+gitignore-generator generate node --add-pattern "*.log"
+```
+
+### detect
+
+Auto-detect project type from existing files.
+
+```bash
+gitignore-generator detect [OPTIONS]
+
+Options:
+  -o, --output PATH     Output file path
+  --preview             Preview without writing
+  --force-refresh       Force refresh from API
+```
+
+### list
+
+List all supported tech stacks.
+
+```bash
+gitignore-generator list [OPTIONS] [SEARCH]
+
+Options:
+  --force-refresh       Force refresh from API
+```
+
+### show
+
+Show gitignore patterns for a specific tech.
+
+```bash
+gitignore-generator show [OPTIONS] TECH
+
+Options:
+  --force-refresh       Force refresh from API
+```
+
+### cache
+
+Manage cache.
+
+```bash
+gitignore-generator cache
+```
+
+### clear-cache
+
+Clear all cached patterns.
+
+```bash
+gitignore-generator clear-cache
+```
+
+### cleanup
+
+Remove expired cache entries.
+
+```bash
+gitignore-generator cleanup --days 7
+```
+
+## Configuration
+
+### Cache Location
+
+Default: `~/.cache/gitignore-generator/`
+
+Customize via:
+```bash
+gitignore-generator --cache-dir /path/to/cache generate node
+```
+
+### Custom Patterns
+
+Create a file with custom patterns (one per line):
+```bash
+# ~/.config/gitignore-generator/custom_patterns.txt
+*.custom
+custom/
+.env.local
+```
+
+## Supported Technologies
+
+The tool supports 100+ technologies including:
+
+- **Languages**: Python, Node.js, Go, Rust, Java, C++, Ruby, PHP, Swift, Kotlin
+- **Frameworks**: Django, Flask, Rails, React, Vue, Angular, Express, Spring
+- **Tools**: Docker, Kubernetes, Terraform, Ansible, Git, Vim, Emacs
+- **IDEs**: VS Code, JetBrains, Eclipse, Vim, Emacs
+- **OS**: macOS, Windows, Linux
+
+For full list:
+```bash
+gitignore-generator list
+```
+
+## Error Handling
+
+### Network Errors
+
+If the API is unavailable, the tool will:
+1. Use cached patterns if available
+2. Fall back to local templates
+3. Show a warning message
+
+### Unknown Technology
+
+If you specify an unknown technology, the tool will:
+1. Show available similar technologies
+2. Suggest correct names
+3. Fail with helpful error message
+
+### File Permissions
+
+If writing fails due to permissions, the tool will:
+1. Show error with file path
+2. Suggest using `--output` with writable location
+
+## 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 --cov=gitignore_generator
+```
+
+### Project Structure
+
+```
+gitignore-generator-cli/
+├── gitignore_generator/
+│   ├── __init__.py       # Package marker, version
+│   ├── api.py            # gitignore.io API client
+│   ├── cache.py          # Caching system
+│   ├── detector.py       # Project type detection
+│   ├── generator.py      # Pattern combination
+│   └── cli.py            # CLI interface
+├── templates/            # Local fallback templates
+├── tests/
+│   ├── conftest.py       # Test fixtures
+│   ├── test_api.py       # API tests
+│   ├── test_cache.py     # Cache tests
+│   ├── test_detector.py  # Detector tests
+│   ├── test_generator.py # Generator tests
+│   └── test_cli.py       # CLI tests
+├── pyproject.toml        # Project configuration
+├── setup.py              # Package setup
+└── README.md             # Documentation
+```
+
+## License
+
+MIT License - see LICENSE file for details.