diff --git a/.README.md b/.README.md
new file mode 100644
index 0000000..aac974a
--- /dev/null
+++ b/.README.md
@@ -0,0 +1,237 @@
+# Term Flow
+
+A CLI tool that records terminal sessions and generates ASCII flowcharts/visualizations. Perfect for documenting workflows, creating tutorials, and visualizing git histories.
+
+## Features
+
+- **Session Recording**: Record terminal sessions interactively or from shell history
+- **Flowchart Generation**: Generate ASCII and Mermaid diagrams from recorded sessions
+- **Git Visualization**: Visualize git workflows and commit histories
+- **Pattern Detection**: Automatically detect common command patterns
+- **Session Comparison**: Compare multiple terminal sessions side by side
+- **Export Options**: Export to various formats including ASCII, JSON, and Mermaid
+
+## Installation
+
+```bash
+pip install termflow
+```
+
+Or from source:
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/term-flow.git
+cd term-flow
+pip install -e .
+```
+
+## Quick Start
+
+### Record a Session
+
+```bash
+# Interactive recording
+termflow record
+
+# Record from shell history
+termflow record --from-history --count 100
+
+# Record with custom name
+termflow record my-session-name
+```
+
+### List Recorded Sessions
+
+```bash
+termflow list
+```
+
+### Visualize a Session
+
+```bash
+# Visualize latest session as ASCII
+termflow visualize session
+
+# Visualize with specific style
+termflow visualize session --style detailed --format ascii
+
+# Visualize as Mermaid diagram
+termflow visualize session --format mermaid -o session.mmd
+```
+
+### Visualize Git Workflow
+
+```bash
+# Visualize current git repository
+termflow visualize git
+
+# Export git visualization
+termflow visualize git --format mermaid -o git-graph.mmd
+```
+
+### Compare Sessions
+
+```bash
+# Compare two sessions
+termflow compare --sessions 1 2
+
+# Compare all sessions
+termflow compare --all
+```
+
+### Export a Session
+
+```bash
+# Export to JSON
+termflow export session --session-id 1 --format json -o session.json
+
+# Export to ASCII
+termflow export session --format ascii -o session.txt
+```
+
+## Commands
+
+### record
+
+Record a terminal session.
+
+```bash
+termflow record [NAME] [OPTIONS]
+```
+
+Options:
+- `--interactive/--no-interactive`: Run in interactive mode (default: True)
+- `--from-history`: Record from shell history
+- `--count`: Number of history commands to record (default: 50)
+- `--output, -o`: Output file for session export
+
+### visualize
+
+Visualize a session or git workflow.
+
+```bash
+termflow visualize <source> [OPTIONS]
+```
+
+Sources:
+- `session`: Visualize a recorded session
+- `git`: Visualize git workflow
+
+Options:
+- `--session-id, -s`: Session ID to visualize
+- `--style`: Visualization style (compact, detailed, minimal)
+- `--format, -f`: Output format (ascii, mermaid)
+- `--output, -o`: Output file
+- `--analyze/--no-analyze`: Include pattern analysis (default: True)
+
+### compare
+
+Compare terminal sessions.
+
+```bash
+termflow compare [OPTIONS]
+```
+
+Options:
+- `--sessions`: Session IDs to compare (e.g., --sessions 1 2)
+- `--all`: Compare all sessions
+
+### export
+
+Export a session to file.
+
+```bash
+termflow export <source> [OPTIONS]
+```
+
+Options:
+- `--session-id, -s`: Session ID to export
+- `--format`: Export format (json, ascii, mermaid)
+- `--output, -o`: Output file (required)
+
+### list
+
+List all recorded sessions.
+
+```bash
+termflow list
+```
+
+### show
+
+Show details of a specific session.
+
+```bash
+termflow show <session_id>
+```
+
+## Configuration
+
+Term Flow can be configured using environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TERMFLOW_HOME` | Configuration directory | `~/.termflow` |
+| `TERMFLOW_DB` | Database path | `~/.termflow/sessions.db` |
+| `TERMFLOW_GIT_CACHE` | Git cache directory | `~/.termflow/git_cache` |
+| `TERMFLOW_STYLE` | Default visualization style | `detailed` |
+
+## Architecture
+
+```
+termflow/
+├── __main__.py       # CLI entry point
+├── core/
+│   ├── session.py    # Session data model
+│   ├── recorder.py   # Session recording logic
+│   └── database.py   # SQLite database management
+├── commands/
+│   ├── record.py     # Record command
+│   ├── visualize.py  # Visualize command
+│   ├── compare.py    # Compare command
+│   └── export.py     # Export command
+├── parsers/
+│   ├── git_parser.py      # Git log parsing
+│   └── pattern_analyzer.py # Command pattern detection
+├── exporters/
+│   ├── ascii_generator.py    # ASCII flowchart generation
+│   ├── mermaid_generator.py  # Mermaid diagram generation
+│   └── graphviz_exporter.py  # Graphviz export
+└── utils/
+    └── config.py     # Configuration management
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/term-flow.git
+cd term-flow
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+### Code Formatting
+
+```bash
+ruff check .
+ruff format .
+```
+
+## 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.