diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1ecac3da..9b70abf7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,23 +1,189 @@
 # Contributing to Maestro
 
-Thank you for your interest in contributing to Maestro! This document provides guidelines and instructions for contributing.
+Thank you for your interest in contributing to Maestro! This document provides guidelines, setup instructions, and architectural information for developers.
+
+## Table of Contents
+
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Tech Stack](#tech-stack)
+- [Development Scripts](#development-scripts)
+- [Architecture](#architecture)
+- [Code Style](#code-style)
+- [Commit Messages](#commit-messages)
+- [Pull Request Process](#pull-request-process)
+- [Building for Release](#building-for-release)
+- [GitHub Actions Workflow](#github-actions-workflow)
 
 ## Development Setup
 
-1. Fork and clone the repository
-2. Install dependencies: `npm install`
-3. Start development server: `npm run dev`
+### Prerequisites
+
+- Node.js 20+
+- npm or yarn
+- Git
+
+### Getting Started
+
+```bash
+# Fork and clone the repository
+git clone <your-fork-url>
+cd maestro
+
+# Install dependencies
+npm install
+
+# Run in development mode with hot reload
+npm run dev
+```
+
+## Project Structure
+
+```
+maestro/
+├── src/
+│   ├── main/              # Electron main process (Node.js backend)
+│   │   ├── utils/         # Shared utilities
+│   │   └── ...            # Process management, IPC, web server
+│   └── renderer/          # React frontend (UI)
+│       ├── components/    # React components (UI elements, modals, panels)
+│       ├── hooks/         # Custom React hooks (reusable state logic)
+│       ├── services/      # Business logic services (git, process management)
+│       ├── types/         # TypeScript definitions
+│       ├── utils/         # Frontend utilities
+│       └── constants/     # App constants (themes, shortcuts, emojis)
+├── build/                 # Application icons
+├── .github/workflows/     # CI/CD automation
+└── dist/                  # Build output (generated)
+```
+
+## Tech Stack
+
+### Backend (Electron Main Process)
+
+- **Electron 28+** - Desktop application framework
+- **TypeScript** - Type-safe JavaScript
+- **node-pty** - Terminal emulation for shell sessions
+- **Fastify** - High-performance web server for remote access
+- **electron-store** - Persistent settings storage
+
+### Frontend (Renderer Process)
+
+- **React 18** - UI framework
+- **TypeScript** - Type-safe JavaScript
+- **Tailwind CSS** - Utility-first CSS framework
+- **Vite** - Fast build tool and dev server
+- **Lucide React** - Icon library
+- **marked** - Markdown rendering
+- **react-syntax-highlighter** - Code syntax highlighting
+- **ansi-to-html** - Terminal ANSI escape code rendering
+- **dompurify** - HTML sanitization for XSS prevention
+- **emoji-mart** - Emoji picker component
+
+## Development Scripts
+
+```bash
+# Start dev server with hot reload
+npm run dev
+
+# Build main process only (Electron backend)
+npm run build:main
+
+# Build renderer only (React frontend)
+npm run build:renderer
+
+# Full production build
+npm run build
+
+# Start built application
+npm start
+
+# Clean build artifacts and cache
+npm run clean
+```
+
+## Architecture
+
+### Process Management
+
+Maestro uses a dual-process architecture where **each session runs two processes simultaneously**:
+
+1. **AI Agent Process** - Runs Claude Code as a child process
+2. **Terminal Process** - Runs a PTY shell session for command execution
+
+This architecture enables seamless switching between AI and terminal modes without process restarts. All processes are managed through IPC (Inter-Process Communication) with secure context isolation.
+
+### Security Model
+
+Maestro implements strict security measures:
+
+- **Context isolation enabled** - Renderer has no direct Node.js access
+- **No node integration in renderer** - No `require()` in renderer process
+- **Secure IPC via preload script** - Minimal API exposed via `contextBridge`
+- **No shell injection** - Uses `execFile` instead of `exec`
+- **Input sanitization** - All user inputs are validated
+
+### Main Process (Backend)
+
+Located in `src/main/`:
+
+- `index.ts` - Application entry point, IPC handler registration, window management
+- `process-manager.ts` - Core primitive for spawning and managing CLI processes
+- `web-server.ts` - Fastify-based HTTP/WebSocket server for remote access
+- `agent-detector.ts` - Auto-detects available AI tools via PATH
+- `preload.ts` - Secure IPC bridge via contextBridge
+
+### Renderer Process (Frontend)
+
+Located in `src/renderer/`:
+
+- `App.tsx` - Main UI coordinator
+- `main.tsx` - Renderer entry point
+- `components/` - React components (modals, panels, UI elements)
+- `hooks/` - Custom React hooks for reusable state logic
+- `services/` - Business logic services (clean wrappers around IPC calls)
+- `constants/` - Application constants (themes, shortcuts, etc.)
 
 ## Code Style
 
-- TypeScript for all new code
-- Use ESLint and Prettier (configs coming soon)
-- Follow existing code patterns
-- Add JSDoc comments for public APIs
+### TypeScript
+
+- All code must be TypeScript with strict mode enabled
+- Define interfaces for all data structures
+- Export types via `preload.ts` for renderer types
+
+### React Components
+
+- Use functional components with hooks
+- Keep components small and focused
+- Use Tailwind CSS for styling
+- Maintain keyboard accessibility
+- Use inline styles for theme colors, Tailwind for layout
+
+### Architecture Guidelines
+
+**Main Process:**
+- Keep IPC handlers simple and focused
+- Use TypeScript interfaces for all data structures
+- Handle errors gracefully
+- No blocking operations
+
+**Renderer Process:**
+- Use React hooks
+- Keep components small and focused
+- Use Tailwind for styling
+- Maintain keyboard accessibility
+
+**Security:**
+- Never expose Node.js APIs to renderer
+- Use preload script for all IPC
+- Sanitize all user inputs
+- Use `execFile` instead of `exec`
 
 ## Commit Messages
 
 Use conventional commits:
+
 - `feat:` - New features
 - `fix:` - Bug fixes
 - `docs:` - Documentation changes
@@ -36,25 +202,54 @@ Example: `feat: add context usage visualization`
 5. Submit PR with clear description
 6. Wait for review
 
-## Architecture Guidelines
+## Building for Release
 
-### Main Process (Backend)
-- Keep IPC handlers simple and focused
-- Use TypeScript interfaces for all data structures
-- Handle errors gracefully
-- No blocking operations
+### 1. Prepare Icons
 
-### Renderer Process (Frontend)
-- Use React hooks
-- Keep components small and focused
-- Use Tailwind for styling
-- Maintain keyboard accessibility
+Place your application icons in the `build/` directory:
 
-### Security
-- Never expose Node.js APIs to renderer
-- Use preload script for all IPC
-- Sanitize all user inputs
-- Use `execFile` instead of `exec`
+- `icon.icns` - macOS (512x512 or 1024x1024)
+- `icon.ico` - Windows (256x256)
+- `icon.png` - Linux (512x512)
+
+### 2. Update Version
+
+Update version in `package.json`:
+
+```json
+{
+  "version": "0.1.0"
+}
+```
+
+### 3. Build Distributables
+
+```bash
+# Build for all platforms
+npm run package
+
+# Platform-specific builds
+npm run package:mac    # Creates .dmg and .zip
+npm run package:win    # Creates .exe installer
+npm run package:linux  # Creates .AppImage, .deb, .rpm
+```
+
+Output will be in the `release/` directory.
+
+## GitHub Actions Workflow
+
+The project includes automated builds via GitHub Actions:
+
+1. **Create a release tag:**
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+2. **GitHub Actions will automatically:**
+   - Build for macOS, Windows, and Linux
+   - Create release artifacts
+   - Publish a GitHub Release with downloads
 
 ## Testing
 
diff --git a/README.md b/README.md
index 739ec858..41783f0e 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,37 @@
 
 > A unified, highly-responsive developer command center for managing your fleet of AI coding agents.
 
-Maestro is a desktop application built with Electron that allows you to run and manage multiple AI coding instances instances in parallel with a Linear/Superhuman-level responsive interface. Currently supporting Claude Code with plans for additional agentic coding tools (Aider, OpenCode, etc.) may be added in the future based on user demand.
+Maestro is a desktop application that allows you to run and manage multiple AI coding instances in parallel with a Linear/Superhuman-level responsive interface. Currently supporting Claude Code with plans for additional agentic coding tools (Aider, OpenCode, etc.) based on user demand.
+
+## Installation
+
+### Download
+
+Download the latest release for your platform from the [Releases](https://github.com/pedramamini/maestro/releases) page:
+
+- **macOS**: `.dmg` or `.zip`
+- **Windows**: `.exe` installer
+- **Linux**: `.AppImage`, `.deb`, or `.rpm`
+
+### Requirements
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- Git (optional, for git-aware features)
+
+## Features
+
+- 🚀 **Multi-Instance Management** - Run multiple Claude Code instances and Command Terminal sessions simultaneously
+- 🔄 **Dual-Mode Input** - Switch between Command Terminal and AI Terminal seamlessly
+- ⌨️ **Keyboard-First Navigation** - Full keyboard control with customizable shortcuts
+- 🎨 **Beautiful Themes** - 12 themes including Dracula, Monokai, Nord, Tokyo Night, GitHub Light, and more
+- 🔀 **Git Integration** - Automatic git status, diff tracking, and workspace detection
+- 📁 **File Explorer** - Browse project files with syntax highlighting and markdown preview
+- 📋 **Session Management** - Group, rename, and organize your sessions
+- 📝 **Scratchpad** - Built-in markdown editor with live preview
+- ⚡ **Slash Commands** - Extensible command system with autocomplete
+- 🌐 **Remote Access** - Built-in web server with optional ngrok/Cloudflare tunneling
+
+> **Note**: Maestro currently supports Claude Code only. Support for other agentic coding tools may be added in future releases based on community demand.
 
 ## UI Overview
 
@@ -12,266 +42,70 @@ Maestro features a three-panel layout:
 - **Main Window** - Center workspace with two modes:
   - **AI Terminal** - Interact with Claude Code AI assistant
   - **Command Terminal** - Execute shell commands and scripts
-  - **File Preview** - View images and text documents wtih source highlighting and markdown rendering
+  - **File Preview** - View images and text documents with source highlighting and markdown rendering
   - **Diff Preview** - View the current diff when working in Git repositories
 - **Right Bar** - File explorer, command history, and scratchpad
 
 ### Session Status Indicators
 
 Each session shows a color-coded status indicator:
+
 - 🟢 **Green** - Ready and waiting
 - 🟡 **Yellow** - Agent is thinking
 - 🔴 **Red** - No connection with agent
 - 🟠 **Pulsing Orange** - Attempting to establish connection
 
-## Features
-
-- 🚀 **Multi-Instance Management** - Run multiple Claude Code instances and Command Terminal sessions simultaneously
-- 🎨 **Beautiful UI** - Obsidian-inspired themes with keyboard-first navigation
-- 🔄 **Dual-Mode Input** - Switch between Command Terminal and AI Terminal seamlessly
-- ⚡ **Slash Commands** - Extensible command system with autocomplete (`/clear` to clear output)
-- 🌐 **Remote Access** - Built-in web server with optional ngrok/Cloudflare tunneling
-- 🎯 **Git Integration** - Automatic git status, diff tracking, and workspace detection
-- ⚡ **Keyboard Shortcuts** - Full keyboard control with customizable shortcuts
-- 📝 **Session Management** - Group, rename, and organize your sessions
-- 🎭 **Multiple Themes** - 8 themes including Dracula, Monokai, Nord, Tokyo Night, GitHub Light, Solarized, One Light, and Gruvbox
-- 📄 **File Explorer** - Browse project files with syntax highlighting and markdown preview
-- ✏️ **Scratchpad** - Built-in markdown editor with live preview
-
-> **Note**: Maestro currently supports Claude Code only. Support for other agentic coding tools may be added in future releases based on community demand.
-
-## Quick Start
-
-### Prerequisites
-
-- Node.js 20+
-- npm or yarn
-- Git (optional, for git-aware features)
-
-### Installation
-
-```bash
-# Clone the repository
-git clone <repository-url>
-cd maestro
-
-# Install dependencies
-npm install
-
-# Run in development mode
-npm run dev
-
-# Build for production
-npm run build
-
-# Package for distribution
-npm run package
-```
-
-### Platform-Specific Builds
-
-```bash
-# macOS only
-npm run package:mac
-
-# Windows only
-npm run package:win
-
-# Linux only
-npm run package:linux
-```
-
-## Development
-
-### Project Structure
-
-```
-maestro/
-├── src/
-│   ├── main/              # Electron main process (Node.js backend)
-│   │   ├── utils/         # Shared utilities
-│   │   └── ...            # Process management, IPC, web server
-│   └── renderer/          # React frontend (UI)
-│       ├── components/    # React components (UI elements, modals, panels)
-│       ├── hooks/         # Custom React hooks (reusable state logic)
-│       ├── services/      # Business logic services (git, process management)
-│       ├── types/         # TypeScript definitions
-│       ├── utils/         # Frontend utilities
-│       └── constants/     # App constants (themes, shortcuts, emojis)
-├── build/                 # Application icons
-├── .github/workflows/     # CI/CD automation
-└── dist/                  # Build output (generated)
-```
-
-### Tech Stack
-
-**Backend (Electron Main)**
-- Electron 28+
-- TypeScript
-- node-pty (terminal emulation)
-- Fastify (web server)
-- electron-store (settings persistence)
-
-**Frontend (Renderer)**
-- React 18
-- TypeScript
-- Tailwind CSS
-- Vite
-- Lucide React (icons)
-- marked (Markdown rendering)
-- react-syntax-highlighter (code highlighting)
-- ansi-to-html (ANSI escape code rendering)
-- dompurify (HTML sanitization)
-- emoji-mart (emoji picker)
-
-### Development Scripts
-
-```bash
-# Start dev server with hot reload
-npm run dev
-
-# Build main process only
-npm run build:main
-
-# Build renderer only
-npm run build:renderer
-
-# Full production build
-npm run build
-
-# Start built application
-npm start
-```
-
-## Building for Release
-
-### 1. Prepare Icons
-
-Place your application icons in the `build/` directory:
-- `icon.icns` - macOS (512x512 or 1024x1024)
-- `icon.ico` - Windows (256x256)
-- `icon.png` - Linux (512x512)
-
-### 2. Update Version
-
-Update version in `package.json`:
-```json
-{
-  "version": "0.1.0"
-}
-```
-
-### 3. Build Distributables
-
-```bash
-# Build for all platforms
-npm run package
-
-# Platform-specific
-npm run package:mac    # Creates .dmg and .zip
-npm run package:win    # Creates .exe installer
-npm run package:linux  # Creates .AppImage, .deb, .rpm
-```
-
-Output will be in the `release/` directory.
-
-## GitHub Actions Workflow
-
-The project includes automated builds via GitHub Actions:
-
-1. **Create a release tag:**
-   ```bash
-   git tag v0.1.0
-   git push origin v0.1.0
-   ```
-
-2. **GitHub Actions will automatically:**
-   - Build for macOS, Windows, and Linux
-   - Create release artifacts
-   - Publish a GitHub Release with downloads
-
-## Configuration
-
-Settings are stored in:
-- **macOS**: `~/Library/Application Support/maestro/`
-- **Windows**: `%APPDATA%/maestro/`
-- **Linux**: `~/.config/maestro/`
-
-### Configuration Files
-
-- `maestro-settings.json` - User preferences (theme, shortcuts, LLM settings, UI preferences)
-
-## Architecture
-
-### Process Management
-
-Maestro uses a dual-process architecture where **each session runs two processes simultaneously**:
-
-1. **AI Agent Process** - Runs Claude Code as a child process
-2. **Terminal Process** - Runs a PTY shell session for command execution
-
-This architecture enables seamless switching between AI and terminal modes without process restarts. All processes are managed through IPC (Inter-Process Communication) with secure context isolation.
-
-### Security
-
-- ✅ Context isolation enabled
-- ✅ No node integration in renderer
-- ✅ Secure IPC via preload script
-- ✅ No shell injection (uses `execFile` instead of `exec`)
-- ✅ Input sanitization for all user inputs
-
 ## Keyboard Shortcuts
 
 ### Global Shortcuts
 
 | Action | macOS | Windows/Linux |
 |--------|-------|---------------|
-| Quick Actions | `⌘K` | `Ctrl+K` |
-| Toggle Sidebar | `⌘B` | `Ctrl+B` |
-| Toggle Right Panel | `⌘\` | `Ctrl+\` |
-| New Agent | `⌘N` | `Ctrl+N` |
-| Kill Agent | `⌘⇧⌫` | `Ctrl+Shift+Backspace` |
-| Move Session to Group | `⌘⇧M` | `Ctrl+Shift+M` |
-| Previous Agent | `⌘⇧{` | `Ctrl+Shift+{` |
-| Next Agent | `⌘⇧}` | `Ctrl+Shift+}` |
-| Switch AI/Command Terminal | `⌘J` | `Ctrl+J` |
-| Show Shortcuts Help | `⌘/` | `Ctrl+/` |
-| Open Settings | `⌘,` | `Ctrl+,` |
+| Quick Actions | `Cmd+K` | `Ctrl+K` |
+| Toggle Sidebar | `Cmd+B` | `Ctrl+B` |
+| Toggle Right Panel | `Cmd+\` | `Ctrl+\` |
+| New Agent | `Cmd+N` | `Ctrl+N` |
+| Kill Agent | `Cmd+Shift+Backspace` | `Ctrl+Shift+Backspace` |
+| Move Session to Group | `Cmd+Shift+M` | `Ctrl+Shift+M` |
+| Previous Agent | `Cmd+Shift+{` | `Ctrl+Shift+{` |
+| Next Agent | `Cmd+Shift+}` | `Ctrl+Shift+}` |
+| Switch AI/Command Terminal | `Cmd+J` | `Ctrl+J` |
+| Show Shortcuts Help | `Cmd+/` | `Ctrl+/` |
+| Open Settings | `Cmd+,` | `Ctrl+,` |
 | Cycle Focus Areas | `Tab` | `Tab` |
-| Cycle Focus Backwards | `⇧Tab` | `Shift+Tab` |
+| Cycle Focus Backwards | `Shift+Tab` | `Shift+Tab` |
 
 ### Panel Shortcuts
 
 | Action | macOS | Windows/Linux |
 |--------|-------|---------------|
-| Go to Files Tab | `⌘⇧F` | `Ctrl+Shift+F` |
-| Go to History Tab | `⌘⇧H` | `Ctrl+Shift+H` |
-| Go to Scratchpad | `⌘⇧S` | `Ctrl+Shift+S` |
-| Toggle Markdown Raw/Preview | `⌘E` | `Ctrl+E` |
+| Go to Files Tab | `Cmd+Shift+F` | `Ctrl+Shift+F` |
+| Go to History Tab | `Cmd+Shift+H` | `Ctrl+Shift+H` |
+| Go to Scratchpad | `Cmd+Shift+S` | `Ctrl+Shift+S` |
+| Toggle Markdown Raw/Preview | `Cmd+E` | `Ctrl+E` |
 
 ### Input & Output
 
 | Action | Key |
 |--------|-----|
-| Send Message | `Enter` or `⌘Enter` (configurable in Settings) |
-| Multiline Input | `⇧Enter` |
-| Navigate Command History | `↑` while in input |
-| Slash Commands | Type `/` to open autocomplete, `↑`/`↓` to navigate, `Tab`/`Enter` to select |
+| Send Message | `Enter` or `Cmd+Enter` (configurable in Settings) |
+| Multiline Input | `Shift+Enter` |
+| Navigate Command History | `Up Arrow` while in input |
+| Slash Commands | Type `/` to open autocomplete |
 | Focus Output | `Esc` while in input |
 | Focus Input | `Esc` while in output |
 | Open Output Search | `/` while in output |
-| Scroll Output Up/Down | `↑` / `↓` while in output |
-| Jump to Top of Output | `⌘↑` / `Ctrl+↑` while in output |
-| Jump to Bottom of Output | `⌘↓` / `Ctrl+↓` while in output |
+| Scroll Output | `Up/Down Arrow` while in output |
+| Jump to Top/Bottom | `Cmd+Up/Down Arrow` while in output |
 
 ### Navigation & Search
 
 | Action | Key |
 |--------|-----|
-| Navigate Sessions (Sidebar) | `↑` / `↓` while in sidebar |
+| Navigate Sessions | `Up/Down Arrow` while in sidebar |
 | Select Session | `Enter` while in sidebar |
 | Open Session Filter | `/` while in sidebar |
-| Navigate Files | `↑` / `↓` while in file tree |
+| Navigate Files | `Up/Down Arrow` while in file tree |
 | Open File Tree Filter | `/` while in file tree |
 | Open File Preview | `Enter` on selected file |
 | Close Preview/Filter/Modal | `Esc` |
@@ -280,39 +114,30 @@ This architecture enables seamless switching between AI and terminal modes witho
 
 | Action | macOS | Windows/Linux |
 |--------|-------|---------------|
-| Copy File Path | `⌘P` | `Ctrl+P` |
-| Open Search in Preview | `/` | `/` |
-| Scroll Preview | `↑` / `↓` | `↑` / `↓` |
-| Close Preview | `Esc` | `Esc` |
+| Copy File Path | `Cmd+P` | `Ctrl+P` |
+| Open Search | `/` | `/` |
+| Scroll | `Up/Down Arrow` | `Up/Down Arrow` |
+| Close | `Esc` | `Esc` |
 
-### Quick Actions Modal
-
-| Action | macOS | Windows/Linux |
-|--------|-------|---------------|
-| Select Action 1-8 | `⌘1-8` | `Ctrl+1-8` |
-| Navigate Actions | `↑` / `↓` | `↑` / `↓` |
-| Execute Action | `Enter` | `Enter` |
-
-*Most shortcuts are customizable in Settings → Shortcuts*
+*Most shortcuts are customizable in Settings > Shortcuts*
 
 ## Slash Commands
 
-Maestro includes an extensible slash command system with autocomplete. Commands are executed in the input area and affect the current session.
-
-### Available Commands
+Maestro includes an extensible slash command system with autocomplete:
 
 | Command | Description |
 |---------|-------------|
-| `/clear` | Clear the output history for the current mode (AI Terminal or Command Terminal) |
+| `/clear` | Clear the output history for the current mode |
 
-### Using Slash Commands
+Type `/` in the input area to open the autocomplete menu, use arrow keys to navigate, and press `Tab` or `Enter` to select.
 
-1. Type `/` in the input area to open the autocomplete menu
-2. Use `↑`/`↓` arrow keys to navigate commands
-3. Press `Tab` or `Enter` to select a command
-4. Press `Esc` to dismiss the autocomplete menu
+## Configuration
 
-The slash command system is extensible - new commands can be added in `src/renderer/slashCommands.ts`.
+Settings are stored in:
+
+- **macOS**: `~/Library/Application Support/maestro/`
+- **Windows**: `%APPDATA%/maestro/`
+- **Linux**: `~/.config/maestro/`
 
 ## Remote Access
 
@@ -325,8 +150,14 @@ Maestro includes a built-in web server for remote access:
 ### Enabling Public Tunnels
 
 1. Get an API token from [ngrok.com](https://ngrok.com) or Cloudflare
-2. Open Settings → Network
+2. Open Settings > Network
 3. Select your tunnel provider and enter your API key
 4. Start the tunnel from the session interface
 
-The web server provides REST API endpoints and WebSocket support for real-time session updates.
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, architecture details, and contribution guidelines.
+
+## License
+
+[MIT License](LICENSE)