pulpo-lib 0.1.0__tar.gz

pulpo_lib-0.1.0/.claude/commands/emergencia.md

@@ -0,0 +1,57 @@
+# /emergencia — Inicializar el sistema de monitoreo Pulpo
+
+Sos el sistema de guardia de Pulpo (Emergencia On Going).
+Ejecutá estos pasos en orden sin pedir confirmación:
+
+## Paso 1 — Chequeo de estado actual
+
+Corré estos dos comandos en paralelo:
+- `curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/bots`
+- `curl -s -o /dev/null -w "%{http_code}" http://localhost:5173`
+
+Interpretación: backend UP = responde cualquier código ≠ "000". Frontend UP = responde 200.
+
+## Paso 2 — Ver últimas líneas del log
+
+```
+tail -10 /Users/josetabuyo/Development/pulpo/_/monitor/backend.log
+```
+
+## Paso 3 — Activar el loop de monitoreo horario
+
+Creá un CronCreate con:
+- cron: `"7 * * * *"` (cada hora a los :07)
+- recurring: true
+- prompt (copiar verbatim):
+
+```
+MONITOREO PULPO — chequeo automático horario. Ejecutar sin pedir confirmación:
+
+1. En paralelo: (a) curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/bots (b) curl -s -o /dev/null -w "%{http_code}" http://localhost:5173
+
+2. Backend DOWN si resultado es "000" o comando falla. Frontend DOWN si resultado no es "200".
+
+3. Si backend DOWN:
+   a. Bash: lsof -i :8000 | grep LISTEN
+   b. Si hay proceso que NO sea Pulpo (uvicorn de /Development/pulpo): Bash: say -v "Paulina" "Atención! El puerto 8000 está ocupado por otra aplicación. Pulpo no puede levantarse."
+   c. Si el puerto está libre o el proceso es Pulpo caído: Bash (desde /Users/josetabuyo/Development/pulpo/_): ./start.sh back
+   d. Bash: sleep 8
+   e. Volver a chequear: curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/bots
+   f. Si sigue DOWN: usar Agent con model="sonnet" con este prompt: "El backend de Pulpo en /Users/josetabuyo/Development/pulpo/_ está caído y no levantó con start.sh. Leé las últimas 60 líneas de monitor/backend.log, identificá la causa raíz y aplicá la corrección mínima necesaria. Si no podés resolverlo, reportá exactamente qué encontraste."
+   g. Bash: say -v "Paulina" "Emergencia! Emergencia! El backend de Pulpo cayó y no pudo recuperarse solo. Requiere atención inmediata."
+
+4. Si frontend DOWN:
+   a. Bash (desde /Users/josetabuyo/Development/pulpo/_): ./start.sh front
+   b. Bash: say -v "Paulina" "Alerta! El frontend de Pulpo estaba caído. Intentando levantar."
+
+5. Si todo OK: no hacer nada, no emitir ningún texto ni mensaje.
+```
+
+## Paso 4 — Reportar al usuario
+
+Mostrar un resumen claro:
+- Backend: UP / DOWN
+- Frontend: UP / DOWN  
+- Últimas líneas relevantes del log (sesiones WA activas)
+- Job ID del cron activo
+- Instrucción: "Para restablecer este sistema en una sesión nueva, usar /emergencia"

pulpo_lib-0.1.0/.env.example

@@ -0,0 +1,16 @@
+# ============================================================
+# PUERTOS DE ESTE AMBIENTE
+# Cada worktree tiene su propio .env con puertos únicos.
+# master (estable): BACKEND_PORT=8000  FRONTEND_PORT=5173
+# dev-1:            BACKEND_PORT=8001  FRONTEND_PORT=5174
+# dev-2:            BACKEND_PORT=8002  FRONTEND_PORT=5175
+# ============================================================
+BACKEND_PORT=8000
+FRONTEND_PORT=5173
+
+# Contraseñas de acceso
+ADMIN_PASSWORD=admin
+CLIENT_PASSWORD=conectar
+
+# Ruta al ejecutable de Chrome (cambiar en Linux)
+# CHROME_PATH=/usr/bin/google-chrome

pulpo_lib-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Management / handoffs — documentos internos, no van al repo
+management/
+
+# Environment
+.env
+
+# Configuración de conexiones (datos sensibles)
+connections.json
+
+# WhatsApp session
+.wwebjs_auth/
+.wwebjs_cache/
+
+# SQLite database
+data/
+
+# Dependencies
+node_modules/
+
+# Logs
+*.log
+npm-debug.log*
+
+# Python
+backend/.venv/
+.venv-pulpo/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+
+# Backups
+connections.json.bak_*
+backend/output/
+
+# Playwright
+.playwright-mcp/
+.playwright-cli/
+backend/.playwright-cli/
+frontend/test-results/
+frontend/playwright-report/
+
+# Monitor logs
+monitor/
+data/summaries/
+node_modules
+
+# macOS
+.DS_Store
+
+# Sesión multi-agente y agente local
+session/
+.agent.json
+.claude/settings.local.json
+
+# Estado local de herramientas
+backend/.node-persist/
+
+# Colecciones Postman exportadas (locales)
+backend/open-wa-*.json

pulpo_lib-0.1.0/CLAUDE.md

@@ -0,0 +1,267 @@
+# Pulpo — Contexto del proyecto
+
+## Forma de trabajar
+- Responder siempre en **español**
+- Para mensajes cortos: hablar via la cola del backend (nunca `say` directo — colisiona con otras voces):
+  ```bash
+  curl -s -X POST http://localhost:8700/queue/speak \
+    -H "Content-Type: application/json" \
+    -d '{"text":"...","voice":"Tessa","family":"Pulpo"}'
+  ```
+- Para código, logs o texto largo: solo texto, sin voz
+- Trabajar un problema a la vez
+
+## Comandos Bash — siempre simples y auditables
+
+**Regla obligatoria:** cada llamada al Bash tool debe hacer **una sola cosa**.
+
+- ✅ `grep "full-sync" backend.log`
+- ✅ `tail -20 backend.log`
+- ✅ `curl -s http://localhost:8000/health`
+- ❌ `grep X | awk | xargs rm` — demasiado en un solo comando
+- ❌ `kill $(ps aux | grep ... | awk ...)` — encadenar kill con subshell es peligroso
+
+**Por qué:** el usuario puede aprobar/rechazar cada comando individualmente.
+Si un comando hace A+B+C en un pipe, no puede aprobar A sin B.
+Comandos simples = auditoría real.
+
+**Cuando necesites encadenar:** pedir aprobación explícita o dividir en pasos separados.
+
+---
+
+## Multi-agente — Haiku y Opus
+
+Al inicio de cada respuesta, chequeá silenciosamente si Haiku u Opus terminaron trabajo pendiente:
+
+```bash
+ls session/haiku-done.flag session/opus-done.flag 2>/dev/null
+```
+
+Si existe algún flag:
+1. Leé el final del outbox correspondiente (`tail -30 session/haiku-outbox.md`)
+2. Eliminá el flag (`rm session/haiku-done.flag`)
+3. Informame brevemente qué encontraron antes de responder mi pregunta
+
+### Delegar a Haiku
+
+Haiku maneja: lectura masiva de archivos, búsquedas, tareas repetitivas, análisis de logs.
+
+```bash
+echo "tu tarea con contexto completo" > session/haiku-inbox.md
+```
+
+El resultado queda en `session/haiku-outbox.md`. Haiku avisa cuando termina con una notificación macOS.
+
+### Consultar a Opus
+
+Opus asesora en decisiones de arquitectura, merges riesgosos, o cuando hay duda sobre impacto en producción.
+
+```bash
+echo "contexto + pregunta preparada" > session/opus-inbox.md
+```
+
+---
+
+## Rol de Claude en este proyecto
+
+Claude en `_` (master) es el **orquestador y guardián de producción**:
+
+1. **Guardián de prod** — protege el servidor en `_`. Nada se toca en producción sin criterio. Sesiones WA son valiosas: nunca `pkill -9`, nunca borrar perfiles Chrome sin confirmación.
+
+2. **Orquestador** — cuando hay una feature nueva, Claude crea el worktree, hace el setup completo y deja un `NEXT_SESSION.md` con el scope detallado para que otra sesión de Claude arranque sola en ese worktree.
+
+3. **Merges y push** — el merge a master y el push a origin los hace **siempre** la sesión de `_`, nunca un worktree.
+
+4. **Documentos de management** — planes, visión, arquitectura, estados van en `management/`. Son la fuente de verdad para planificar worktrees nuevos.
+
+---
+
+## Forma de trabajo: worktrees como ambientes independientes
+
+Cada feature se desarrolla en su propio worktree, que es un servidor completamente independiente:
+
+- **`_` (master)** → producción real. `ENABLE_BOTS=true`. Bots WA y Telegram reales corriendo.
+- **Cualquier otro worktree** → ambiente de desarrollo. `ENABLE_BOTS=false`. Usa **simuladores** para WA y Telegram — no hay browser real, no hay conexiones reales. El pipeline completo (DB, auto_reply, config) funciona igual pero con datos simulados.
+
+Esto permite desarrollar y testear sin arriesgar la sesión de producción ni los bots reales.
+
+### Ciclo de vida de una feature
+
+```
+1. Planificar → crear/actualizar doc en management/
+2. Crear worktree → git worktree add + setup completo + NEXT_SESSION.md
+3. Desarrollar → en la sesión Claude del worktree, modo simulado
+4. Mergear → desde la sesión de _, merge + push a origin
+5. ⚠️ ANTES de eliminar: bajar el backend del worktree → ./stop-backend.sh (desde el directorio del worktree)
+6. Eliminar worktree → git worktree remove --force
+```
+
+> **Por qué el paso 5 es crítico:** un backend activo en un worktree tiene bots WA conectados.
+> Si se elimina el worktree sin bajarlo, el proceso uvicorn queda huérfano corriendo en background,
+> con bots activos que pueden procesar y responder mensajes. Esto ocurrió en producción (incidente abril 2026).
+
+---
+
+## Worktrees — setup obligatorio al crear uno nuevo
+
+### 1. Crear
+```bash
+git worktree add /Users/josetabuyo/Development/pulpo/<rama> -b <rama>
+```
+
+### 2. Symlinks de archivos gitignoreados
+```bash
+WDIR=/Users/josetabuyo/Development/pulpo/<rama>
+ln -s /Users/josetabuyo/Development/pulpo/_/node_modules  $WDIR/node_modules
+ln -s /Users/josetabuyo/Development/pulpo/_/phones.json   $WDIR/phones.json
+# ⚠️  NO linkear data/ — cada worktree tiene su propia data/ aislada
+# El backend la crea automáticamente al arrancar (messages.db vacía, sin sesiones WA reales)
+mkdir -p $WDIR/data
+```
+
+### 3. `.env` con puertos únicos
+```
+BACKEND_PORT=800X
+FRONTEND_PORT=517X
+```
+
+### 4. Crear `NEXT_SESSION.md` con el scope completo para el Claude del worktree
+
+### 5. Puertos asignados
+| Worktree     | Backend | Frontend | Estado       |
+|--------------|---------|----------|--------------|
+| `_` (master) | 8000    | 5173     | Producción   |
+| dev-1        | 8001    | 5174     | Libre        |
+| dev-2        | 8002    | 5175     | Libre        |
+
+---
+
+## Stack actual (Python backend)
+
+- **Backend**: FastAPI + uvicorn (sin `--reload` en producción, con `--reload` en worktrees dev)
+- **Frontend**: React + Vite
+- **DB**: SQLite (`data/messages.db`)
+- **Config**: `phones.json` (gitignoreado)
+- **WhatsApp**: Playwright headless — `launch_persistent_context`, perfil Chrome en `data/sessions/{number}/profile/`
+- **Telegram**: python-telegram-bot, polling
+
+## Archivos clave
+- `backend/main.py` — lifespan, routers, CORS
+- `backend/state.py` — `clients` dict + `wa_session` singleton
+- `backend/automation/whatsapp.py` — lógica WA Web con Playwright
+- `backend/api/` — routers: auth, bots, phones, whatsapp, telegram, messages, sim, client
+- `backend/sim.py` — motor del simulador (activo cuando `ENABLE_BOTS=false`)
+- `frontend/src/pages/DashboardPage.jsx` — dashboard admin
+- `frontend/src/pages/ConnectPage.jsx` — portal del cliente
+- `phones.json` — configuración de bots y teléfonos (GITIGNOREADO)
+- `data/messages.db` — base de datos (auto-creada)
+- `data/sessions/` — perfiles Chrome persistentes por sesión WA
+- `management/` — documentos de planificación y visión
+
+## Scripts y aliases — la única forma correcta de operar el servidor
+
+Todos se corren parados en la raíz del worktree (`_/` para producción).
+**Nunca usar comandos manuales de uvicorn ni matar procesos a mano.**
+
+### Scripts (en disco, ya aprobados)
+```bash
+./start.sh            # levanta back + front
+./start.sh back       # solo backend (si ya corre, no lo reinicia)
+./start.sh front      # solo frontend
+./stop-backend.sh     # detiene el backend con SIGTERM (seguro para WA)
+./restart-backend.sh  # stop + sleep 3 + start back (safe: WA reconnecta sola)
+```
+
+### Aliases en ~/.zshrc (correr desde la raíz del worktree)
+```bash
+start       # alias de ./start.sh
+log_back    # tail -f ./monitor/backend.log
+log_front   # tail -f ./monitor/frontend.log
+qdb "SQL"   # query directo sobre data/messages.db de producción
+```
+
+### ⚠️ Regla de logs
+`log_back` solo muestra logs cuando el servidor fue iniciado vía `./start.sh`
+(que redirige stdout a `monitor/backend.log`).
+Si el servidor se inició a mano en una terminal, los logs van a esa terminal — no al archivo.
+**Siempre arrancar con `./start.sh` para que `log_back` funcione.**
+
+## Flujo de desarrollo — Tests primero
+
+**El orden obligatorio, siempre:**
+1. Correr los tests existentes antes de tocar código (`pytest tests/ -v` + `playwright test`)
+2. Leer el output — los errores describen qué asume el sistema, valen más que leer código en frío
+3. Implementar hasta que los tests pasen
+4. Nunca mergear con tests en rojo
+
+**Tests nuevos:**
+- Lo ideal es seguir TDD: escribir el test antes de implementar
+- Si agregar tests nuevos cuesta más que el cambio (layouts, prototipos, exploración), se pueden omitir en el medio y escribir al terminar el feature
+- Si el cambio rompe un test existente de forma intencional (UI que cambió), actualizarlo es parte del trabajo
+
+## Tests
+
+### Backend (pytest + httpx — requiere server corriendo en :8001 o :8000)
+```bash
+cd backend
+pytest tests/ -v
+```
+Archivos:
+- `tests/test_auth.py` — auth, health, mode
+- `tests/test_logs.py` — endpoint /api/logs/latest, auth, source inválido
+- `tests/test_sim.py`  — simulador: send, log de mensajes, connect/disconnect
+
+### Frontend (Playwright — requiere server corriendo)
+```bash
+cd frontend
+node_modules/.bin/playwright test
+```
+Archivos:
+- `tests/login.spec.cjs`   — login, contraseña incorrecta, dashboard carga
+- `tests/monitor.spec.cjs` — botón Monitor, drawer, log live, filtro, pausa, sim→log
+
+> **Nota:** `pytest` y sus dependencias (`pytest-asyncio`, `httpx`) deben estar instalados en el venv:
+> ```bash
+> .venv/bin/pip install pytest pytest-asyncio httpx
+> ```
+
+## Browsers automatizados — tres usos distintos
+
+Hay tres tipos de browser Playwright/Chromium corriendo en paralelo. **Nunca confundirlos:**
+
+| Tipo | Cómo identificarlo en `ps` | Tocar |
+|------|---------------------------|-------|
+| **playwright-cli** (Claude) | proceso CLI efímero (sin servidor permanente) — `playwright-cli open/close` | ✅ OK cerrar |
+| **WA bots** | Chrome con `--user-data-dir=.../data/sessions/{número}/profile` | ❌ NUNCA |
+| **Tests de UI** | Chrome lanzado por `playwright test` (también `/var/folders/...`) | ✅ OK (solo existen mientras corren tests) |
+
+### Cuando playwright-cli se traba
+playwright-cli es un CLI global — **no hay servidor permanente**. Claude lo usa directamente via Bash: `playwright-cli open`, `playwright-cli goto`, `playwright-cli screenshot`, etc.
+
+Si el browser se traba:
+```bash
+# Cerrar la sesión actual
+playwright-cli close
+
+# Ver todas las sesiones abiertas y cerrarlas
+playwright-cli list
+playwright-cli close-all
+
+# Si hay procesos zombie
+playwright-cli kill-all
+```
+
+Verificar que los WA bots sobrevivieron:
+```bash
+ps aux | grep "data/sessions" | grep -v grep
+```
+
+La clave para distinguir:
+- `playwright-cli` (Claude) → efímero, sin user-data-dir persistente — cerrar OK
+- `.../data/sessions/` → WA bot persistente — NUNCA tocar
+
+## Sesiones WhatsApp — reglas críticas
+- **NUNCA `pkill -9`** en procesos Playwright/Chromium — SIGKILL corrompe el perfil Chrome y pierde la sesión WA
+- Usar solo `pkill` (SIGTERM) para que Chrome guarde limpiamente
+- El perfil persiste en disco — al reiniciar siempre intenta restaurar antes de pedir QR nuevo
+- Nunca borrar `data/sessions/` sin confirmación explícita del usuario

pulpo_lib-0.1.0/NEXT_SESSION.md

@@ -0,0 +1,70 @@
+# NEXT SESSION — Pipeline FB completado
+
+## Estado (sesión 2026-06-24)
+
+Los tres pasos del pipeline FB están completos. No hay deuda pendiente en este tema.
+
+---
+
+### ✅ Paso 1 — Links en respuestas del LLM
+
+**Qué se hizo:**
+- Bug corregido: `_NOTICIAS_SYSTEM` no tenía cierre `"""` → `_AUSPICIANTE_SYSTEM` quedaba embebido
+  como texto y nunca era una variable Python (la rama `auspiciante` tiraba `NameError`).
+- `responder_noticias` ahora arma el contexto con `Link: <url>` antes del texto de cada post.
+- Prompt del LLM actualizado: le indica que cite el link al final de la oración relevante.
+- Error path de `_scrape_post_page` corregido: ahora siempre retorna `{"url": url, ...}`.
+
+**Archivos:**
+- `backend/graphs/luganense.py` — líneas 68, 217, prompt `_NOTICIAS_SYSTEM`
+- `backend/nodes/fetch_facebook.py` — línea 293
+
+---
+
+### ✅ Paso 2 — Límite de contexto
+
+**Resultado:** sin cambios necesarios.
+El modelo es `llama-3.3-70b-versatile` (Groq) con 128k tokens de contexto.
+30 posts × ~600 tokens = ~18k tokens → caben holgado.
+
+---
+
+### ✅ Paso 3 — Cache como read-through (sin LLM)
+
+**Qué se hizo:**
+- `buscar_posts_fb` ahora chequea `fb_cache.get_by_query` antes de scrapear FB.
+- Si la query tiene posts en cache con menos de 24h de antigüedad → los reutiliza, no toca FB.
+- Solo scrapea las queries sin cache hit.
+- `get_by_query` acepta `max_age` (segundos); 0 = sin límite.
+- El dedup semántico es implícito: `expandir_consulta` normaliza las queries
+  ("perdí mi perro" → "perro perdido"), así queries equivalentes reutilizan la misma entrada de cache.
+
+**Archivos:**
+- `backend/nodes/fb_cache.py` — `get_by_query(max_age=)`
+- `backend/graphs/luganense.py` — `buscar_posts_fb` (lógica cache-first)
+
+---
+
+## Tests
+
+```bash
+backend/.venv/bin/pytest backend/tests/test_fb_cache.py -v   # 10/10
+```
+
+## Cómo verificar en vivo
+
+```bash
+# Ver posts cacheados con sus URLs
+qdb "SELECT url, substr(text,1,60) FROM fb_posts WHERE page_id='luganense' LIMIT 10"
+
+# Ver queries guardadas
+qdb "SELECT query, found_at FROM fb_post_queries ORDER BY found_at DESC LIMIT 10"
+
+# Test de scraping real (abre browser visible)
+backend/.venv/bin/python scripts/test_fb_debug.py --visible "perro perdido"
+```
+
+En los logs del backend, el cache hit se ve como:
+```
+[luganense] cache hit 'perro perdido': 12 posts (sin scrapear FB)
+```

pulpo_lib-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: pulpo-lib
+Version: 0.1.0
+Summary: Pulpo — bot orchestration engine with CLI, lib, API, and UI interfaces
+Project-URL: Source, https://github.com/josetabuyo/pulpo
+Author-email: José Tabuyo <josetabuyo@gmail.com>
+License: MIT
+Keywords: automation,bot,cli,telegram,whatsapp,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: google-api-python-client>=2.0.0
+Requires-Dist: google-auth>=2.0.0
+Requires-Dist: greenlet>=3.0.0
+Requires-Dist: groq>=0.11.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: langchain-groq>=1.1.0
+Requires-Dist: langchain-openai>=0.2.0
+Requires-Dist: langgraph>=1.1.0
+Requires-Dist: passlib[bcrypt]>=1.7.4
+Requires-Dist: playwright>=1.49.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Requires-Dist: python-telegram-bot>=21.10.0
+Requires-Dist: slowapi>=0.1.9
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: teli-lib>=0.1.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Requires-Dist: wavi-lib>=0.2.0
+Description-Content-Type: text/markdown
+
+# 🐙 Pulpo
+
+**Automatizá la atención de tu negocio por WhatsApp y Telegram.**
+
+Pulpo conecta tus canales de mensajería a un sistema de bots inteligentes: respuesta automática, historial de conversaciones y gestión desde un portal propio. Sin código, sin complicaciones.
+
+---
+
+## ✨ ¿Qué hace Pulpo?
+
+- **Respuesta automática** — tu bot responde al instante cuando no estás disponible
+- **Multi-canal** — WhatsApp y Telegram desde un solo lugar
+- **Portal de bot** — cada cliente gestiona sus canales, ve conversaciones y responde inline
+- **Panel admin** — control total: agregar bots, ver estado de bots, monitorear en tiempo real
+
+---
+
+## 🚀 Empezar ahora
+
+Accedé al portal público:
+
+**[https://unbuoyant-surgeless-micheal.ngrok-free.dev/bot](https://unbuoyant-surgeless-micheal.ngrok-free.dev/bot)**
+
+- ¿Ya tenés una cuenta? Ingresá con tu clave de bot.
+- ¿Primera vez? → **[Crear bot nueva](https://unbuoyant-surgeless-micheal.ngrok-free.dev/bot/nueva)**
+
+---
+
+## 📲 Conectar Telegram paso a paso
+
+Para agregar un bot de Telegram a tu bot en Pulpo:
+
+### 1. Crear el bot en Telegram
+
+1. Abrí Telegram y buscá **@BotFather**
+2. Enviá `/newbot`
+3. Elegí un nombre para tu bot (ej: `Soporte Herrería`)
+4. Elegí un username (debe terminar en `bot`, ej: `herreria_soporte_bot`)
+5. BotFather te va a dar un **token** con este formato:
+   ```
+   123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
+   ```
+6. Guardalo — lo vas a necesitar en el paso siguiente
+
+### 2. Agregar el bot a Pulpo
+
+1. Entrá a tu portal: [https://unbuoyant-surgeless-micheal.ngrok-free.dev/bot](https://unbuoyant-surgeless-micheal.ngrok-free.dev/bot)
+2. En la sección **Telegram**, pegá el token en el campo y hacé click en **+ Agregar**
+3. Listo — el bot ya está activo y respondiendo
+
+### 3. Activar el bot
+
+Compartí el link de tu bot (`t.me/herreria_soporte_bot`) con tus clientes. Cuando te escriban, Pulpo:
+- Responde automáticamente con tu mensaje configurado
+- Registra la conversación en tu portal
+- Te permite responder manualmente desde el chat inline
+
+---
+
+## 📱 Conectar WhatsApp
+
+1. En la sección **WhatsApp** del portal, ingresá tu número (formato internacional sin `+`, ej: `5491155612767`)
+2. Click en **+ Agregar** → aparece un código QR
+3. En tu WhatsApp móvil: **Dispositivos vinculados → Vincular dispositivo** → escaneá el QR
+4. En 10-20 segundos el estado pasa a **Conectado**
+
+> El bot mantiene la sesión activa. Si se desconecta, podés reconectar desde el portal sin perder el historial.
+
+---
+
+## 🛠️ Stack técnico
+
+| Componente    | Tecnología                                      |
+|---------------|-------------------------------------------------|
+| API REST      | FastAPI + uvicorn                               |
+| Frontend      | React + Vite                                    |
+| Base de datos | SQLite async (`data/messages.db`)               |
+| WhatsApp      | Playwright headless (perfil Chrome persistente) |
+| Telegram      | python-telegram-bot v21                         |
+| Exposición    | ngrok (etapa 1) → Cloudflare Tunnel (etapa 2)  |
+
+---
+
+## ⚡ Desarrollo local
+
+### Requisitos
+
+- Python 3.11+
+- Node 18+
+- `phones.json` con la configuración de bots
+
+### Arrancar
+
+```bash
+./start.sh        # levanta backend (uvicorn) + frontend (vite)
+```
+
+Los puertos se leen del `.env` en la raíz:
+
+```env
+BACKEND_PORT=8000
+FRONTEND_PORT=5173
+ADMIN_PASSWORD=...
+```
+
+### Tests
+
+```bash
+# Backend (requiere server corriendo)
+cd backend
+pytest tests/ -v
+
+# Frontend Playwright (requiere server corriendo)
+cd frontend
+node_modules/.bin/playwright test
+```
+
+---
+
+## 🗂️ Estructura del proyecto
+
+```
+_/
+├── backend/
+│   ├── main.py              # FastAPI app, lifespan, routers
+│   ├── sim.py               # Simulador (activo cuando ENABLE_BOTS=false)
+│   ├── state.py             # clients dict + wa_session singleton
+│   ├── config.py            # lee phones.json
+│   ├── db.py                # SQLite async
+│   ├── api/                 # routers: auth, bots, phones, whatsapp,
+│   │                        #          telegram, messages, sim, bot, logs
+│   ├── automation/
+│   │   └── whatsapp.py      # lógica WA Web con Playwright
+│   ├── bots/
+│   │   └── telegram_bot.py  # bot de Telegram
+│   └── tests/               # pytest: auth, logs, sim
+├── frontend/
+│   ├── src/
+│   │   ├── pages/
+│   │   │   ├── DashboardPage.jsx    # panel admin
+│   │   │   ├── BotPage.jsx      # portal de bot (login + dashboard)
+│   │   │   └── NewBotPage.jsx # onboarding nueva bot
+│   │   └── components/
+│   │       ├── ChatWidget.jsx       # chat inline reutilizable
+│   │       └── MonitorPanel.jsx     # drawer de monitoring en tiempo real
+│   └── tests/               # Playwright: login, monitor
+├── management/              # planes, visión, arquitectura
+├── phones.json              # config de bots y teléfonos (gitignoreado)
+├── data/                    # DB y sesiones Chrome (gitignoreado)
+└── start.sh                 # arranque unificado
+```
+
+---
+
+## 🔀 Worktrees (flujo de desarrollo)
+
+Cada feature se desarrolla en su propio worktree — un servidor independiente con DB propia, sin tocar producción.
+
+| Worktree     | Backend | Frontend | Estado     |
+|--------------|---------|----------|------------|
+| `_` (master) | 8000    | 5173     | Producción |
+| dev-1        | 8001    | 5174     | Libre      |
+| dev-2        | 8002    | 5175     | Libre      |
+
+Ver `CLAUDE.md` para el flujo completo de creación de worktrees, symlinks y setup.
+
+---
+
+## 🗺️ Roadmap
+
+- [x] Bots de WhatsApp (Playwright headless)
+- [x] Bots de Telegram (python-telegram-bot)
+- [x] Respuesta automática configurable por bot
+- [x] Portal de bot — gestión de canales + chat inline
+- [x] Alta de bot nueva (onboarding autogestionable)
+- [x] Panel admin con monitoring en tiempo real
+- [x] Exposición pública via ngrok
+- [ ] Autenticación segura (OAuth / tokens)
+- [ ] Dominio propio + Cloudflare Tunnel
+- [ ] Reconexión automática de sesiones WA