diff --git a/README.md b/README.md
index 944d096..10751d7 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,228 @@
-# techdebt-tracker-cli
+# TechDebt Tracker CLI
 
-A Rust-based CLI tool to analyze and track technical debt in codebases with TUI dashboard
\ No newline at end of file
+A Rust-based CLI tool that analyzes codebases to extract, categorize, and visualize TODO/FIXME/HACK comments using tree-sitter for multi-language parsing, providing an interactive TUI dashboard and export capabilities.
+
+## Features
+
+- **Multi-language Support**: Parse TODO/FIXME/HACK comments in JavaScript, TypeScript, Python, Rust, Go, Java, C/C++, Ruby, and more
+- **Priority Categorization**: Automatically categorize technical debt by priority (Critical, High, Medium, Low) based on keywords and context
+- **Interactive TUI Dashboard**: Visualize technical debt with an interactive terminal UI
+- **Export Capabilities**: Export reports to JSON and Markdown formats
+- **Complexity Estimation**: Estimate complexity of technical debt items based on comment content and context
+- **Configurable Patterns**: Define custom comment patterns via YAML configuration
+- **Ignore Patterns**: Exclude directories and files using .gitignore-style patterns
+
+## Installation
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/techdebt-tracker-cli.git
+cd techdebt-tracker-cli
+cargo build --release
+cargo install --path .
+```
+
+### Using Cargo
+
+```bash
+cargo install techdebt-tracker-cli
+```
+
+## Quick Start
+
+### Initialize Configuration
+
+```bash
+techdebt-tracker init
+```
+
+### Analyze a Directory
+
+```bash
+# Analyze current directory
+techdebt-tracker analyze
+
+# Analyze specific directory
+techdebt-tracker analyze --path /path/to/project
+
+# Output to file
+techdebt-tracker analyze --output report.json
+```
+
+### Open Interactive Dashboard
+
+```bash
+techdebt-tracker tui
+```
+
+### Export Report
+
+```bash
+# Export to JSON
+techdebt-tracker export --output report.json --format json
+
+# Export to Markdown
+techdebt-tracker export --output report.md --format markdown
+```
+
+## Configuration
+
+Create a `techdebt.yaml` file in your project root or in `~/.config/techdebt-tracker/`:
+
+```yaml
+patterns:
+  - keyword: "FIXME"
+    priority: critical
+    regex: false
+  - keyword: "TODO"
+    priority: medium
+    regex: false
+  - keyword: "HACK"
+    priority: low
+    regex: false
+
+languages:
+  - javascript
+  - typescript
+  - python
+  - rust
+
+ignore:
+  - "node_modules/**"
+  - "target/**"
+  - ".git/**"
+```
+
+## CLI Commands
+
+### analyze
+
+Analyze codebase and show summary of technical debt.
+
+```bash
+techdebt-tracker analyze [OPTIONS]
+
+Options:
+  -p, --path <PATH>     Directory to analyze (default: current directory)
+  -o, --output <FILE>   Output file for results
+  -v, --verbose         Show verbose output
+```
+
+### tui
+
+Open interactive TUI dashboard.
+
+```bash
+techdebt-tracker tui [OPTIONS]
+
+Options:
+  -p, --path <PATH>     Directory to analyze (default: current directory)
+```
+
+### export
+
+Export analysis to file.
+
+```bash
+techdebt-tracker export [OPTIONS]
+
+Options:
+  -p, --path <PATH>      Directory to analyze (default: current directory)
+  -o, --output <FILE>    Output file (required)
+  -f, --format <FORMAT>  Export format: json or markdown
+```
+
+### init
+
+Initialize default configuration file.
+
+```bash
+techdebt-tracker init [OPTIONS]
+
+Options:
+  -p, --path <PATH>    Directory to create config in (default: current directory)
+```
+
+## TUI Navigation
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Switch between Dashboard and List views |
+| `↑` / `↓` | Navigate items |
+| `Enter` | View item details |
+| `/` or `f` | Filter items |
+| `1-4` | Filter by priority (1=Critical, 2=High, 3=Medium, 4=Low) |
+| `s` | Cycle sort order |
+| `c` | Clear filters |
+| `q` | Quit |
+
+## Export Formats
+
+### JSON
+
+```json
+{
+  "summary": {
+    "total_items": 42,
+    "by_priority": {
+      "critical": 5,
+      "high": 10,
+      "medium": 20,
+      "low": 7
+    }
+  },
+  "items": [...]
+}
+```
+
+### Markdown
+
+Generates a formatted report with:
+- Summary statistics
+- Priority breakdown with visual bars
+- Language distribution
+- Detailed item list grouped by priority
+
+## Supported Languages
+
+- JavaScript (.js, .jsx)
+- TypeScript (.ts, .tsx)
+- Python (.py)
+- Rust (.rs)
+- Go (.go)
+- Java (.java)
+- C (.c)
+- C++ (.cpp, .cc, .cxx, .h, .hpp)
+- Ruby (.rb)
+
+## Building from Source
+
+```bash
+# Debug build
+cargo build
+
+# Release build
+cargo build --release
+
+# Run tests
+cargo test --all-features
+
+# Run linting
+cargo clippy --all-targets
+
+# Check formatting
+cargo fmt --check
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests and linting
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.