Update AGENTS.md: add data directory structure and testing tools section

AGENTS.md

@@ -29,6 +29,71 @@
 - **Bot data:** `/opt/gbo/data` (primary)
 - **Test web:** `http://localhost:3000` — Login: `http://localhost:3000/suite/auth/login.html`
 
+### 📦 Data Directory Structure
+
+```
+/opt/gbo/data/                    # Fonte original dos bots (production)
+├── system/
+│   └── work/
+│       └── {botname}.gbai/      # Código fonte .bas
+│           └── {botname}.gbdialog/
+│               └── *.bas         # Scripts BASIC originais
+│
+./botserver-stack/data/system/work/  # Dev local (symlink ou cópia)
+├── {botname}.gbai/
+│   ├── seplagse.gbdialog/       # .bas original
+│   └── seplagse/                 # .gbkb (KB compilado)
+```
+
+**Importante:** O botserver_compila `.bas` → `.ast` em tempo de execução. Arquivos `.ast` são gerados automaticamente.
+
+---
+
+## 🧪 Debugging & Testing Tools
+
+### 🔍 Ver Erros de Execução
+```bash
+tail -f botserver.log | grep -i "error\|tool"
+```
+
+### 🧪 Testar Ferramenta Específica
+
+1. **Identificar o erro no log:**
+   ```bash
+   grep -A5 "Tool error" botserver.log
+   ```
+
+2. **Corrigir o arquivo `.bas` na fonte:**
+   - **Production:** `/opt/gbo/data/system/work/{bot}.gbai/{bot}.gbdialog/{tool}.bas`
+   - **Dev:** `./botserver-stack/data/system/work/{bot}.gbai/{bot}.gbdialog/{tool}.bas`
+
+3. **Forçar recompilação (se necessário):**
+   ```bash
+   rm ./botserver-stack/data/system/work/{bot}.gbai/{bot}.gbdialog/{tool}.ast
+   ```
+
+4. **Testar novamente no browser:**
+   ```
+   http://localhost:3000/{botname}
+   ```
+
+### ⚠️ Erros Comuns em Scripts BASIC
+
+| Erro | Causa | Solução |
+|------|-------|---------|
+| `=== is not a valid operator` | BASIC usa `==`, não `===` | Substituir `===` por `--` em strings |
+| `Syntax error` | Erro de sintaxe BASIC | Verificar parênteses, vírgulas |
+| `Tool execution failed` | Erro no script | Ver logs para stack trace |
+
+### 📝 Exemplo: Corrigir Operador Inválido
+```bas
+# ERRADO (JavaScript syntax):
+PRINT "=== RESULTADO ==="
+
+# CORRETO (BASIC syntax):
+PRINT "-- RESULTADO --"
+```
+
 ---
 
 ## 🧭 LLM Navigation Guide
@@ -167,22 +232,86 @@ CARGO_BUILD_JOBS=1 cargo check -p botserver 2>&1 | tail -200
 
 ---
 
-## 🔄 Reset & Service Management
+## 🔄 Modos de Execução
 
-### reset.sh
+O botserver suporta **dois modos** de execução:
-- Cleans and restarts dev env (3-5 min bootstrap: Vault, PostgreSQL, Valkey, MinIO, Zitadel, LLM)
-- May timeout waiting for Zitadel — check `botserver.log` for "Bootstrap process completed!"
 
-### Verify After Reset
+### Modo 1: Local Standalone (sem Docker/Incus)
-✅ PostgreSQL (5432), ✅ Valkey (6379), ✅ BotServer (8080), ✅ BotUI (3000), ✅ No errors in logs
+
+O botserver sobe **tudo localmente** (PostgreSQL, Valkey, MinIO, Vault, LLM).
+
+```bash
+cd /home/rodriguez/src/gb/botserver
+cargo run -- --install    # Instala dependências (PostgreSQL, Valkey, MinIO, etc.)
+cargo run                 # Sobe tudo e inicia o servidor
+```
+
+**O que acontece:**
+- `PackageManager` baixa e extrai binários para `botserver-stack/bin/`
+- Cria `botserver-stack/data/pgdata/` com PostgreSQL
+- Inicia PostgreSQL na porta 5432
+- Inicia Valkey na porta 6379
+- Inicia MinIO na porta 9100
+- Configura Vault para secrets
+- Baixa modelo LLM (llama.cpp) para detecção de anomalias
+- Ao final: `http://localhost:8080`
+
+**Verificar se está rodando:**
+```bash
+curl http://localhost:8080/health
+curl http://localhost:5432  # PostgreSQL
+curl http://localhost:6379  # Valkey
+```
+
+**Testar com Playwright:**
+```bash
+# Navegar para bot de teste
+npx playwright open http://localhost:3000/salesianos
+# Ou diretamente
+npx playwright open http://localhost:3000/detecta
+```
+
+### Modo 2: Container (Incus) — Produção
+
+Os serviços rodam em containers Incus separados.
+
+```bash
+# Subir todos os containers
+sudo incus start system tables vault directory drive cache llm vector_db
+
+# Verificar status
+sudo incus list
+
+# Acessar container system (onde roda botserver)
+sudo incus exec system -- bash
+
+# Ver logs do botserver
+sudo incus exec system -- journalctl -u botserver -f
+```
+
+**Arquitetura de Containers:**
+
+| Container | Services | Portas |
+|-----------|----------|--------|
+| system | BotServer, Valkey | 8080, 6379 |
+| tables | PostgreSQL | 5432 |
+| vault | Vault | 8200 |
+| directory | Zitadel | 9000 |
+| drive | MinIO | 9100 |
+| cache | Valkey (backup) | 6379 |
+| llm | llama.cpp | 8081 |
+| vector_db | Qdrant | 6333 |
+
+### reset.sh (Ambiente Local)
+```bash
+./reset.sh  # Limpa e reinicia tudo localmente
+```
 
 ### Service Commands
 ```bash
 ps aux | grep -E "(botserver|botui)" | grep -v grep
 curl http://localhost:8080/health
 ./restart.sh                        # Restart services
-systemctl status|start|stop|restart botserver   # systemd management
-journalctl -u botserver -f          # Follow logs
 ```
 
 ---
@@ -244,28 +373,6 @@ cd .. && git add botserver && git commit -m "Update botserver: <desc>" && git pu
 
 ---
 
-## 🐛 Debugging
-
-### Critical Rule
-**STOP on ANY error** — identify → fix root cause → verify → then continue. Never restart to "fix" errors.
-
-### Log Locations
-| Component | Log | Prefix |
-|-----------|-----|--------|
-| botserver | `botserver.log` | — |
-| botui | `botui.log` | — |
-| drive_monitor | botserver logs | `[drive_monitor]` |
-| client errors | botserver logs | `CLIENT:` |
-
-### Bug Fix Flow
-1. Reproduce: `grep -E " E | W " botserver.log | tail -20`
-2. Trace data flow backwards through call chain
-3. Fix minimal change, search for similar occurrences
-4. `cargo check -p botserver` → `./restart.sh` → test → check logs
-5. Commit with clear root cause description
-
----
-
 ## 🧪 Testing
 
 - **Unit:** per-crate `tests/` or `#[cfg(test)]` modules — `cargo test -p <crate>`
@@ -288,26 +395,6 @@ cd .. && git add botserver && git commit -m "Update botserver: <desc>" && git pu
 | system | BotServer + Valkey | 8080/6379 |
 | tables | PostgreSQL | 5432 |
 | vault | Vault | 8200 |
-| directory | Zitadel | 9000 |
-| drive | MinIO | 9100 |
-| cache | Valkey | 6379 |
-| llm | llama.cpp | 8081 |
-| vectordb | Qdrant | 6333 |
-| meet | LiveKit | 7880 |
-| email | Stalwart | 25/587 |
-| alm | Forgejo | **4747** (NOT 3000!) |
-| alm-ci | Forgejo Runner | — |
-| proxy | Caddy | 80/443 |
-
-### Container Management (Incus)
-```bash
-sudo incus list                              # List all
-sudo incus start|stop|restart <container>    # Lifecycle
-sudo incus exec <container> -- bash          # Shell access
-sudo incus exec <container> -- systemctl restart <service>
-sudo incus snapshot create <container> pre-change-$(date +%Y%m%d%H%M%S)
-```
-
 ---
 
 ## 🔑 Core Directives Summary