diff --git a/README.md b/README.md
index ce2f976275..9bdcc2f626 100644
--- a/README.md
+++ b/README.md
@@ -1,72 +1,251 @@
-# Roo Code Cloud Monorepo
+# 🚀 Roo Code Cloud Monorepo
 
-This guide assumes:
-- Your platform is MacOS.
-- You have Docker Desktop installed.
-- You have node.js & pnpm installed via [nvm](https://github.com/nvm-sh/nvm) or [asdf](https://asdf-vm.com/).
+- [📋 Prerequisites](#-prerequisites)
+- [🔐 Environment Setup](#-environment-setup)
+- [🗄️ Database Setup](#️-database-setup)
+- [🌐 Running the Web App](#-running-the-web-app)
+- [🤖 Roomote Services](#-roomote-services)
+- [🛠️ Development Commands](#️-development-commands)
+- [🔧 Troubleshooting](#-troubleshooting)
+- [📚 Additional Resources](#-additional-resources)
 
-### Encrypted Env
+## 📋 Prerequisites
 
-The various apps within the monorepo rely on the encrypted variables in `.env.*`. You need a set of private keys to decrypt these files. Ask in Slack for these keys and place them in a file called `.env.keys` at the root of the repository. It will look something like:
+Before getting started, ensure you have the following installed:
 
-```
-DOTENV_PRIVATE_KEY_TEST=...
-DOTENV_PRIVATE_KEY_DEVELOPMENT=...
-DOTENV_PRIVATE_KEY_PREVIEW=...
-DOTENV_PRIVATE_KEY_PRODUCTION=...
+| Tool                  | Version | Installation                                                                     |
+| --------------------- | ------- | -------------------------------------------------------------------------------- |
+| 🍎 **macOS**          | Latest  | This guide is optimized for macOS                                                |
+| 🐳 **Docker Desktop** | Latest  | [Download here](https://www.docker.com/products/docker-desktop/)                 |
+| 📦 **Node.js**        | 18+     | Install via [nvm](https://github.com/nvm-sh/nvm) or [asdf](https://asdf-vm.com/) |
+| ⚡ **pnpm**           | Latest  | `npm install -g pnpm`                                                            |
+
+## 🔐 Environment Setup
+
+The monorepo uses encrypted environment variables for security. Follow these steps:
+
+### 1. Get Decryption Keys 🔑
+
+Contact your team via Slack to obtain the private keys needed to decrypt environment files.
+
+### 2. Create `.env.keys` File 📄
+
+Create a `.env.keys` file at the repository root with your keys:
+
+```bash
+# .env.keys
+DOTENV_PRIVATE_KEY_TEST=your_test_key_here
+DOTENV_PRIVATE_KEY_DEVELOPMENT=your_dev_key_here
+DOTENV_PRIVATE_KEY_PREVIEW=your_preview_key_here
+DOTENV_PRIVATE_KEY_PRODUCTION=your_prod_key_here
 ```
 
-You can verify that decryption is working by running the following:
-```
+### 3. Verify Setup ✅
+
+Test that decryption is working correctly:
+
+```bash
 pnpm install
 pnpm --filter @roo-code-cloud/env test
 ```
 
-### Postgres, ClickHouse, Redis
+If successful, you'll see: ✅ **Environment decryption working correctly!**
 
-Next you should start the Docker database containers by running:
+## 🗄️ Database Setup
 
-```sh
+Roo Code Cloud uses multiple databases for different purposes:
+
+- **🐘 PostgreSQL**: Primary application data
+- **📊 ClickHouse**: Analytics and time-series data
+- **🔴 Redis**: Caching and session storage
+
+### Start All Database Services 🚀
+
+```bash
 pnpm db:up
 ```
 
-This will automatically sync your postgres schema to the latest version. If you need to reset your database at any point, you can run:
+This command will:
 
-```sh
+- 🐳 Start Docker containers for all databases
+- 🔄 Automatically sync PostgreSQL schema to the latest version
+- 🌐 Make services available on standard ports
+
+### Reset Database (if needed) 🔄
+
+To completely reset your local database:
+
+```bash
 pnpm db:reset
 ```
 
-We don't currently have ClickHouse migrations automated, so if you encounter any errors that look related to ClickHouse schema drift you'll have to manually apply the missing migrations, or completely reset the database with:
+### ClickHouse Manual Reset 🔧
 
-```sh
+If you encounter ClickHouse schema issues:
+
+```bash
+# Stop all databases
 pnpm db:down
+
+# Remove ClickHouse data
 rm -rf .docker/data/clickhouse
+
+# Restart everything
 pnpm db:up
 ```
 
-To connect to these services via the Docker hostnames specified in `docker-compose.yml` you should update your `/etc/hosts` file to alias `postgres`, `clickhouse` and `redis`:
+### Configure Local Hosts 🌐
 
-```
+Add these entries to your `/etc/hosts` file for proper local development:
+
+```bash
 # /etc/hosts
 
 127.0.0.1       localhost
 255.255.255.255 broadcasthost
 ::1             localhost
 
-# Roo Code Cloud
+# 🚀 Roo Code Cloud Services
 127.0.0.1 postgres redis clickhouse
 ```
 
-### Web
+## 🌐 Running the Web App
 
-You should now be able to start the Roo Code Cloud web app:
+Start the main web application:
 
-```sh
+```bash
 pnpm --filter @roo-code-cloud/web dev
 ```
 
-The app will be available at [localhost:3000](http://localhost:3000/).
+🎯 **Access your app**: [http://localhost:3000](http://localhost:3000)
 
-### Roomote
+### What you'll see:
 
-Documentation for running the various roomote services is still a [WIP](https://www.notion.so/Roomote-Local-Setup-21cfd1401b0a80fc9e8ac37e7c4cfc05).
+- 🎨 Modern, responsive web interface
+- 🔐 Authentication and user management
+- 📊 Dashboard with analytics
+- ⚙️ Settings and configuration panels
+
+## 🤖 Roomote Services
+
+Roomote provides intelligent automation and workflow management.
+
+> 📝 **Note**: Detailed Roomote documentation is currently being developed.
+>
+> For now, refer to our [Work-in-Progress Setup Guide](https://www.notion.so/Roomote-Local-Setup-21cfd1401b0a80fc9e8ac37e7c4cfc05).
+
+### Available Roomote Commands:
+
+```bash
+# Start Roomote dashboard
+pnpm --filter @roo-code-cloud/roomote-dashboard dev
+
+# Run Roomote worker
+pnpm --filter @roo-code-cloud/roomote worker
+
+# Check Roomote health
+pnpm --filter @roo-code-cloud/roomote health
+```
+
+## 🛠️ Development Commands
+
+Here are the most commonly used development commands:
+
+### Testing 🧪
+
+```bash
+# Run all tests
+pnpm test
+
+# Test specific file
+pnpm test path/to/file.test.ts
+
+# Run tests in watch mode
+pnpm test --watch
+```
+
+### Code Quality 🔍
+
+```bash
+# Lint all code
+pnpm lint
+
+# Type checking
+pnpm check-types
+
+# Format code (auto-formatted on commit)
+pnpm format
+```
+
+### Database Operations 🗄️
+
+```bash
+# Push schema changes
+pnpm db:push
+
+# Generate new migration
+pnpm --filter @roo-code-cloud/db db:generate
+
+# Run pending migrations
+pnpm --filter @roo-code-cloud/db db:migrate
+
+# Reset database completely
+pnpm db:reset
+```
+
+### Package Management 📦
+
+```bash
+# Install dependencies
+pnpm install
+
+# Add dependency to specific workspace
+pnpm --filter @roo-code-cloud/web add package-name
+
+# Update all dependencies
+pnpm update
+```
+
+## 🔧 Troubleshooting
+
+### Common Issues and Solutions
+
+#### 🚫 Database Connection Errors
+
+```bash
+# Check if containers are running
+docker ps
+
+# Restart database services
+pnpm db:down && pnpm db:up
+
+# Verify hosts file configuration
+cat /etc/hosts | grep -E "(postgres|redis|clickhouse)"
+```
+
+#### 🔐 Environment Decryption Fails
+
+- ✅ Verify `.env.keys` file exists and contains valid keys
+- ✅ Check with team for updated keys
+- ✅ Ensure no extra spaces or characters in key values
+
+#### 📦 Package Installation Issues
+
+```bash
+# Clear pnpm cache
+pnpm store prune
+
+# Remove node_modules and reinstall
+rm -rf node_modules package-lock.json
+pnpm install
+```
+
+#### 🐳 Docker Issues
+
+```bash
+# Reset Docker Desktop
+# Restart Docker Desktop application
+
+# Clean Docker system
+docker system prune -a
+```