docs: update README with comprehensive project overview and usage guide

Author: IKatsuba

.gitignore

@@ -1,4 +1,5 @@
 .idea
 .env
 .cli
-dist
+dist
+.DS_Store

README.md

@@ -1,7 +1,104 @@
-# runx
+# runx 🚀
 
-`runx` is a monorepo management tool written in Deno and compiled into a
-standalone executable file. It helps you run scripts across multiple projects in
-your monorepo efficiently and with minimal configuration.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> The project is under development and not ready for production use!
+> ATTENTION! The project is under development and not ready for production use!
+
+A lightning monorepo task runner written in Deno. `runx` helps you manage and
+execute tasks across multiple packages in your monorepo with minimal
+configuration and maximum efficiency.
+
+## 🌟 Key Features
+
+- **Zero Configuration**: Works out of the box with your existing monorepo
+  structure
+- **Smart Workspace Detection**: Automatically detects and works with workspace
+  patterns defined in your root `package.json`
+- **Intelligent Dependency Management**:
+  - Builds and validates dependency relationships between packages
+  - Detects and prevents circular dependencies
+  - Executes tasks in correct topological order
+- **Flexible Execution Modes**:
+  - Run commands across all packages
+  - Target specific packages
+  - Execute only in affected packages (Git-aware)
+
+## 📦 Installation
+
+> TODO. Stay tuned!
+
+## 🚀 Quick Start
+
+1. Navigate to your monorepo root:
+
+```bash
+cd your-monorepo
+```
+
+2. Run a script in all packages:
+
+```bash
+runx test
+```
+
+## 💡 Usage
+
+### Basic Commands
+
+```bash
+# Run a command in all packages
+runx <task-name>
+
+# Run a command only in specific packages
+runx <task-name> package1 package2
+
+# Run a command only in affected packages (compared to main branch)
+runx <task-name> --affected
+
+# Run a command in packages affected since a specific branch
+runx <task-name> --affected feature-branch
+```
+
+### Command Options
+
+- `-a, --affected [base]` - Run command only for affected packages since the
+  specified base branch (defaults to 'main')
+- `--version` - Show version information
+- `-h, --help` - Display help information
+
+## 🔧 How It Works
+
+1. **Workspace Detection**: `runx` reads your root `package.json` to understand
+   your workspace structure
+2. **Dependency Analysis**: Builds a complete dependency graph of your packages
+3. **Task Execution**:
+   - Validates the dependency graph for circular dependencies
+   - Determines the correct execution order
+   - Executes tasks while maintaining proper working directories and environment
+     variables
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major
+changes, please open an issue first to discuss what you would like to change.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
+for details.
+
+## 🙏 Acknowledgments
+
+Built with:
+
+- [Deno](https://deno.land/) - A modern runtime for JavaScript and TypeScript
+- [Cliffy](https://cliffy.io/) - A framework for building command line
+  applications
+- [dax](https://github.com/dsherret/dax) - The friendly shell scripting library
+  for Deno