feat: Audit, repair, and stabilize bot architecture

This commit addresses critical issues in the Talia Bot system, including fixing missing admin flows, correcting agenda privacy logic, implementing voice message transcription, and enforcing RAG guardrails.

Key changes include:
- Modified the onboarding module to dynamically generate admin menus from available JSON flows, making all admin functions accessible.
- Updated the agenda module to correctly use separate work and personal Google Calendar IDs, ensuring privacy and accurate availability.
- Implemented audio transcription using the OpenAI Whisper API, replacing placeholder logic and enabling multimodal interaction.
- Reworked the sales RAG module to prevent it from generating generic responses when it lacks sufficient context.

Additionally, this commit introduces comprehensive documentation as requested:
- `AGENTS.md`: Defines the roles and responsibilities of each system agent.
- `Agent_skills.md`: Details the technical capabilities and business rules for each agent.
- `plan_de_pruebas.md`: Provides a step-by-step test plan to verify the fixes.
- `reparacion_vs_refactor.md`: Outlines the immediate repairs performed and proposes a strategic, incremental plan for long-term architectural improvements.

reparacion_vs_refactor.md

@@ -0,0 +1,71 @@
+# Plan de Reparación vs. Refactorización
+
+Este documento distingue entre las reparaciones críticas ya implementadas y propone un plan de refactorización incremental para estabilizar y mejorar la arquitectura del sistema Talia Bot a largo plazo.
+
+---
+
+### Parte 1: Reparaciones Críticas (Ya Implementadas)
+
+Las siguientes acciones se tomaron como medidas de reparación inmediata para solucionar los problemas más urgentes y restaurar la funcionalidad básica.
+
+1.  **Visibilidad de Flujos de Admin**:
+    -   **Fix**: Se modificó `onboarding.py` para generar el menú de administrador de forma dinámica, leyendo los flujos disponibles del `FlowEngine`. Se añadieron las claves `name` y `trigger_button` a los archivos JSON de los flujos para permitir esto.
+    -   **Impacto**: Los administradores ahora pueden ver y acceder a todos los flujos que tienen asignados, incluyendo "Capturar Idea" e "Imprimir Archivo".
+
+2.  **Lógica de Agenda y Privacidad**:
+    -   **Fix**: Se actualizó `agenda.py` para que utilice las variables de entorno `WORK_GOOGLE_CALENDAR_ID` y `PERSONAL_GOOGLE_CALENDAR_ID`.
+    -   **Impacto**: El bot ahora muestra correctamente solo los eventos de la agenda de trabajo del administrador, mientras que trata el tiempo en la agenda personal como bloqueado, protegiendo la privacidad y asegurando que la disponibilidad sea precisa.
+
+3.  **Implementación de Transcripción (Whisper)**:
+    -   **Fix**: Se añadió una función `transcribe_audio` a `llm_engine.py` y se integró en el `text_and_voice_handler` de `main.py`.
+    -   **Impacto**: El bot ya no ignora los mensajes de voz. Ahora puede transcribirlos y usarlos como entrada para los flujos de conversación, sentando las bases para una interacción multimodal completa.
+
+4.  **Guardarraíl del RAG de Ventas**:
+    -   **Fix**: Se eliminó la lógica de fallback en `sales_rag.py`. Si no se encuentran servicios relevantes para la consulta de un cliente, el agente se detiene.
+    -   **Impacto**: El bot ya no genera respuestas de ventas genéricas o irrelevantes. Ahora cumple la regla obligatoria de "sin contexto, no hay respuesta", mejorando la calidad y la fiabilidad de sus interacciones con clientes.
+
+---
+
+### Parte 2: Plan de Refactorización Incremental (Propuesta)
+
+Las reparaciones anteriores han estabilizado el sistema, pero la auditoría reveló debilidades arquitectónicas que deben abordarse para asegurar la mantenibilidad y escalabilidad futuras. Se propone el siguiente plan incremental.
+
+#### Incremento 1: Gestión de Estado y Base de Datos
+
+-   **Problema**: La lógica de la base de datos está dispersa. La persistencia del estado de las aprobaciones es frágil, lo que causa que actividades rechazadas reaparezcan.
+-   **Propuesta**:
+    1.  **Centralizar Acceso a DB**: Crear un gestor de contexto en `db.py` para manejar las conexiones y cursores, asegurando que las conexiones siempre se cierren correctamente.
+    2.  **Refactorizar Aprobaciones**: Rediseñar la lógica en `aprobaciones.py`. Introducir una tabla `activity_proposals` en la base de datos con un campo `status` (ej. `pending`, `approved`, `rejected`).
+    3.  **Implementar DAO (Data Access Object)**: Crear clases o funciones específicas para interactuar con cada tabla (`users`, `conversations`, `activity_proposals`), en lugar de escribir consultas SQL directamente en la lógica de negocio.
+-   **Riesgos**: Mínimos. Este cambio es interno y no debería afectar la experiencia del usuario, pero requiere cuidado para no corromper la base de datos.
+-   **Beneficios**: Solucionará permanentemente el bug de las actividades rechazadas. Hará que el manejo de la base de datos sea más robusto y fácil de mantener.
+
+#### Incremento 2: Abstracción de APIs Externas (Fachada)
+
+-   **Problema**: Las llamadas directas a APIs externas (Google, OpenAI, Vikunja) están mezcladas con la lógica de negocio, lo que hace que el código sea difícil de probar y de cambiar.
+-   **Propuesta**:
+    1.  **Crear un Módulo `clients`**: Dentro de `modules`, crear un nuevo directorio `clients`.
+    2.  **Implementar Clientes API**: Mover toda la lógica de interacción directa con las APIs a clases dedicadas dentro de este nuevo módulo (ej. `google_calendar_client.py`, `openai_client.py`). Estas clases manejarán la autenticación, las solicitudes y el formato de las respuestas.
+    3.  **Actualizar Módulos de Negocio**: Modificar los módulos como `agenda.py` y `llm_engine.py` para que usen estos clientes, en lugar de hacer llamadas directas.
+-   **Riesgos**: Moderados. Requiere refactorizar una parte significativa del código. Se deben realizar pruebas exhaustivas para asegurar que las integraciones no se rompan.
+-   **Beneficios**: Desacopla la lógica de negocio de las implementaciones de las API. Permite cambiar de proveedor (ej. de OpenAI a Gemini) con un impacto mínimo. Facilita enormemente las pruebas unitarias al permitir "mockear" los clientes API.
+
+#### Incremento 3: Sistema de Routing y Comandos Explícito
+
+-   **Problema**: El `button_dispatcher` en `main.py` es un monolito que mezcla lógica de flujos, acciones simples y lógica de aprobación. Es difícil de seguir y propenso a errores a medida que se añaden más botones. El comando `/abracadabra` no funciona porque no hay un sistema claro para registrar comandos "secretos" o de un solo uso.
+-   **Propuesta**:
+    1.  **Registro de Comandos**: Crear un patrón de registro explícito. Cada módulo podría tener una función `register_handlers(application)` que se llama desde `main.py`.
+    2.  **Separar Despachador**: Dividir el `button_dispatcher` en funciones más pequeñas y específicas. Una podría manejar los callbacks de los flujos, otra los de acciones simples, etc.
+    3.  **Implementar `/abracadabra`**: Usando el nuevo sistema de registro, crear un comando simple en `admin.py` para la funcionalidad de `/abracadabra` y registrarlo en `main.py`.
+-   **Riesgos**: Bajos. Los cambios son principalmente organizativos.
+-   **Beneficios**: Mejora radicalmente la legibilidad y mantenibilidad del `main.py`. Crea un sistema claro y escalable para añadir nuevos comandos y botones.
+
+---
+
+### Orden Recomendado
+
+Se recomienda seguir el orden de los incrementos propuestos:
+
+1.  **Gestión de Estado y DB**: Es la base. Un manejo de datos sólido es fundamental para todo lo demás.
+2.  **Abstracción de APIs**: Abordar esto primero hará que el siguiente paso sea más limpio.
+3.  **Sistema de Routing**: Con la lógica de negocio y los datos bien estructurados, refactorizar el enrutamiento será mucho más sencillo.