From 0202821faac88e0fd505d86bd94c4f1b9793514a Mon Sep 17 00:00:00 2001
From: admtracksteel <admtracksteel@gmail.com>
Date: Sun, 22 Mar 2026 01:21:14 +0000
Subject: [PATCH] docs: add comprehensive handover documentation

---
 README.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..75aa2ba
--- /dev/null
+++ b/README.md
@@ -0,0 +1,34 @@
+# 🤖 Antigravity VPS Agent - Central de Controle
+
+Este é um Agente de IA avançado para gerenciamento de VPS, projetado para operar tanto via **Telegram** quanto por uma **Interface Web Customizada**. O agente possui acesso root e pode executar comandos shell, ler arquivos e gerenciar o Coolify/Docker.
+
+## 🏗️ Arquitetura Atual (Handover Context)
+
+### 1. Loop ReAct (`ai_agent.py`)
+O "cérebro" do bot usa um loop de raciocínio (Thinking -> Action -> Observation).
+- **IA**: Gemini 2.5 Flash (API Key do Marcos).
+- **Attempts**: Até 10 tentativas por tarefa para resolver problemas complexos sem desistir.
+- **Output**: Separa Logs Técnicos (Terminal) de Resumos Visuais (Painel de Insights) usando as tags `<REFINED>`.
+
+### 2. Interface Web (`templates/index.html`)
+- Painel de 2 colunas: Chat Técnico (esquerda) e Insights Visuais (direita).
+- **Recurso de Áudio**: Implementamos gravação nativa (Web Audio API) com transcrição no backend (STT).
+- **Padrão de Resposta**: Se o usuário fala por áudio, o bot sintetiza (TTS via gTTS) e responde por áudio também (Audio-to-Audio).
+
+### 3. Integração com Infraestrutura
+- **Docker**: O bot roda em container (`vps-ai-agent`) com acesso ao `docker.sock` em modo `rw`.
+- **Gitea**: Repositório de código fonte em `https://git.reifonas.cloud/admtracksteel/BotVPS.git`.
+- **Coolify**: Gerencia aplicações. Os domínios foram recentemente migrados de `reifonas.cloud` para `tracksteel.com.br` (ex: `tscut.tracksteel.com.br`).
+
+### 4. Ferramentas (Tools)
+- `run_bash_command`: Execução de comandos shell.
+- `get_system_health`: CPU, RAM, Disco.
+- `get_docker_stats`: Uso de recursos por container (Especializado para evitar erro de chaves).
+- `read_vps_file`: Leitura de arquivos de log/config.
+
+## 🚀 Como Executar
+Use o script `./start.sh`, que inicia o servidor FastAPI (port 8000) com `--reload` e o processo do Telegram em background.
+
+---
+**Recado para a Próxima Instância do Antigravity:**
+> Marcos utiliza este bot para controle total da VPS. Sempre verifique o `.env` e o `data/config.json` para as credenciais. Mantenha o padrão de resposta visual no painel de insights para facilitar a leitura.