diff --git a/README.md b/README.md
index 69def1d..fe5e41f 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,164 @@
-# typeflow
+# TypeFlow - CLI Type Dependency Tracer
 
-CLI Type Dependency Tracer for TypeScript/JavaScript - Visualize type propagation, detect circular dependencies, and analyze type widening/narrowing
\ No newline at end of file
+A CLI tool that traces TypeScript/JavaScript type dependencies through a codebase, visualizing type propagation, detecting type widening/narrowing issues, and identifying circular type dependencies.
+
+## Features
+
+- **Type Dependency Graph Visualization**: Generate visual dependency graphs showing how types relate to each other
+- **Circular Dependency Detection**: Detect circular type dependencies that could cause issues
+- **Type Widening Analysis**: Identify type widening issues like large unions, intersections, and use of `any`
+- **Type Narrowing Analysis**: Detect excessive type narrowing and complex conditional types
+- **Multiple Export Formats**: Export graphs to DOT, GraphML, or JSON formats
+- **Watch Mode**: Monitor files for changes and incrementally analyze
+- **CLI Interface**: Easy-to-use command-line interface with Commander.js
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Usage
+
+### Analyze a directory
+
+```bash
+typeflow analyze ./src
+```
+
+### Analyze and export to DOT
+
+```bash
+typeflow analyze ./src -o output.dot -f dot
+```
+
+### Analyze and export to GraphML
+
+```bash
+typeflow analyze ./src -o output.graphml -f graphml
+```
+
+### Watch for changes
+
+```bash
+typeflow watch ./src
+```
+
+### Check for issues only
+
+```bash
+typeflow check ./src
+```
+
+### Initialize a config file
+
+```bash
+typeflow init
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `analyze [path]` | Analyze type dependencies |
+| `watch [path]` | Watch files and incrementally analyze |
+| `export <input> <output>` | Export an existing analysis |
+| `check [path]` | Check for issues without generating a graph |
+| `init` | Initialize a typeflow config file |
+
+## Options
+
+### Analyze Command
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <file>` | Output file for the graph |
+| `-f, --format <format>` | Output format (dot, graphml, json) |
+| `--no-circular` | Skip circular dependency detection |
+| `--no-widening` | Skip type widening analysis |
+| `--no-narrowing` | Skip type narrowing analysis |
+| `--cluster-by <type>` | Cluster nodes by (file, kind) |
+| `-d, --max-depth <number>` | Maximum dependency depth |
+
+## Configuration
+
+Create a `typeflow.config.json` file to customize behavior:
+
+```json
+{
+  "includePatterns": ["**/*.ts", "**/*.tsx"],
+  "excludePatterns": ["node_modules", "dist", "*.d.ts"],
+  "maxDepth": 10,
+  "exportFormats": ["dot", "graphml", "json"],
+  "analysis": {
+    "circularDependencies": true,
+    "typeWidening": true,
+    "typeNarrowing": true
+  }
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Run linter
+npm run lint
+
+# Format code
+npm run format
+
+# Watch mode
+npm run watch
+
+# Run CLI directly
+npm run dev -- analyze ./src
+```
+
+## Architecture
+
+```
+typeflow/
+├── src/
+│   ├── cli.ts              # CLI entry point
+│   ├── index.ts            # Main exports
+│   ├── parsers/            # AST parsing
+│   │   ├── typeParser.ts
+│   │   ├── importParser.ts
+│   │   ├── interfaceParser.ts
+│   │   └── typeAliasParser.ts
+│   ├── analyzers/          # Analysis modules
+│   │   ├── dependencyGraph.ts
+│   │   ├── circularDetector.ts
+│   │   ├── typeWidening.ts
+│   │   └── typeNarrowing.ts
+│   ├── exporters/          # Export formats
+│   │   ├── dotExporter.ts
+│   │   ├── graphmlExporter.ts
+│   │   └── jsonExporter.ts
+│   ├── utils/              # Utilities
+│   │   ├── fileFinder.ts
+│   │   ├── typeUtils.ts
+│   │   ├── astUtils.ts
+│   │   └── watcher.ts
+│   └── types/              # Type definitions
+│       ├── index.ts
+│       ├── ast.ts
+│       └── graph.ts
+├── test/                   # Tests
+├── bin/                    # CLI binary
+└── package.json
+```
+
+## License
+
+MIT