From 11831f905b28355dd32878ad0218f1e1a36a320b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jose=20Luis=20Monta=C3=B1es=20Ojados?= <joseluis@zubi.group>
Date: Wed, 28 Jan 2026 14:45:06 +0100
Subject: [PATCH] initial commit

---
 readme.md | 126 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)
 create mode 100644 readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..797c4b2
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,126 @@
+# 🛡️ EnvGuard (Integration Lock Manager)
+
+> **Stop asking "Who is touching the Payment Service?" in Slack.**
+
+**EnvGuard** es una herramienta TUI (Terminal User Interface) escrita en Go para gestionar la concurrencia y evitar *race conditions* en nuestro entorno de integración. Permite visualizar, reservar y liberar microservicios en tiempo real sin salir de la terminal.
+
+## 📸 Preview
+
+Así es como se ve `envguard` cuando lo ejecutas:
+
+```text
+┌────────────────────────────────────────────────────────────────┐
+│  🛡️  ENV-GUARD v1.0  |  Conectado como: @dev_actual            │
+├────────────────────────────────────────────────────────────────┤
+│                                                                │
+│  SERVICIO          ESTADO       USUARIO       TIEMPO           │
+│  ────────────────  ──────────   ───────────   ──────────────   │
+│  auth-service      🟢 LIBRE     --            --               │
+│> payments-api      🔴 LOCKED    @carlos       Hace 12m         │
+│  user-db           🔴 LOCKED    @sofia        Hace 03m         │
+│  notifications     🟢 LIBRE     --            --               │
+│  front-web         🔴 LOCKED    @tu (YO)      Hace 10s         │
+│                                                                │
+├────────────────────────────────────────────────────────────────┤
+│  [↑/↓] Navegar   [Enter] Reservar/Liberar   [Q] Salir          │
+└────────────────────────────────────────────────────────────────┘
+
+```
+
+## 🚀 Cómo funciona
+
+El sistema consta de dos partes:
+
+1. **Server (`cmd/server`):** Una API ligera que mantiene el estado de los bloqueos en memoria (Source of Truth).
+2. **CLI (`cmd/cli`):** El cliente TUI desarrollado con [Bubble Tea](https://github.com/charmbracelet/bubbletea) que consumen los desarrolladores.
+
+### Flujo de Trabajo
+
+1. Abres la terminal y ejecutas `envguard`.
+2. Ves que **payments-api** está libre.
+3. Pulsas `Enter` sobre él.
+4. El servidor registra el bloqueo a tu nombre.
+5. Tus compañeros ven instantáneamente (polling) que tú lo estás usando.
+
+## 🛠️ Desarrollo y Setup Local
+
+Sigue estos pasos para arrancar el entorno de desarrollo:
+
+### Prerrequisitos
+
+* Go 1.21+
+
+### 1. Clonar el repositorio
+
+```bash
+git clone https://github.com/tu-org/envguard.git
+cd envguard
+
+```
+
+### 2. Arrancar el Servidor
+
+En una terminal separada:
+
+```bash
+go run cmd/server/main.go
+# Output: 🚦 Lock Server corriendo en :8080
+
+```
+
+### 3. Arrancar el Cliente (TUI)
+
+En otra terminal:
+
+```bash
+# Simula ser un usuario específico mediante variable de entorno
+USER=mi_usuario go run cmd/cli/main.go
+
+```
+
+## 📂 Estructura del Proyecto
+
+```text
+.
+├── cmd/
+│   ├── server/      # Entry point del servidor
+│   │   └── main.go
+│   └── cli/         # Entry point del cliente TUI
+│       └── main.go
+├── internal/
+│   ├── models/      # Estructuras compartidas (Lock, Service)
+│   └── api/         # Cliente HTTP para llamar al servidor
+├── go.mod
+└── README.md
+
+```
+
+## 🎮 Controles
+
+| Tecla | Acción |
+| --- | --- |
+| `↑` / `k` | Subir cursor |
+| `↓` / `j` | Bajar cursor |
+| `Enter` | **Bloquear** (si está libre) o **Liberar** (si es tuyo) |
+| `r` | Forzar refresco de datos |
+| `q` / `Esc` | Salir |
+
+## 🔮 Roadmap
+
+* [x] **v1:** Visualización de estado y bloqueo manual simple.
+* [ ] **v1.1:** Auto-refresco (Polling) cada 2 segundos.
+* [ ] **v1.2:** Notificaciones de escritorio cuando un servicio se libera.
+* [ ] **v2:** Wrapper de ejecución (`envguard run services -- go test ./...`).
+* [ ] **v3:** Integración con CI/CD (Bloqueo automático desde Jenkins/GitHub Actions).
+
+---
+
+### ¿Cómo contribuir?
+
+1. Haz fork del repo.
+2. Instala las dependencias de Charm: `go get github.com/charmbracelet/bubbletea`
+3. Crea una rama `feature/nueva-cosa`.
+4. Haz PR. ¡Evitemos race conditions también en el código! 😉
+
+---
+