diff --git a/README.md b/README.md
index 2532f0b..0619c52 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,296 @@
-# git-insights-cli
+# Git Insights CLI
 
-A CLI tool that analyzes git repositories to generate developer productivity insights, code quality metrics, and commit pattern analysis
\ No newline at end of file
+A powerful CLI tool that analyzes git repositories to generate developer productivity insights, code quality metrics, and commit pattern analysis. Works entirely offline using local git data with no external API dependencies.
+
+![CI Status](https://img.shields.io/badge/CI-Passing-green)
+![Python Version](https://img.shields.io/badge/Python-3.8%2B-blue)
+![License](https://img.shields.io/badge/License-MIT-yellow)
+
+## Features
+
+- **Commit Pattern Analysis** - Analyze commit frequency, time patterns, and author contributions
+- **Code Churn Tracking** - Track lines added/removed per commit and identify high churn areas
+- **Productivity Metrics Dashboard** - Display metrics in a formatted terminal dashboard using Rich
+- **Risky Commit Detection** - Identify commits with large changes, merge commits, and revert commits
+- **Team Velocity Reports** - Calculate commit velocity and throughput over time periods
+- **Export to Multiple Formats** - Export analysis results to JSON, HTML, and Markdown formats
+
+## Installation
+
+### From Source
+
+```bash
+pip install -e .
+```
+
+### Dependencies
+
+- Python 3.8+
+- Click 8.1.7+
+- Rich 13.7.0+
+- GitPython 3.1.40+
+- dataclasses-json 0.6.4+
+- PyYAML 6.0.1+
+- Jinja2 3.1.3+
+
+## Quick Start
+
+```bash
+# Analyze current repository (last 30 days)
+git-insights analyze
+
+# Analyze specific repository
+git-insights analyze /path/to/repo
+
+# Show productivity dashboard
+git-insights dashboard
+
+# Export to JSON
+git-insights export --format json
+
+# Analyze last 7 days
+git-insights analyze --days 7
+```
+
+## Commands
+
+### analyze
+
+Analyze a git repository for commit patterns, code churn, and productivity metrics.
+
+```bash
+git-insights analyze [OPTIONS] [PATH]
+
+Options:
+  --days INTEGER     Number of days to analyze (default: 30)
+  --format TEXT      Output format: json, markdown, html (default: console)
+  -v, --verbose      Enable verbose output
+```
+
+**Example:**
+
+```bash
+git-insights analyze /my/project --days 7 --format json
+```
+
+### dashboard
+
+Display productivity metrics in an interactive terminal dashboard.
+
+```bash
+git-insights dashboard [OPTIONS] [PATH]
+
+Options:
+  --days INTEGER     Number of days to analyze (default: 30)
+```
+
+**Example:**
+
+```bash
+git-insights dashboard /my/project
+```
+
+### export
+
+Export analysis results to a file in the specified format.
+
+```bash
+git-insights export [OPTIONS] [PATH]
+
+Options:
+  --days INTEGER     Number of days to analyze (default: 30)
+  --format TEXT      Output format: json, markdown, html (default: json)
+  --output FILE      Output file path (default: stdout)
+```
+
+**Example:**
+
+```bash
+git-insights export /my/project --format markdown --output report.md
+```
+
+### report
+
+Generate a comprehensive productivity report.
+
+```bash
+git-insights report [OPTIONS] [PATH]
+
+Options:
+  --days INTEGER     Number of days to analyze (default: 30)
+  --output FILE      Output file path
+```
+
+**Example:**
+
+```bash
+git-insights report /my/project --output report.html
+```
+
+## Configuration
+
+Create a `.git-insights/config.yaml` file in your project root or home directory:
+
+```yaml
+repository_path: "."
+analysis_days: 30
+output_format: "json"
+churn_threshold: 500
+risky_commit_threshold: 500
+merge_commit_flag: true
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| GIT_INSIGHTS_REPO_PATH | "." | Repository path to analyze |
+| GIT_INSIGHTS_DAYS | "30" | Default analysis period in days |
+| GIT_INSIGHTS_OUTPUT_FORMAT | "json" | Default output format |
+
+## Output Formats
+
+### Console Dashboard
+
+The default console output uses Rich library to display colorful, formatted metrics directly in your terminal:
+
+```
+╔════════════════════════════════════════════════════════════╗
+║          Git Insights - Productivity Dashboard              ║
+╠════════════════════════════════════════════════════════════╣
+║  Total Commits: 147    │  Authors: 5                       ║
+║  Lines Added: 12,453   │  Lines Deleted: 4,231             ║
+╚════════════════════════════════════════════════════════════╝
+```
+
+### JSON
+
+```json
+{
+  "summary": {
+    "total_commits": 147,
+    "authors": 5,
+    "lines_added": 12453,
+    "lines_deleted": 4231
+  },
+  "commit_patterns": {...},
+  "code_churn": {...}
+}
+```
+
+### Markdown
+
+```markdown
+# Git Insights Report
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Commits | 147 |
+| Authors | 5 |
+```
+
+### HTML
+
+Generates a self-contained HTML report with interactive charts and tables.
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/git-insights-cli.git
+cd git-insights-cli
+
+# 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=src
+
+# Run linting
+ruff check src/ tests/
+```
+
+### Project Structure
+
+```
+git-insights-cli/
+├── src/
+│   ├── __init__.py          # Package marker with version
+│   ├── cli.py               # CLI commands and entry point
+│   ├── git_insights.py      # Main orchestrator class
+│   ├── analyzers/
+│   │   ├── __init__.py
+│   │   ├── git_repository.py     # Git repository wrapper
+│   │   ├── commit_pattern.py     # Commit pattern analysis
+│   │   ├── code_churn.py         # Code churn tracking
+│   │   ├── risky_commit.py       # Risky commit detection
+│   │   └── velocity.py           # Velocity analysis
+│   ├── formatters/
+│   │   ├── __init__.py
+│   │   ├── base.py               # Base formatter abstract class
+│   │   ├── json_formatter.py     # JSON output
+│   │   ├── markdown_formatter.py # Markdown output
+│   │   ├── html_formatter.py     # HTML output
+│   │   └── dashboard.py          # Rich console dashboard
+│   ├── models/
+│   │   ├── __init__.py
+│   │   └── data_structures.py    # Dataclass models
+│   └── utils/
+│       ├── __init__.py
+│       ├── date_utils.py         # Date/time utilities
+│       └── config.py             # Configuration loader
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py              # Pytest fixtures
+│   ├── test_cli.py              # CLI tests
+│   ├── test_models.py           # Model tests
+│   ├── test_analyzers.py        # Analyzer tests
+│   └── test_formatters.py       # Formatter tests
+├── .git-insights/
+│   └── config.yaml              # Default configuration
+├── .gitea/
+│   └── workflows/
+│       └── ci.yml               # Gitea Actions CI workflow
+├── requirements.txt             # Dependencies
+├── setup.py                     # Package setup
+├── pyproject.toml              # Project configuration
+├── .gitignore                  # Git ignore patterns
+├── .pre-commit-config.yaml     # Pre-commit hooks
+└── README.md                   # This file
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ -v --cov=src --cov-report=term-missing
+
+# Run specific test file
+pytest tests/test_cli.py -v
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- [Click](https://click.palletsprojects.com/) - CLI framework
+- [Rich](https://github.com/Textualize/rich) - Terminal formatting
+- [GitPython](https://gitpython.readthedocs.io/) - Git bindings
+- [Jinja2](https://jinja.palletsprojects.com/) - Template engine