Initial implementation: gitswarm REPL, build script, README

Adds:
- gitswarm.py: REPL interactivo con rich que escanea repos git de
  primer nivel, muestra estado (ahead/behind/dirty) y permite update
  <repo>|all via git pull --ff-only.
- gitswarm: wrapper bash que invoca el venv local.
- build.sh: compila a binario standalone con Nuitka --onefile.
- requirements.txt: rich.
- README.md: uso, requisitos del sistema (python3-dev, gcc, patchelf
  para el build) e instrucciones de desarrollo y compilacion.

README.md

@@ -1,3 +1,72 @@
 # gitswarm
 
-Aplicació per escanejar repos gits locals i comprovar el estat
+Lista y actualiza repos git de primer nivel dentro de una carpeta. REPL interactivo con colores y tabla.
+
+## Uso
+
+```bash
+gitswarm /ruta/a/escanear
+```
+
+Te muestra una tabla con los repos detectados y entra a un prompt:
+
+- `list` / `ls` — vuelve a mostrar la tabla
+- `refresh` / `r` — re-escanea haciendo `git fetch`
+- `update <repo>` — `git pull --ff-only` (acepta nº, nombre exacto o fragmento)
+- `update all` — actualiza todos los que estén behind
+- `help` / `?`
+- `quit` / `q` (también Ctrl-D / Ctrl-C)
+
+El estado se calcula con `git fetch` al arrancar y al hacer `refresh`. `update` aborta si el repo tiene cambios locales sin commitear.
+
+## Requisitos en el sistema
+
+Necesarios siempre:
+
+- `python3` (≥ 3.10)
+- `git`
+
+Para desarrollar (con venv y rich pip-installed):
+
+- `python3-venv`
+
+Para compilar a binario con Nuitka (`./build.sh`):
+
+- `python3-dev` — cabeceras `Python.h`
+- `gcc` — compilador C
+- `patchelf` — necesario para el modo `--onefile` en Linux
+
+En Debian/Ubuntu:
+
+```bash
+sudo apt install python3 python3-venv python3-dev git gcc patchelf
+```
+
+## Desarrollo (con venv)
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+./gitswarm /ruta/a/escanear   # wrapper que usa el venv
+```
+
+## Compilar a binario standalone
+
+```bash
+./build.sh
+```
+
+Genera `dist/gitswarm`, un único ejecutable autocontenido (lleva Python + rich dentro). Para instalarlo en tu PATH:
+
+```bash
+cp dist/gitswarm ~/.local/bin/
+```
+
+## Ficheros
+
+- `gitswarm.py` — script principal
+- `gitswarm` — wrapper bash que invoca el venv local (para desarrollo)
+- `requirements.txt` — dependencias Python (`rich`)
+- `build.sh` — compila el binario con Nuitka
+- `.venv/` — virtualenv local (no en git)
+- `dist/` — binarios compilados (no en git)