diff --git a/README.es-ES.md b/README.es-ES.md
new file mode 100644
index 0000000..5c19d9a
--- /dev/null
+++ b/README.es-ES.md
@@ -0,0 +1,216 @@
+
+
+# herdr-nvim-nav
+
+Navegación fluida con `Ctrl+h/j/k/l` entre paneles de [herdr] y divisiones de Neovim —
+la experiencia de [vim-tmux-navigator], para herdr.
+
+> **Exclusivo para Neovim, basado en sockets, sin procesos por pulsación.** Si también
+> deseas soporte para **Vim** o una implementación en shell sencillo, consulta
+> [Obras previas](#obras-previas) — ese proyecto sigue un enfoque diferente.
+
+Presiona `Ctrl+h/j/k/l` y el cursor se moverá a la división en esa dirección. Cuando
+alcances el borde de las divisiones de Neovim, la misma pulsación cruzará hacia el
+panel vecino de herdr en lugar de detenerse. También funciona a la inversa: desde un
+panel normal, el atajo mueve el foco de herdr; desde un panel que ejecuta Neovim, el atajo
+se pasa a Neovim.
+
+[herdr]: https://herdr.dev
+[vim-tmux-navigator]: https://github.com/christoomey/vim-tmux-navigator
+
+## Cómo funciona
+
+tmux responde a "¿es este panel Neovim?" con una opción de panel (`@pane-is-vim`) y un
+atajo condicional (`if -F`). herdr no tiene ninguno de los dos, por lo que este plugin reconstruye
+la decisión:
+
+- **Neovim** escribe su PID en un archivo marcador con el nombre del panel
+  (`$XDG_CACHE_HOME/herdr/nvim-panes/<pane-id>`) al entrar, y lo elimina al
+  salir. Un PID obsoleto dejado por un fallo se reconoce (vía `kill(pid, 0)`) y
+  se limpia.
+- La **acción de herdr** (id del plugin `herdr-nvim-nav`) lee ese marcador en cada pulsación. Si un
+  Neovim activo posee el panel enfocado, reenvía el atajo a través del socket de control
+  de herdr (`pane.send_keys`); de lo contrario, mueve el foco del panel de herdr
+  (`pane.focus_direction`).
+
+La acción es un binario pequeño en C, no un script de shell, a propósito. herdr debe
+hacer fork/exec de *algo* por pulsación (~2.4 ms aquí); añadir `sh` más la CLI de herdr
+por encima añadía ~8 ms para 0.3 ms de trabajo real de socket. El binario en C realiza ese
+trabajo en el único proceso que herdr ya tenía que iniciar. Consulta el bloque de comentarios en la
+parte superior de [`herdr-nvim-nav.c`](herdr-nvim-nav.c) para ver las mediciones.
+
+## Requisitos
+
+- **herdr** ≥ 0.7.0
+- **Neovim** (0.9+ recomendado, para `vim.uv`)
+- Un compilador de C (`cc` / `clang` / `gcc`) — utilizado durante la compilación en la instalación. La
+  instrucción `herdr plugin install` lo ejecuta por ti; solo un `plugin link` local lo necesita disponible.
+- **christoomey/vim-tmux-navigator** — solo si ejecutas Neovim bajo tmux
+  (`with_tmux`); las configuraciones solo con herdr no lo necesitan.
+- macOS o Linux
+
+## Instalación
+
+### 1. Instalar la acción de herdr
+
+**Desde GitHub (recomendado):**
+
+```sh
+herdr plugin install aimdevlee/herdr-nvim-nav
+```
+
+El comando `[[build]]` del manifiesto compila el binario de C durante la instalación, por lo que
+no hay un paso de compilación separado. Fija una versión con `--ref <tag|sha>`.
+
+**Desde un clon local** (para desarrollo):
+
+```sh
+git clone https://github.com/aimdevlee/herdr-nvim-nav
+cd herdr-nvim-nav
+make                                  # produces ./herdr-nvim-nav
+herdr plugin link "$PWD"              # link — build commands are NOT run
+```
+
+`herdr plugin link` omite `[[build]]`, por lo que compila con `make` tú mismo primero, y
+vuelve a compilar después de cualquier `git pull` que modifique `herdr-nvim-nav.c`. El binario
+compilado es un artefacto de construcción y no se commita. `herdr server reload-config`
+vuelve a leer `config.toml`, no los manifiestos de los plugins.
+
+### 2. Asignar las teclas en herdr
+
+En `~/.config/herdr/config.toml`, asigna las cuatro direcciones a las acciones del
+plugin:
+
+```toml
+[[keys.command]]
+key = "ctrl+h"
+type = "plugin_action"
+command = "herdr-nvim-nav.left"
+
+[[keys.command]]
+key = "ctrl+j"
+type = "plugin_action"
+command = "herdr-nvim-nav.down"
+
+[[keys.command]]
+key = "ctrl+k"
+type = "plugin_action"
+command = "herdr-nvim-nav.up"
+
+[[keys.command]]
+key = "ctrl+l"
+type = "plugin_action"
+command = "herdr-nvim-nav.right"
+```
+
+Luego recarga: `herdr server reload-config`.
+
+### 3. Instalar la parte de Neovim
+
+La parte de Neovim es un módulo agnóstico al gestor de plugins
+([`lua/herdr-nvim-nav/init.lua`](lua/herdr-nvim-nav/init.lua)). Instálalo como
+cualquier plugin de Neovim y llama a `setup()`. Mantiene el marcador de panel que lee la
+acción de herdr, y asigna `<C-h/j/k/l>` (junto con las variantes de flechas) para moverse dentro
+de las divisiones de Neovim, cayendo en herdr — o en tmux cuando se ejecuta bajo tmux.
+
+**lazy.nvim:**
+
+```lua
+{
+  'aimdevlee/herdr-nvim-nav',
+  dependencies = { 'christoomey/vim-tmux-navigator' }, -- omitir si with_tmux = false
+  config = function()
+    require('herdr-nvim-nav').setup()
+  end,
+}
+```
+
+**packer:**
+
+```lua
+use {
+  'aimdevlee/herdr-nvim-nav',
+  requires = { 'christoomey/vim-tmux-navigator' }, -- omitir si with_tmux = false
+  config = function() require('herdr-nvim-nav').setup() end,
+}
+```
+
+**Manual** (cualquier runtimepath): coloca `lua/herdr-nvim-nav/` en tu runtimepath y
+llama `require('herdr-nvim-nav').setup{ with_tmux = false }` desde tu init.
+
+#### Alternativa para tmux
+
+`christoomey/vim-tmux-navigator` se utiliza **solo** cuando Neovim se ejecuta bajo tmux
+(no herdr). `with_tmux` se detecta automáticamente desde `$TMUX`, por lo que los usuarios de tmux no necesitan
+configuración. Si nunca ejecutas Neovim bajo tmux, elimina la dependencia y configura
+`with_tmux = false` — no se cargará nada relacionado con tmux.
+
+#### Opciones
+
+```lua
+require('herdr-nvim-nav').setup({
+  with_tmux = nil,          -- nil = detectar automáticamente $TMUX; true/false para forzar
+  keymaps = {               -- lista de teclas por dirección; {} deshabilita una dirección
+    left  = { '<C-h>', '<C-Left>' },
+    down  = { '<C-j>', '<C-Down>' },
+    up    = { '<C-k>', '<C-Up>' },
+    right = { '<C-l>', '<C-Right>' },
+  },
+  socket_path = nil,        -- predeterminado: $HERDR_SOCKET_PATH o ~/.config/herdr/herdr.sock
+  cache_dir = nil,          -- predeterminado: $XDG_CACHE_HOME o ~/.cache
+  herdr_bin = nil,          -- predeterminado: $HERDR_BIN_PATH o "herdr"
+  socket_timeout_ms = 150,
+})
+```
+
+## Configuración
+
+Ambas partes respetan estas variables de entorno. La parte de Neovim también acepta las
+opciones de `setup()` correspondientes anteriores, que prevalecen sobre el entorno cuando se establecen; la acción en
+C solo lee el entorno.
+
+| Variable | opción `setup()` | Usado por | Predeterminado |
+| --- | --- | --- | --- |
+| `HERDR_SOCKET_PATH` | `socket_path` | C, lua | `~/.config/herdr/herdr.sock` |
+| `XDG_CACHE_HOME` | `cache_dir` | C, lua | `~/.cache` (raíz del directorio de marcadores) |
+| `HERDR_BIN_PATH` | `herdr_bin` | lua | `herdr` en `$PATH` (alternativa de CLI) |
+| `HERDR_PANE_ID` | — | C, lua | configurado por herdr por panel |
+
+## Solución de problemas
+
+- **Las teclas mueven paneles pero nunca llegan a Neovim.** El marcador no se está escribiendo —
+  confirma que se ejecutó `require('herdr-nvim-nav').setup()` y que `HERDR_PANE_ID` está configurado en el panel
+  (`echo $HERDR_PANE_ID`). Verifica que `$XDG_CACHE_HOME/herdr/nvim-panes/` reciba un
+  archivo mientras Neovim está enfocado.
+- **No sucede nada en absoluto.** herdr registra el stderr y el código de salida de la acción —
+  consulta `herdr plugin log`. Se reportará allí si una solicitud de socket es rechazada.
+- **Socket de herdr incorrecto.** Establece `HERDR_SOCKET_PATH` explícitamente si tu socket de herdr
+  no está en la ruta predeterminada.
+
+## Obras previas
+
+[**paulbkim-dev/vim-herdr-navigation**][prior] resuelve el mismo problema y salió
+primero. Vale la pena usarlo — y hace dos cosas que este proyecto no: soporta
+**Vim** así como Neovim, y su parte de herdr es un script de shell portátil
+sin paso de compilación.
+
+Este proyecto realiza diferentes compromisos a propósito:
+
+| | vim-herdr-navigation | herdr-nvim-nav |
+| --- | --- | --- |
+| Verificación "¿Es Vim?" | CLI de herdr `pane process-info` + `jq` en el proceso de primer plano | archivo marcador mantenido por Neovim + `kill(pid,0)` |
+| Lado herdr | `navigate.sh` (bash, necesita `jq`) | `herdr-nvim-nav` (C compilado, sin dependencias de ejecución) |
+| Transporte herdr | CLI (`herdr pane …`) | socket de control directamente |
+| Coste por pulsación | carga de binario de herdr + proceso `jq` | un proceso, socket directo (~3 ms) |
+| Editores | Vim + Neovim | Neovim |
+
+La versión corta: elige **vim-herdr-navigation** si usas Vim o quieres
+evitar un compilador; elige **esto** si solo usas Neovim y quieres que el atajo
+cueste lo menos posible por pulsación. El fundamento del diseño y las mediciones están
+en el encabezado de [`herdr-nvim-nav.c`](herdr-nvim-nav.c).
+
+[prior]: https://github.com/paulbkim-dev/vim-herdr-navigation
+
+## Licencia
+
+[MIT](LICENSE) © aimdevlee