diff --git a/README.md b/README.md
index f57278b..305ea50 100644
--- a/README.md
+++ b/README.md
@@ -1,133 +1,315 @@
-emacs-personal
-Lightweight configuration of emacs with basic utilities plus personal configuration
+# emacs-personal
+
+> Lightweight Emacs configuration with essential utilities and personal customizations
-### Installation
+[](LICENSE)
+[](https://www.gnu.org/software/emacs/)
-First step:
+---
- M-x package-refresh-contents [RET]
+## Table of Contents
-#### Main mirror
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Configuration](#configuration)
+- [Key Bindings](#key-bindings)
+- [Language Support](#language-support)
+- [Troubleshooting](#troubleshooting)
+- [Project Structure](#project-structure)
+- [License](#license)
-1. `git clone https://c.fridu.us/software/emacs-personal.git ~/.emacs.d/`
-2. `cp -v ~/.emacs.d/.env.example ~/.emacs.d/.env`
-3. `emacs --batch --eval='(load-file "~/.emacs.d/init.el")'`
+---
-#### Secundary mirror
+## Features
-1. `git clone https://git.sr.ht/~heckyel/emacs-personal ~/.emacs.d/`
-2. `cp -v ~/.emacs.d/.env.example ~/.emacs.d/.env`
-3. `emacs --batch --eval='(load-file "~/.emacs.d/init.el")'`
+- **Fast Startup** - Optimized loading with garbage collection tuning
+- **Modern Theme** - VSCode-inspired dark theme
+- **Package Management** - ELPA + MELPA integration
+- **Enhanced Navigation** - Ivy + Projectile for fuzzy finding
+- **Intelligent Completion** - Company mode with multiple backends
+- **Multi-language Support** - Python, JS/TS, PHP, Go, C/C++, and more
+- **Code Quality** - Flycheck + Linter integration
+- **File Explorer** - Neotree sidebar
+- **Dashboard** - Clean startup screen
+- **Developer Tools** - Docker, Terraform, REST client
-### Requirements
+---
-* [x] ttf-hack
-* [x] ttf-anonymous-pro
-* [x] hyphen
-* [x] hyphen-es
-* [x] markdown
-* [x] shellcheck
-* [x] python-virtualenv
-* [x] python-pylint
+## Quick Start
+
+```bash
+# Clone the repository
+git clone https://git.fridu.us/software/emacs-personal.git ~/.emacs.d/
+
+# Copy environment configuration
+cp ~/.emacs.d/.env.example ~/.emacs.d/.env
+
+# Initialize packages (first time only)
+emacs --batch --eval='(load-file "~/.emacs.d/init.el")'
+```
+
+---
+
+## Installation
+
+### Step 1: Refresh Package Contents
+
+Inside Emacs, run:
+
+```elisp
+M-x package-refresh-contents [RET]
+```
+
+### Step 2: Clone Repository
+
+#### Primary Mirror
+
+```bash
+git clone https://git.fridu.us/software/emacs-personal.git ~/.emacs.d/
+```
+
+#### Secondary Mirror
+
+```bash
+git clone https://git.sr.ht/~heckyel/emacs-personal ~/.emacs.d/
+```
+
+### Step 3: Configure Environment
+
+```bash
+cp -v ~/.emacs.d/.env.example ~/.emacs.d/.env
+```
+
+### Step 4: Initialize
+
+```bash
+emacs --batch --eval='(load-file "~/.emacs.d/init.el")'
+```
+
+---
+
+## Requirements
+
+### System Dependencies
+
+| Package | Description |
+|---------|-------------|
+| `ttf-hack` | Hack font family |
+| `ttf-anonymous-pro` | Anonymous Pro font |
+| `hyphen` | Hyphenation patterns |
+| `hyphen-es` | Spanish hyphenation |
+| `markdown` | Markdown processor |
+| `shellcheck` | Shell script analyzer |
+| `python-virtualenv` | Python virtual environments |
+| `python-pylint` | Python linter |
+
+### Install on Arch Linux
+
+```bash
+sudo pacman -S ttf-hack ttf-anonymous-pro hyphen hyphen-es \
+ markdown shellcheck python-virtualenv python-pylint
+```
+
+### Install on Debian/Ubuntu
+
+```bash
+sudo apt install fonts-hack fonts-anonymous-pro hyphen hyphen-es \
+ markdown shellcheck python3-venv pylint
+```
+
+---
+
+## Configuration
### Fonts
-change the typography in the [init-gui.el](modules/init-gui.el#L54) file
+
+Edit [`init-gui.el`](modules/init-gui.el#L54) to customize typography:
+
+```elisp
+(if (member "Hack" (font-family-list))
+ (set-frame-font "Hack-9")
+ (set-frame-font "DejaVu Sans Mono-10"))
+```
### Icons
-```console
-$ emacs --batch --eval="(progn (package-initialize)(package-install 'all-the-icons))"
+Install `all-the-icons` package:
+
+```bash
+emacs --batch --eval="(progn (package-initialize) (package-install 'all-the-icons))"
```
-### Markdown Mode
+Then press `F8` to open Neotree (will prompt to install fonts on first run).
-Require installed markdown in distro GNU+Linux, example:
+### Environment Variables
-```console
-$ apt install markdown
+Copy and edit `.env.example`:
+
+```bash
+cp ~/.emacs.d/.env.example ~/.emacs.d/.env
```
-or
+---
-```console
-$ pacman -S markdown
+## Key Bindings
+
+| Key | Action |
+|-----|--------|
+| `F6` | Toggle line numbers |
+| `F8` | Open Neotree file explorer |
+| `F11` | Toggle fullscreen |
+| `F12` | Revert buffer |
+| `M-0` | Reset frame transparency |
+| `S-C-+` | Increase font size |
+| `S-C--` | Decrease font size |
+| `S-h` | Toggle highlight current line |
+| `C->` | Mark next occurrence (multi-cursor) |
+| `C-<` | Mark previous occurrence (multi-cursor) |
+| `C-c C-<` | Mark all occurrences (multi-cursor) |
+| `C-x e` | Evaluate last expression |
+
+---
+
+## Language Support
+
+### Python
+
+```bash
+# Install dependencies
+sudo pacman -S python-virtualenv python-pylint
```
-### Flycheck Mode
-- Require installed the languages checking, example:
+| Command | Action |
+|---------|--------|
+| `M-x pyvenv-mode` | Toggle virtualenv |
+| `M-x pyvenv-create` | Create virtualenv |
+| `M-x pyvenv-activate` | Activate virtualenv |
-#### bash, sh
+### JavaScript / TypeScript
-```console
-$ pacman -S shellcheck
+- Auto-completion with Company mode
+- Syntax checking with Flycheck
+- Emmet support for HTML/CSS
+
+### Shell Scripts
+
+```bash
+sudo pacman -S shellcheck
```
-#### python
+### Markdown
-```console
-$ pacman -S python-pylint
+```bash
+# Arch
+sudo pacman -S markdown
+
+# Debian/Ubuntu
+sudo apt install markdown
```
-### Neotree
+### Other Languages
-Neotree comes by default in combination with all-the-icons.
-So pressing `[f8]` will display (you must give "yes") a one-time screen to install all-the-icons fonts.
+- C/C++/C#
+- PHP
+- Go
+- Lua
+- Ruby
+- YAML
+- Dockerfile
+- Terraform
+- reStructuredText (ox-reveal)
-### Linum
-So pressing `[f6]` will display
-
-### Mode Python
-- Require installed virtualenv:
-
- $ pacman -S python-virtualenv
-
-- Enable or disable pyvenv-mode: M-x pyvenv-mode
-
-- To create virtualenv from emacs:
-
- $ pyvenv-create
-
-- To activate virtualenv from emacs:
-
- $ pyvenv-activate
+---
## Troubleshooting
-```bash
+### GPG Signature Error
+
+```
Failed to verify signature archive-contents.sig:
-No public key for 066DAFCB81E42C40 created at 2019-10-05T04:10:02-0500 using RSA
-Command output:
-gpg: Firmado el sáb 05 oct 2019 04:10:02 -05
-gpg: usando RSA clave C433554766D3DDC64221BFAA066DAFCB81E42C40
-gpg: Imposible comprobar la firma: No public key
+No public key for 066DAFCB81E42C40
```
-### Method 0
+#### Method 1: Import GPG Key
-```console
-$ gpg --homedir ~/.emacs.d/elpa/gnupg --receive-keys 066DAFCB81E42C40
+```bash
+gpg --homedir ~/.emacs.d/elpa/gnupg --receive-keys 066DAFCB81E42C40
```
-### Method 1
+#### Method 2: Disable Signature Check (Temporary)
-Disable temp signature key
+```bash
+# Disable signature check
+sed -i "s|(setq package-check-signature 'allow-unsigned)|(setq package-check-signature nil)|g" \
+ "$HOME/.emacs.d/init.el"
-```console
-$ sed -i "s|(setq package-check-signature 'allow-unsigned)|(setq package-check-signature nil)|g" "$HOME/.emacs.d/init.el"
-```
-
-```console
+# Inside Emacs
M-x package-install RET gnu-elpa-keyring-update RET
+
+# Re-enable signature check
+sed -i "s|(setq package-check-signature nil)|(setq package-check-signature 'allow-unsigned)|g" \
+ "$HOME/.emacs.d/init.el"
```
-and enable signature key
+### Package Installation Issues
-```console
-$ sed -i "s|(setq package-check-signature nil)|(setq package-check-signature 'allow-unsigned)|g" "$HOME/.emacs.d/init.el"
+If packages fail to install, try:
+
+```elisp
+M-x package-refresh-contents
+M-x package-reinstall RET RET
```
-## Evaluate in buffer
+### Font Issues
-C-x + C-e
+If fonts don't render correctly:
+
+1. Install fonts: `M-x all-the-icons-install-fonts`
+2. Restart Emacs
+3. Check available fonts: `M-x font-selector`
+
+---
+
+## Project Structure
+
+```
+~/.emacs.d/
+├── init.el # Main configuration file
+├── custom.el # User customizations (auto-generated)
+├── settings.el # Personal settings
+├── .env.example # Environment variables template
+├── modules/ # Feature modules
+│ ├── init-gui.el # GUI settings
+│ ├── init-elpa.el # Package management
+│ ├── init-company.el # Auto-completion
+│ ├── init-flycheck.el # Syntax checking
+│ ├── init-python.el # Python support
+│ └── ...
+└── elpa/ # Installed packages
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## Acknowledgments
+
+- [GNU Emacs](https://www.gnu.org/software/emacs/)
+- [MELPA](https://melpa.org/)
+- [Doom Emacs](https://github.com/hlissner/doom-emacs)
+- [Spacemacs](https://www.spacemacs.org/)
+
+---
+
+