From 88e333831f1cc23ab8c79b338187eb1512ccd7f3 Mon Sep 17 00:00:00 2001
From: 7000pctAUTO <lukems3823@gmail.com>
Date: Fri, 30 Jan 2026 09:08:41 +0000
Subject: [PATCH] Add README and main entry point

---
 README.md | 150 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 148 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 6d905ea..fe2e25d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,149 @@
-# devtrace
+# DevTrace
 
-Local development workflow tracker with real-time monitoring and semantic search
\ No newline at end of file
+![License](https://img.shields.io/badge/License-MIT-blue.svg)
+![Python Version](https://img.shields.io/badge/Python-3.10%2B-green.svg)
+![Version](https://img.shields.io/badge/Version-0.1.0-orange.svg)
+
+A CLI tool that automatically snapshots and indexes your entire development workflow in real-time, tracking file changes, terminal commands, git operations, and errors into a local searchable database with natural language query capabilities.
+
+## Features
+
+- **Real-time File Monitoring**: Track file creations, modifications, deletions, and moves
+- **Command Capture**: Log all terminal commands executed during development sessions
+- **Git Operation Tracking**: Monitor commits, branches, merges, pushes, and pulls
+- **Semantic Search**: Search your workflow using natural language queries
+- **Timeline View**: Visualize your development session as an interactive timeline
+- **Export Capabilities**: Export session data to JSON for external analysis
+
+## Installation
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/devtrace.git
+cd devtrace
+pip install -e .
+```
+
+### Development Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+1. **Initialize DevTrace**:
+   ```bash
+   devtrace init
+   ```
+
+2. **Start a monitoring session**:
+   ```bash
+   devtrace start --project "My Project"
+   ```
+
+3. **View session timeline**:
+   ```bash
+   devtrace timeline 1
+   ```
+
+4. **Search your workflow**:
+   ```bash
+   devtrace search "modified Python files"
+   ```
+
+5. **Ask natural language questions**:
+   ```bash
+   devtrace ask 1 "What commands did I run?"
+   ```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `devtrace init` | Initialize DevTrace database |
+| `devtrace start` | Start a new monitoring session |
+| `devtrace stop` | Stop a monitoring session |
+| `devtrace timeline` | View session timeline |
+| `devtrace search` | Search workflow history |
+| `devtrace ask` | Ask natural language questions |
+| `devtrace sessions` | List all sessions |
+| `devtrace events` | Show events by type |
+| `devtrace export` | Export session to JSON |
+| `devtrace status` | Show DevTrace statistics |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DEVTRACE_DIR` | Base directory for DevTrace data | `~/.devtrace` |
+| `DEVTRACE_DB` | SQLite database path | Auto-generated |
+| `DEVTRACE_EMBEDDING_MODEL` | Sentence-transformers model | `all-MiniLM-L6-v2` |
+| `DEVTRACE_WATCH_PATTERNS` | File patterns to watch | `*.py,*.js,*.ts,*.html,*.css` |
+
+### Configuration File
+
+Create a `.devtracerc` file in your project root:
+
+```ini
+[devtrace]
+db_path = /path/to/devtrace.db
+watch_patterns = *.py,*.js,*.ts,*.html,*.css,*.md
+ignored_patterns = __pycache__,.git,node_modules,.venv
+embedding_model = all-MiniLM-L6-v2
+```
+
+## Architecture
+
+```
+devtrace/
+├── src/
+│   ├── main.py          # Entry point
+│   ├── cli.py           # Click CLI commands
+│   ├── monitor/         # Monitoring modules
+│   │   ├── filesystem.py   # File monitoring
+│   │   ├── commands.py     # Command capture
+│   │   └── git.py          # Git tracking
+│   ├── storage/         # Data persistence
+│   │   ├── database.py     # SQLite operations
+│   │   └── models.py       # Data models
+│   ├── search/          # Search functionality
+│   │   ├── embeddings.py   # Embedding management
+│   │   ├── semantic.py     # Semantic search
+│   │   └── query.py        # Query engine
+│   └── ui/              # User interface
+│       ├── timeline.py     # Timeline view
+│       └── display.py      # Display utilities
+├── tests/               # Unit tests
+└── requirements.txt     # Dependencies
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=src
+
+# Run specific test file
+pytest tests/test_storage.py -v
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/new-feature`
+3. Make your changes and add tests
+4. Run tests: `pytest tests/ -v`
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.