diff --git a/README.md b/README.md
index e3de097..d9c6de2 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,160 @@
-# term-diagram
+# TermDiagram
 
-Generate architecture diagrams from codebases in terminal
\ No newline at end of file
+A CLI tool for generating architecture diagrams from codebases directly in your terminal.
+
+## Features
+
+- **Multi-format Output**: Generate diagrams in ASCII, Mermaid, SVG, or DOT formats
+- **Codebase Analysis**: Parse and analyze code structure including modules, classes, functions, and methods
+- **Interactive TUI**: Launch an interactive terminal user interface for exploring codebases
+- **Git Integration**: Track architecture changes over time with git history analysis
+- **Fuzzy Search**: Quickly find symbols across your codebase
+- **Language Support**: Support for multiple programming languages via tree-sitter
+
+## Installation
+
+```bash
+pip install termdiagram
+```
+
+Or from source:
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/term-diagram.git
+cd term-diagram
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Generate a Diagram
+
+```bash
+# Generate ASCII diagram (default)
+termdiagram diagram .
+
+# Generate Mermaid diagram
+termdiagram diagram . --format mermaid
+
+# Generate SVG diagram
+termdiagram diagram . --format svg -o architecture.svg
+
+# Generate DOT diagram
+termdiagram diagram . --format dot -o architecture.dot
+
+# Filter by file extensions
+termdiagram diagram . --extensions py js ts
+
+# Exclude patterns
+termdiagram diagram . --exclude "*/tests/*" "*/.venv/*"
+
+# Simplify output
+termdiagram diagram . --no-imports --no-methods
+```
+
+### Export Data
+
+```bash
+# Export as JSON
+termdiagram json .
+
+# Export as YAML
+termdiagram json . --format yaml
+```
+
+### Show Statistics
+
+```bash
+termdiagram stats .
+```
+
+### Interactive Mode
+
+```bash
+termdiagram interactive .
+```
+
+### Search Symbols
+
+```bash
+# Search for symbols
+termdiagram search . --search "ClassName"
+
+# Show indexed symbols count
+termdiagram search .
+```
+
+### Git Integration
+
+```bash
+# Show git history
+termdiagram history . --limit 20
+
+# Show architecture changes between commits
+termdiagram diff . OLD_COMMIT NEW_COMMIT
+```
+
+### Check Dependencies
+
+```bash
+termdiagram check
+```
+
+## Configuration
+
+Create a `termdiagram.yaml` or `termdiagram.json` config file:
+
+```yaml
+# termdiagram.yaml
+output_format: mermaid
+extensions:
+  - py
+  - js
+  - ts
+exclude:
+  - "*/tests/*"
+  - "*/.venv/*"
+  - "*/node_modules/*"
+max_methods: 5
+show_imports: true
+```
+
+## Architecture
+
+```
+termdiagram/
+├── cli.py           # CLI entry point and command group
+├── __init__.py      # Package initialization
+├── generators/      # Diagram generation (ASCII, Mermaid, SVG)
+├── models/          # Data models (Module, Class, Function symbols)
+├── parser/          # Code parsing (symbol extraction, language detection)
+├── ui/              # Terminal UI (TUI, tree view, fuzzy search)
+├── git/             # Git integration (history tracking, diff analysis)
+└── utils/           # Utilities (config, file operations)
+```
+
+## Requirements
+
+- Python 3.10+
+- Click
+- Rich
+- tree-sitter-languages
+- GitPython
+- rapidfuzz
+
+Optional dependencies:
+- Graphviz + pygraphviz (for SVG generation)
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Install development dependencies: `pip install -e ".[dev]"
+4. Run tests: `pytest tests/ -v`
+5. Run linting: `ruff check .`
+6. Run type checking: `mypy src/termdiagram/ --strict`
+7. Submit a pull request
+
+## License
+
+MIT License