From 4f510d1196ba38f8a4fdf0088e6f13742f429524 Mon Sep 17 00:00:00 2001
From: "Rodrigo Rodriguez (Pragmatismo)" <me@rodrigorodriguez.com>
Date: Sun, 5 Apr 2026 19:55:53 -0300
Subject: [PATCH] docs: Update AGENTS.md with bot scripts architecture and
 TOOL_EXEC info

---
 AGENTS.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 2895bdb..4c61e56 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -409,6 +409,60 @@ cd .. && git add botserver && git commit -m "Update botserver: <desc>" && git pu
 - **GIT WORKFLOW** — always push to ALL repositories
 - **0 warnings, 0 errors** — loop until clean
 
+---
+
+## 🔧 Bot Scripts Architecture
+
+### File Types
+| File | Purpose |
+|------|---------|
+| `start.bas` | Entry point, executed on session start |
+| `{tool}.bas` | Tool implementation (e.g., `detecta.bas`) |
+| `tables.bas` | **SPECIAL** - Defines database tables, auto-creates on compile |
+| `init_folha.bas` | Initialization script for specific features |
+
+### tables.bas — SPECIAL FILE
+- **DO NOT call via CALL keyword** - it's processed automatically
+- Parsed at compile time by `process_table_definitions()`
+- Tables are created/updated in database via `sync_bot_tables()`
+- Location: `/opt/gbo/data/{bot}.gbai/{bot}.gbdialog/tables.bas`
+
+### Tool Button Execution (TOOL_EXEC)
+- Frontend sends `message_type: 6` via WebSocket
+- Backend handles in `stream_response()` when `message_type == MessageType::TOOL_EXEC`
+- Tool executes directly, skips KB injection and LLM
+- Result appears in chat (tool output), no "/tool" text shown
+
+### CALL Keyword
+- Can call in-memory procedures OR .bas scripts
+- Syntax: `CALL "script_name"` or `CALL "procedure_name"`
+- If not in memory, looks for `{name}.bas` in bot's gbdialog folder
+
+### DETECT Keyword
+- Analyzes database table for anomalies
+- Requires table to exist (defined in tables.bas)
+- Example: `result = DETECT "folha_salarios"`
+- Calls BotModels API at `/api/anomaly/detect`
+
+### start.bas Execution
+- Executed on WebSocket connect (for web clients)
+- Also on first user message (blocking, once per session)
+- Loads suggestions via `ADD_SUGGESTION_TOOL`
+- Marks session with Redis key to prevent re-run
+
+### MessageType Enum (botlib/src/message_types.rs)
+| ID | Name | Purpose |
+|----|------|---------|
+| 0 | EXTERNAL | External message |
+| 1 | USER | User message |
+| 2 | BOT_RESPONSE | Bot response |
+| 3 | CONTINUE | Continue processing |
+| 4 | SUGGESTION | Suggestion button |
+| 5 | CONTEXT_CHANGE | Context change |
+| 6 | TOOL_EXEC | Direct tool execution (skips KB/LLM) |
+
+**Usage:** When frontend sends `message_type: 6`, backend executes tool directly without going through LLM.
+
 ### 🚨 FUNDAMENTAL: Submodule Push Rule (MANDATORY)
 
 **Every time you push the main repo, you MUST also push ALL submodules!**