diff --git a/README.md b/README.md
index 4bfd372..41fe8a5 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,474 @@
-# gh-switch
+# gh-switch - GitHub Account Switcher 🔄
 
-Fast GitHub account switcher for managing multiple GitHub identities.
+A fast, reliable command-line tool for managing multiple GitHub accounts. Switch between personal, work, and other GitHub identities seamlessly without manual SSH or Git config editing.
 
-## Features
-- 🔄 Quick account switching
-- 🔐 SSH key management
-- ⚡ Auto-detection based on repo
-- 🛠️ Works on Mac & Linux
+![Shell](https://img.shields.io/badge/shell-bash-green.svg)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg)
 
-## Quick Start
+## ✨ Features
+
+- **Instant Switching**: Change GitHub accounts with a single command
+- **SSH Key Management**: Automatically configures SSH hosts for each profile
+- **Git Config Integration**: Updates user.name and user.email per repository
+- **Profile Storage**: Securely stores multiple account profiles
+- **Auto-Detection**: Automatically detects and switches profiles based on repository
+- **Remote URL Updates**: Automatically updates git remote URLs when switching
+- **No Dependencies**: Pure shell script - works everywhere
+- **Backup Safety**: Automatically backs up SSH config before modifications
+
+## 🚀 Quick Start
+
+### Installation
+
+#### Method 1: Direct Installation (Recommended)
+
+```bash
+# Download and install
+curl -sSL https://raw.githubusercontent.com/TheDevOpsBlueprint/gh-switch/main/bin/gh-switch-standalone -o /tmp/gh-switch
+chmod +x /tmp/gh-switch
+sudo mv /tmp/gh-switch /usr/local/bin/gh-switch
+
+# Verify installation
+gh-switch --version
+```
+
+#### Method 2: From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/TheDevOpsBlueprint/gh-switch.git
+cd gh-switch
+
+# Install
+chmod +x bin/gh-switch-standalone
+sudo cp bin/gh-switch-standalone /usr/local/bin/gh-switch
+
+# Verify
+gh-switch --version
+```
+
+#### Method 3: Using Make
+
+```bash
+# Clone and install
+git clone https://github.com/TheDevOpsBlueprint/gh-switch.git
+cd gh-switch
+make install
+```
+
+### Initial Setup
+
+```bash
+# Initialize gh-switch
+gh-switch init
+
+# Add your first profile (personal)
+gh-switch add personal
+
+# Add a work profile
+gh-switch add work
+```
+
+## 📖 Usage Guide
+
+### Managing Profiles
+
+#### Adding a Profile
+
+```bash
+# Add a new profile interactively
+gh-switch add personal
+
+# You'll be prompted for:
+# - SSH key path: ~/.ssh/id_ed25519_personal
+# - Git name: John Doe
+# - Git email: john@personal.com
+# - GitHub username: johndoe
+```
+
+#### Listing Profiles
+
+```bash
+# Show all profiles
+gh-switch list
+
+# Output:
+# Available profiles:
+# ==================
+# * personal (active)
+#     User: John Doe
+#     Email: john@personal.com
+#   
+#   work
+#     User: John Smith
+#     Email: john.smith@company.com
+```
+
+#### Switching Profiles
+
+```bash
+# Switch profile for current repository
+gh-switch use work
+
+# Switch globally (all new repos)
+gh-switch use personal --global
+
+# Check current profile
+gh-switch current
+```
+
+### Working with Repositories
+
+#### Cloning with Specific Profile
+
+```bash
+# Use personal profile for personal projects
+gh-switch use personal
+git clone git@github.com-personal:johndoe/my-project.git
+
+# Use work profile for work projects
+gh-switch use work
+git clone git@github.com-work:company/work-project.git
+```
+
+#### Converting Existing Repository
+
+```bash
+# Go to existing repo
+cd ~/projects/my-repo
+
+# Switch to desired profile
+gh-switch use personal
+
+# The remote URL is automatically updated
+git remote -v
+# origin  git@github.com-personal:johndoe/my-repo.git
+```
+
+#### Auto-Detection
+
+```bash
+# Automatically detect profile from remote URL
+cd ~/projects/some-repo
+gh-switch auto
+# Detects and switches to the appropriate profile
+```
+
+### Advanced Usage
+
+#### Profile Management
+
+```bash
+# Delete a profile
+gh-switch delete old-profile
+
+# Edit profile (delete and re-add)
+gh-switch delete work
+gh-switch add work
+```
+
+#### SSH Key Testing
+
+```bash
+# Test personal account SSH connection
+ssh -T git@github.com-personal
+# Hi johndoe! You've successfully authenticated...
+
+# Test work account SSH connection
+ssh -T git@github.com-work
+# Hi john-work! You've successfully authenticated...
+```
+
+## 📁 Configuration
+
+### File Locations
+
+```
+~/.config/gh-switch/
+├── config              # Main configuration
+├── current             # Currently active profile
+└── profiles/           # Profile storage
+    ├── personal        # Personal profile config
+    └── work           # Work profile config
+```
+
+### SSH Config Structure
+
+gh-switch adds entries to `~/.ssh/config`:
+
+```ssh
+# GitHub account: personal
+Host github.com-personal
+  HostName github.com
+  User git
+  IdentityFile ~/.ssh/id_ed25519_personal
+  IdentitiesOnly yes
+
+# GitHub account: work
+Host github.com-work
+  HostName github.com
+  User git
+  IdentityFile ~/.ssh/id_ed25519_work
+  IdentitiesOnly yes
+```
+
+### Profile Structure
+
+Each profile stores:
+- SSH key path
+- Git user name
+- Git email address
+- GitHub username
+- SSH host alias
+
+## 🎨 Command Reference
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `init` | Initialize gh-switch | `gh-switch init` |
+| `add` | Add a new profile | `gh-switch add personal` |
+| `use` | Switch to a profile | `gh-switch use work` |
+| `current` | Show active profile | `gh-switch current` |
+| `list` | List all profiles | `gh-switch list` |
+| `delete` | Remove a profile | `gh-switch delete old` |
+| `auto` | Auto-detect profile | `gh-switch auto` |
+| `help` | Show help message | `gh-switch help` |
+
+### Command Options
+
+- `--global` - Apply profile globally (with `use` command)
+- `--version` / `-v` - Show version information
+
+## 🔧 Shell Aliases
+
+Add to your `~/.bashrc` or `~/.zshrc` for quicker access:
+
+```bash
+# Quick aliases
+alias ghs='gh-switch'
+alias ghsp='gh-switch use personal'
+alias ghsw='gh-switch use work'
+alias ghsl='gh-switch list'
+alias ghsc='gh-switch current'
+
+# Function to clone with profile
+ghclone() {
+  local profile=$1
+  local repo=$2
+  gh-switch use $profile
+  git clone $repo
+}
+
+# Usage: ghclone personal git@github.com-personal:user/repo.git
+```
+
+## 📋 Prerequisites
+
+- **Git**: Version 2.0 or higher
+- **OpenSSH**: Standard SSH client
+- **Bash**: Version 4.0+ (macOS/Linux)
+- **GitHub Account**: With SSH keys configured
+
+### Setting Up SSH Keys
+
+Before using gh-switch, ensure you have SSH keys for each GitHub account:
+
+```bash
+# Generate key for personal account
+ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_personal -C "personal@email.com"
+
+# Generate key for work account
+ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_work -C "work@company.com"
+
+# Add keys to SSH agent
+ssh-add ~/.ssh/id_ed25519_personal
+ssh-add ~/.ssh/id_ed25519_work
+```
+
+Then add each public key to the corresponding GitHub account's settings.
+
+## 🧪 Typical Workflows
+
+### Daily Development
+
+```bash
+# Morning - work on company project
+cd ~/work/company-api
+gh-switch use work
+git pull origin main
+# ... do work, commits use work identity
+
+# Afternoon - personal project
+cd ~/personal/side-project
+gh-switch use personal
+git pull origin main
+# ... commits use personal identity
+
+# Check active profile anytime
+gh-switch current
+```
+
+### New Project Setup
+
+```bash
+# Personal project
+gh-switch use personal
+mkdir ~/projects/new-app
+cd ~/projects/new-app
+git init
+git remote add origin git@github.com-personal:johndoe/new-app.git
+
+# Work project
+gh-switch use work
+mkdir ~/work/new-service
+cd ~/work/new-service
+git init
+git remote add origin git@github.com-work:company/new-service.git
+```
+
+### Migrating Existing Repositories
+
+```bash
+# List current remotes
+cd ~/projects/existing-repo
+git remote -v
+# origin git@github.com:johndoe/existing-repo.git
+
+# Switch to profile
+gh-switch use personal
+
+# Remote is automatically updated
+git remote -v
+# origin git@github.com-personal:johndoe/existing-repo.git
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Issue: "command not found"**
+```bash
+# Check installation
+which gh-switch
+
+# Ensure /usr/local/bin is in PATH
+echo $PATH
+
+# Reinstall if needed
+sudo cp bin/gh-switch-standalone /usr/local/bin/gh-switch
+```
+
+**Issue: "Permission denied (publickey)"**
+```bash
+# Check SSH key is loaded
+ssh-add -l
+
+# Add key to agent
+ssh-add ~/.ssh/your_key
+
+# Test connection
+ssh -T git@github.com-personal
+```
+
+**Issue: "Not in a git repository"**
+```bash
+# For local repository changes
+cd your-git-repo
+gh-switch use profile-name
+
+# For global changes
+gh-switch use profile-name --global
+```
+
+**Issue: SSH config already has entries**
 ```bash
-curl -sSL https://raw.githubusercontent.com/YOUR-ORG/gh-switch/main/install.sh | bash
-gh-switch init
\ No newline at end of file
+# Backup is created automatically
+ls ~/.ssh/config.gh-switch.backup
+
+# Manually restore if needed
+cp ~/.ssh/config.gh-switch.backup ~/.ssh/config
+```
+
+### Debug Commands
+
+```bash
+# Check profile details
+cat ~/.config/gh-switch/profiles/personal
+
+# View current profile
+cat ~/.config/gh-switch/current
+
+# Check SSH config entries
+grep "github.com-" ~/.ssh/config
+
+# Test SSH authentication
+ssh -vT git@github.com-personal  # Verbose output
+```
+
+## 🤝 Contributing
+
+We follow a small PR philosophy - each PR should be 40-80 lines max:
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feat/amazing-feature`)
+3. Keep changes focused and minimal
+4. Test thoroughly on macOS and Linux
+5. Submit a Pull Request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+## 📄 Project Structure
+
+```
+gh-switch/
+├── bin/
+│   ├── gh-switch              # Main script (development)
+│   └── gh-switch-standalone   # Standalone version
+├── lib/
+│   ├── common.sh              # Common utilities
+│   ├── profile.sh             # Profile management
+│   ├── ssh_parser.sh          # SSH config parsing
+│   ├── ssh_writer.sh          # SSH config writing
+│   ├── git_config.sh          # Git configuration
+│   └── cmd_*.sh               # Command implementations
+├── completions/
+│   ├── gh-switch.bash         # Bash completion
+│   └── gh-switch.zsh          # Zsh completion
+├── tests/
+│   └── test_basic.sh          # Test suite
+├── install.sh                 # Installation script
+├── Makefile                   # Make targets
+└── README.md                  # This file
+```
+
+## 🚀 Uninstallation
+
+```bash
+# Remove the binary
+sudo rm /usr/local/bin/gh-switch
+
+# Remove configuration (optional - preserves profiles)
+rm -rf ~/.config/gh-switch
+
+# Remove SSH config entries (manual review recommended)
+# Edit ~/.ssh/config and remove gh-switch sections
+```
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+Built with pure shell scripting for maximum compatibility and zero dependencies.
+
+## 📞 Support
+
+- **Issues**: [GitHub Issues](https://github.com/TheDevOpsBlueprint/gh-switch/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/TheDevOpsBlueprint/gh-switch/discussions)
+- **Author**: Valentin Todorov
+
+---
+
+**Note**: This tool modifies your SSH config and Git settings. Always review changes and maintain backups of important configurations.
\ No newline at end of file