diff --git a/README.md b/README.md
index 1d49c3c..a4a4786 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,141 @@
-# repohealth-cli
+# RepoHealth CLI
 
-A CLI tool that analyzes Git repositories to calculate bus factor scores and identify knowledge concentration hotspots.
\ No newline at end of file
+A CLI tool that analyzes Git repositories to calculate bus factor scores, identify knowledge concentration hotspots, and generate actionable risk reports. It helps team leads and maintainers understand single-points-of-failure risks in their codebase.
+
+## Features
+
+- **Bus Factor Calculation**: Calculate bus factor scores per file/module based on commit authorship distribution
+- **Hotspot Identification**: Identify knowledge concentration hotspots where code ownership is concentrated
+- **Risk Heatmaps**: Generate visual risk heatmaps showing file/module risk levels
+- **Diversification Suggestions**: Suggest strategies to diversify code ownership
+- **Multiple Output Formats**: Export analysis results in JSON, HTML, or terminal display
+
+## Installation
+
+```bash
+pip install repohealth-cli
+```
+
+Or from source:
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+Analyze the current repository:
+
+```bash
+repohealth analyze
+```
+
+Analyze a specific repository:
+
+```bash
+repohealth analyze /path/to/repository
+```
+
+Generate an HTML report:
+
+```bash
+repohealth report /path/to/repository --format html --output report.html
+```
+
+## Commands
+
+### analyze
+
+Perform a full repository analysis:
+
+```bash
+repohealth analyze [REPO_PATH] [OPTIONS]
+```
+
+Options:
+- `--depth`: Limit commit history depth (default: unlimited)
+- `--path`: Analyze specific paths within the repository
+- `--extensions`: Filter by file extensions (e.g., "py,js,ts")
+- `--min-commits`: Minimum commits to consider a file (default: 1)
+
+### report
+
+Generate a detailed report:
+
+```bash
+repohealth report [REPO_PATH] [OPTIONS]
+```
+
+Options:
+- `--format`: Output format (json, html, terminal)
+- `--output`: Output file path (for json/html formats)
+- `--depth`: Limit commit history depth
+- `--path`: Analyze specific paths
+
+## Output Formats
+
+### Terminal
+
+Rich terminal output with colored tables and progress bars.
+
+### JSON
+
+Machine-readable output for integration with other tools:
+
+```json
+{
+  "repository": "/path/to/repo",
+  "analyzed_at": "2024-01-15T10:30:00Z",
+  "bus_factor_overall": 2.3,
+  "files_analyzed": 150,
+  "high_risk_files": 12,
+  "files": [...],
+  "hotspots": [...],
+  "suggestions": [...]
+}
+```
+
+### HTML
+
+Interactive HTML report with visualizations and charts.
+
+## Configuration
+
+Create a `repohealth.config.json` in your repository root:
+
+```json
+{
+  "depth": 365,
+  "extensions": ["py", "js", "ts", "go"],
+  "path": "src",
+  "min_commits": 5,
+  "risk_threshold": 0.7
+}
+```
+
+## Understanding Bus Factor
+
+The **Bus Factor** measures how many developers would need to be hit by a bus before the project is in serious trouble. A higher bus factor indicates better knowledge distribution.
+
+- **Bus Factor 1**: Single point of failure - one person knows everything about this code
+- **Bus Factor 2+**: Multiple people understand the code
+- **Bus Factor > 3**: Healthy knowledge distribution
+
+## Risk Levels
+
+- **Critical** (< 1.5): Immediate attention needed - single author majority
+- **High** (1.5 - 2.0): Multiple authors but concentration exists
+- **Medium** (2.0 - 3.0): Moderate distribution
+- **Low** (> 3.0): Good knowledge distribution
+
+## 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 - see LICENSE file for details.