diff --git a/README.md b/README.md
index 4bbc82e..cffbdb9 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,252 @@
-# gitpulse
+# GitPulse - Local Git Analytics CLI
 
-A privacy-focused CLI tool that analyzes local Git repositories to visualize commit patterns, code churn, and developer productivity metrics using beautiful terminal visualizations with Rich. Runs entirely offline with no external data transmission.
\ No newline at end of file
+[![CI](https://7000pct.gitea.bloupla.net/7000pctAUTO/gitpulse/actions/workflows/ci.yml/badge.svg)](https://7000pct.gitea.bloupla.net/7000pctAUTO/gitpulse/actions)
+[![Version](https://img.shields.io/pypi/v/gitpulse.svg)](https://pypi.org/project/gitpulse/)
+[![Python](https://img.shields.io/pypi/pyversions/gitpulse.svg)](https://pypi.org/project/gitpulse/)
+[![License](https://img.shields.io/pypi/l/gitpulse.svg)](https://opensource.org/licenses/MIT/)
+
+A privacy-focused CLI tool that analyzes local Git repositories to visualize commit patterns, code churn, and developer productivity metrics using beautiful terminal visualizations with Rich. Runs entirely offline with no external data transmission.
+
+## Features
+
+- **Local Repository Analysis** - Analyze any local git repository without data transmission
+- **Commit Activity Heatmap** - Display daily/weekly commit patterns as a GitHub-style heatmap
+- **Code Churn Tracking** - Track lines added/deleted over time with trend visualization
+- **Author Contribution Breakdown** - Show commit count, code changes, and contributions per author
+- **Productivity Scorecard** - Calculate productivity scores based on commits, changes, and patterns
+- **File Change Frequency** - Show most frequently changed files in the repository
+- **Export Reports** - Export analysis results to Markdown and JSON formats
+- **Time Range Filtering** - Filter analysis by custom time ranges (last week, month, custom dates)
+
+## Why GitPulse?
+
+In an era of increasing data privacy concerns, GitPulse stands out by:
+
+- **100% Offline** - All data is processed locally and never transmitted
+- **No External Dependencies** - No API calls, no cloud services, no tracking
+- **Privacy First** - Your repository data stays on your machine
+- **Beautiful Terminal UI** - Built with Rich for stunning visualizations
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install gitpulse
+```
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/gitpulse.git
+cd gitpulse
+pip install -e .
+```
+
+### With Poetry
+
+```bash
+poetry add gitpulse
+```
+
+## Quick Start
+
+### Analyze a Repository
+
+```bash
+gitpulse analyze --path /path/to/repo
+```
+
+### Show Commit Activity Heatmap
+
+```bash
+gitpulse heatmap --path /path/to/repo
+```
+
+### View Code Churn Trends
+
+```bash
+gitpulse churn --path /path/to/repo --since "2024-01-01"
+```
+
+### See Author Contributions
+
+```bash
+gitpulse authors --path /path/to/repo
+```
+
+### Check Productivity Scores
+
+```bash
+gitpulse productivity --path /path/to/repo
+```
+
+### Export a Report
+
+```bash
+gitpulse export --path /path/to/repo --format markdown --output report.md
+gitpulse export --path /path/to/repo --format json --output report.json
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `gitpulse analyze` | Show an overview dashboard with all metrics |
+| `gitpulse heatmap` | Display commit activity as a calendar-style heatmap |
+| `gitpulse churn` | Show code churn trends (lines added/deleted) |
+| `gitpulse authors` | Display author contribution breakdown |
+| `gitpulse productivity` | Show productivity scorecards |
+| `gitpulse export` | Export analysis results to Markdown or JSON |
+
+## Options
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--path PATH` | Path to git repository (default: current directory) |
+| `--since DATE` | Start date for analysis (e.g., "2024-01-01" or "1 week ago") |
+| `--until DATE` | End date for analysis |
+| `--verbose` | Enable verbose output |
+| `--help` | Show help message |
+| `--version` | Show version |
+
+### Date Formats
+
+GitPulse supports various date formats:
+
+- ISO format: `2024-01-01`
+- Relative time: `1 week ago`, `2 months ago`, `3 days ago`
+- Full datetime: `2024-01-01T12:00:00`
+
+## Configuration
+
+### Environment Variables
+
+```bash
+export GITPULSE_DEFAULT_PATH=/path/to/your/repo
+export GITPULSE_CACHE_ENABLED=true
+```
+
+### Configuration File
+
+Create `~/.config/gitpulse/config.toml`:
+
+```toml
+[default]
+path = "/path/to/default/repo"
+cache_enabled = true
+
+[display]
+theme = "default"
+compact = false
+```
+
+## Architecture
+
+```
+gitpulse/
+├── cli.py              # Main CLI entry point with Click commands
+├── config.py           # Configuration management
+├── __init__.py         # Package metadata
+├── analyzers/          # Analysis engines
+│   ├── base.py         # Base analyzer class
+│   ├── commit_analyzer.py   # Commit pattern analysis
+│   ├── churn_analyzer.py    # Code churn tracking
+│   ├── author_analyzer.py   # Author contribution analysis
+│   └── productivity_analyzer.py  # Productivity scoring
+├── ui/                 # Terminal visualizations
+│   ├── heatmap.py      # Calendar-style heatmaps
+│   ├── charts.py       # Bar and line charts
+│   ├── tables.py       # Styled tables
+│   └── render.py       # Combined rendering
+├── exporters/          # Export functionality
+│   ├── markdown_exporter.py
+│   └── json_exporter.py
+└── utils/              # Utility functions
+    ├── git_utils.py    # Git repository access
+    └── date_utils.py   # Date parsing
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/gitpulse.git
+cd gitpulse
+poetry install --with dev
+```
+
+### Run Tests
+
+```bash
+pytest tests/ -v
+pytest tests/ --cov=gitpulse
+```
+
+### Linting
+
+```bash
+ruff check .
+```
+
+### Type Checking
+
+```bash
+mypy gitpulse/
+```
+
+## Dependencies
+
+### Core Dependencies
+
+- `rich>=13.0.0` - Terminal rendering and visualizations
+- `gitpython>=3.1.0` - Git repository access
+- `pandas>=2.0.0` - Data manipulation and analysis
+- `click>=8.0.0` - CLI framework
+
+### Development Dependencies
+
+- `pytest>=7.0.0` - Testing framework
+- `pytest-cov>=4.0.0` - Coverage reporting
+
+## Privacy
+
+GitPulse is designed with privacy as its core principle:
+
+- **No Network Requests** - Zero external API calls
+- **Local Processing** - All git data is processed locally
+- **No Data Storage** - No caching of repository data
+- **No Telemetry** - No usage tracking or analytics
+
+## 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/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- [Rich](https://github.com/Textualize/rich) for the amazing terminal rendering library
+- [GitPython](https://github.com/gitpython-developers/GitPython) for git repository access
+- Inspired by [Prism.Tools](https://prism.tools/) and similar privacy-focused developer tools
+
+## Changelog
+
+### v0.1.0 (2024-01-31)
+
+- Initial release
+- Core CLI with analyze, heatmap, churn, authors, productivity commands
+- Export functionality (Markdown and JSON)
+- Time range filtering
+- Privacy-focused offline processing