Refactor: CRM automations, monitoring homepage, webhook examples, docs standards

- Environment Variables: Simplified to ONLY VAULT_* vars, everything else in config.csv - Attendant Module: Added CRM automations (follow-ups, collections/cobranças, scheduling/agendamentos, sales/vendas) - NEW: Hosting, DNS, MDA integration docs (Namecheap, Stalwart, LLM providers) - Monitoring: Updated as live operations homepage with real data endpoints - Examples: Renamed to 'Webhook Integrations and Jobs', removed loop-based examples 1 & 5, added lead nurturing, payment collection, appointment scheduling - Documentation Standards: WhatsApp HTML style as canonical conversation format, SVG for interfaces - Reading Flow: Improved Executive Vision → Quick Start → Chapter 01 transitions with navigation tables
2025-12-03 21:59:49 -03:00 · 2025-12-03 21:59:49 -03:00 · 2110995b7f
commit 2110995b7f
parent 292d6625b7
11 changed files with 1692 additions and 796 deletions
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@ -112,7 +112,7 @@
    - [store.bas](./chapter-06-gbdialog/templates/store.md)
    - [talk-to-data.bas](./chapter-06-gbdialog/templates/talk-to-data.md)
    - [whatsapp.bas](./chapter-06-gbdialog/templates/whatsapp.md)
-  - [Consolidated Examples](./chapter-06-gbdialog/examples-consolidated.md)
+  - [Webhook Integrations and Jobs](./chapter-06-gbdialog/examples-consolidated.md)
  - [Data Sync Tools](./chapter-06-gbdialog/tools-data-sync.md)
  - [Keywords Reference](./chapter-06-gbdialog/keywords.md)
    - [TALK](./chapter-06-gbdialog/keyword-talk.md)
@ -357,6 +357,7 @@
  - [Storage Services](./appendix-external-services/storage.md)
  - [Directory Services](./appendix-external-services/directory.md)
  - [Attendance Queue](./appendix-external-services/attendance-queue.md)
+  - [Hosting, DNS, and MDA](./appendix-external-services/hosting-dns.md)
  - [Time-Series Database](./appendix-external-services/timeseries.md)
  - [NVIDIA GPU](./appendix-external-services/nvidia.md)
  - [Multimodal](./appendix-external-services/multimodal.md)
@ -365,6 +366,7 @@
 - [Appendix C: Environment Variables](./appendix-env-vars/README.md)

 - [Appendix D: Documentation Style](./appendix-docs-style/conversation-examples.md)
+  - [SVG and Conversation Standards](./appendix-docs-style/svg.md)

 [Glossary](./glossary.md)
 [Contact](./contact/README.md)
--- a/src/appendix-docs-style/svg.md
+++ b/src/appendix-docs-style/svg.md
@ -0,0 +1,191 @@
+# Documentation Style Standards
+
+All interface layouts in this documentation use SVG-based wireframe representations for screenshots and diagrams. Conversation examples use the WhatsApp-style HTML format for consistent, visually appealing rendering.
+
+---
+
+## Interface Wireframes (SVG)
+
+All interface screenshots and layouts should use SVG wireframes located in `/assets/`.
+
+### Directory Structure
+
+```
+assets/
+├── suite/
+│   ├── chat-screen.svg
+│   ├── drive-screen.svg
+│   ├── calendar-screen.svg
+│   ├── mail-screen.svg
+│   ├── tasks-screen.svg
+│   ├── meet-screen.svg
+│   ├── live-monitoring-organism.svg
+│   └── ...
+├── chapter-01/
+│   ├── bootstrap-process.svg
+│   └── session-states.svg
+└── chapter-04/
+    └── analytics-interface.svg
+```
+
+### Referencing SVG Wireframes
+
+Use standard HTML image syntax with responsive styling:
+
+```html
+<img src="../assets/suite/chat-screen.svg" alt="Chat Interface" style="max-width: 100%; height: auto;">
+```
+
+---
+
+## Conversation Examples (WhatsApp Style)
+
+All conversation examples throughout the book use the WhatsApp-style HTML format. This provides a familiar, visually consistent representation of bot interactions.
+
+### Standard Format
+
+```html
+<div class="wa-chat">
+  <div class="wa-message user">
+    <div class="wa-bubble">
+      <p>User message goes here</p>
+      <div class="wa-time">10:30</div>
+    </div>
+  </div>
+  <div class="wa-message bot">
+    <div class="wa-bubble">
+      <p>Bot response goes here</p>
+      <div class="wa-time">10:30</div>
+    </div>
+  </div>
+</div>
+```
+
+### Complete Example
+
+```html
+<div class="wa-chat">
+  <div class="wa-message bot">
+    <div class="wa-bubble">
+      <p>Hello! How can I help you today?</p>
+      <div class="wa-time">10:30</div>
+    </div>
+  </div>
+  <div class="wa-message user">
+    <div class="wa-bubble">
+      <p>I want to enroll in computer science</p>
+      <div class="wa-time">10:31</div>
+    </div>
+  </div>
+  <div class="wa-message bot">
+    <div class="wa-bubble">
+      <p>I'll help you enroll! What's your name?</p>
+      <div class="wa-time">10:31</div>
+    </div>
+  </div>
+  <div class="wa-message user">
+    <div class="wa-bubble">
+      <p>Sarah Chen</p>
+      <div class="wa-time">10:31</div>
+    </div>
+  </div>
+  <div class="wa-message bot">
+    <div class="wa-bubble">
+      <p>✅ Welcome to Computer Science, Sarah!</p>
+      <p>Your enrollment ID is: ENR-2025-0142</p>
+      <div class="wa-time">10:31</div>
+    </div>
+  </div>
+</div>
+```
+
+### Message Classes
+
+| Class | Usage |
+|-------|-------|
+| `wa-chat` | Container for the conversation |
+| `wa-message` | Individual message wrapper |
+| `wa-message user` | User message (right-aligned, colored) |
+| `wa-message bot` | Bot message (left-aligned) |
+| `wa-bubble` | Message bubble with styling |
+| `wa-time` | Timestamp display |
+
+### Formatting Guidelines
+
+1. **User messages** — Use `wa-message user` class
+2. **Bot messages** — Use `wa-message bot` class
+3. **Timestamps** — Include `wa-time` div with realistic times
+4. **Multi-line responses** — Use separate `<p>` tags for each line
+5. **Emojis** — Use sparingly for status indicators (✅, ❌, 📧, 📅, 📁)
+6. **Bold text** — Use `<strong>` for emphasis
+7. **Attachments** — Indicate with 📎 emoji and filename
+
+### File Attachments Example
+
+```html
+<div class="wa-chat">
+  <div class="wa-message user">
+    <div class="wa-bubble">
+      <p>Upload the quarterly report</p>
+      <p>📎 Q4-Report.pdf</p>
+      <div class="wa-time">10:30</div>
+    </div>
+  </div>
+  <div class="wa-message bot">
+    <div class="wa-bubble">
+      <p>✅ File uploaded successfully!</p>
+      <p>📄 Q4-Report.pdf (2.4 MB)</p>
+      <p>📁 Saved to: My Drive</p>
+      <div class="wa-time">10:30</div>
+    </div>
+  </div>
+</div>
+```
+
+---
+
+## CSS Styling
+
+The WhatsApp chat styling is defined in `whatsapp-chat.css` and automatically included in the book build. The styles provide:
+
+- Familiar messaging app appearance
+- Proper alignment (user right, bot left)
+- Bubble styling with shadows
+- Responsive layout
+- Timestamp formatting
+
+---
+
+## When to Use Each Format
+
+| Content Type | Format |
+|--------------|--------|
+| Interface screenshots | SVG wireframe |
+| System architecture | SVG diagram |
+| Data flow diagrams | SVG diagram |
+| Bot conversations | WhatsApp HTML |
+| API examples | Code blocks |
+| Configuration | Code blocks |
+
+---
+
+## Global Conversation Style Reference
+
+For all conversation examples throughout the book, follow the format established in:
+
+**[BASIC vs Automation Tools](../chapter-06-gbdialog/basic-vs-automation-tools.md)**
+
+This document serves as the canonical reference for:
+
+- Conversation formatting
+- Multi-channel message representation
+- Bot response styling
+- User input examples
+
+---
+
+## See Also
+
+- [Conversation Examples](./conversation-examples.md) — Example patterns
+- [BASIC vs Automation Tools](../chapter-06-gbdialog/basic-vs-automation-tools.md) — Canonical conversation style
+- [Chapter 04 Apps](../chapter-04-gbui/apps/README.md) — Interface documentation
--- a/src/appendix-env-vars/README.md
+++ b/src/appendix-env-vars/README.md
@ -1,14 +1,10 @@
 # Appendix C: Environment Variables

-General Bots uses a minimal set of environment variables. All configuration is managed through `config.csv` files within each bot's `.gbot` folder, with secrets stored securely in Vault.
+General Bots uses a **minimal set of environment variables**. All configuration is managed through `config.csv` files within each bot's `.gbot` folder, with secrets stored securely in Vault.

 ## Required Environment Variables

-Only Vault-related environment variables are used by General Bots:
-
-### VAULT_* Variables
-
-**Purpose**: HashiCorp Vault integration for secure secrets management.
+Only Vault-related environment variables are required by General Bots:

 | Variable | Description | Example |
 |----------|-------------|---------|
@ -16,63 +12,18 @@ Only Vault-related environment variables are used by General Bots:
 | `VAULT_TOKEN` | Authentication token | Auto-generated during bootstrap |
 | `VAULT_NAMESPACE` | Vault namespace (optional) | `admin` |

-**Example**:
-```bash
-VAULT_ADDR=http://localhost:8200
-VAULT_TOKEN=hvs.your-vault-token
-```
-
-## Auto-Managed Services
-
-The following services are automatically configured through Vault:
-
-| Service | Management |
-|---------|------------|
-| PostgreSQL | Connection credentials in Vault |
-| S3-Compatible Storage | Access keys in Vault |
-| Cache | Connection managed via Vault |
-| Email (Stalwart) | Credentials in Vault |
-| LLM API Keys | Stored in Vault |
-
-You do **not** need to set environment variables for these services. Vault handles credential distribution and rotation automatically.
-
-## What NOT to Use Environment Variables For
-
-**All application configuration belongs in `config.csv`**:
-
-| Configuration | Where to Configure |
-|--------------|-------------------|
-| Database connection | Managed by Vault |
-| Storage credentials | Managed by Vault |
-| LLM API keys | Managed by Vault |
-| LLM provider | `config.csv`: `llm-url` |
-| Email settings | `config.csv`: `email-*` |
-| Channel tokens | `config.csv`: `whatsapp-*`, etc. |
-| Bot settings | `config.csv`: all bot-specific settings |
-| Feature flags | `config.csv`: various keys |
-
-## Configuration Philosophy
-
-General Bots follows these principles:
-
-1. **Vault-First**: All secrets are managed by Vault
-2. **Minimal Environment**: Only Vault address and token use environment variables
-3. **config.csv for Settings**: All application configuration is in `config.csv`
-4. **Per-Bot Configuration**: Each bot has its own `config.csv` in its `.gbot` folder
-5. **No Hardcoded Secrets**: Never store secrets in code or config files
-
 ## Setting Environment Variables

 ### Linux/macOS

-```bash
+```botbook/src/appendix-env-vars/example.sh#L1-2
 export VAULT_ADDR=http://localhost:8200
 export VAULT_TOKEN=hvs.your-vault-token
 ```

 ### Systemd Service

-```ini
+```botbook/src/appendix-env-vars/example.service#L1-3
 [Service]
 Environment="VAULT_ADDR=http://localhost:8200"
 Environment="VAULT_TOKEN=hvs.your-vault-token"
@ -80,31 +31,79 @@ Environment="VAULT_TOKEN=hvs.your-vault-token"

 ### LXC Container

-When using LXC deployment, environment variables are set in the container configuration:
-
-```bash
+```botbook/src/appendix-env-vars/example-lxc.sh#L1-2
 lxc config set container-name environment.VAULT_ADDR="http://localhost:8200"
 lxc config set container-name environment.VAULT_TOKEN="hvs.your-vault-token"
 ```

-## Security Notes
+## Auto-Managed Services

-1. **Never commit tokens**: Use `.env` files (gitignored) or secrets management
-2. **Rotate regularly**: Vault tokens should be rotated periodically
-3. **Limit access**: Only the botserver process needs these variables
-4. **Use TLS**: Always use HTTPS for Vault in production
+The following services are **automatically configured through Vault** during bootstrap:
+
+| Service | Management |
+|---------|------------|
+| PostgreSQL | Connection credentials stored in Vault |
+| S3-Compatible Storage | Access keys stored in Vault |
+| Cache | Connection managed via Vault |
+| Email (Stalwart) | Credentials stored in Vault |
+| LLM API Keys | Stored in Vault |
+
+You do **not** need environment variables for these services. Vault handles credential distribution and rotation automatically.
+
+## Everything Else Goes in config.csv
+
+**All application configuration belongs in `config.csv`**, not environment variables:
+
+| Configuration | Where to Configure |
+|--------------|-------------------|
+| LLM provider/model | `config.csv`: `llm-url`, `llm-model` |
+| Email settings | `config.csv`: `email-*` |
+| Channel tokens | `config.csv`: `whatsapp-*`, `telegram-*`, etc. |
+| Bot settings | `config.csv`: all bot-specific settings |
+| Feature flags | `config.csv`: various keys |
+| Theme settings | `config.csv`: `theme-*` |
+| Server port | `config.csv`: `server_port` |
+
+### Example config.csv
+
+```botbook/src/appendix-env-vars/example-config.csv#L1-8
+name,value
+llm-url,http://localhost:8081
+llm-model,model.gguf
+server_port,8080
+theme-color1,#0d2b55
+whatsapp-business-id,your-business-id
+admin-email,admin@example.com
+```
+
+## Configuration Philosophy
+
+General Bots follows these principles:
+
+1. **Vault-First** — All secrets are managed by Vault
+2. **Minimal Environment** — Only Vault address and token use environment variables
+3. **config.csv for Settings** — All application configuration is in `config.csv`
+4. **Per-Bot Configuration** — Each bot has its own `config.csv` in its `.gbot` folder
+5. **No Hardcoded Secrets** — Never store secrets in code or config files

 ## Bootstrap Process

 During bootstrap, General Bots:

 1. Connects to Vault using `VAULT_*` variables
-2. Retrieves credentials for all managed services
+2. Retrieves or generates credentials for all managed services
 3. Configures database, storage, cache, and other services
-4. Stores service endpoints securely
+4. Stores service credentials securely in Vault

 This eliminates the need for manual credential management.

+## Security Notes
+
+1. **Never commit tokens** — Use `.env` files (gitignored) or secrets management
+2. **Rotate regularly** — Vault tokens should be rotated periodically
+3. **Limit access** — Only the botserver process needs these variables
+4. **Use TLS** — Always use HTTPS for Vault in production
+
 ## Troubleshooting

 ### Vault Connection Failed
@ -124,13 +123,13 @@ Verify:
 If a managed service (database, storage, cache) is unavailable:

 1. Check Vault is running and unsealed
-2. Verify secrets exist in Vault
+2. Verify secrets exist in Vault at expected paths
 3. Check service container/process status
 4. Review logs for connection errors

 ## See Also

- [config.csv Format](../chapter-08-config/config-csv.md) - Bot configuration
- [Secrets Management](../chapter-08-config/secrets-management.md) - Vault integration details
- [Drive Integration](../chapter-08-config/drive.md) - Storage setup
- [Authentication](../chapter-12-auth/README.md) - Security features
+- [config.csv Format](../chapter-08-config/config-csv.md) — Bot configuration reference
+- [Secrets Management](../chapter-08-config/secrets-management.md) — Vault integration details
+- [Drive Integration](../chapter-08-config/drive.md) — Storage setup
+- [Authentication](../chapter-12-auth/README.md) — Security features
--- a/src/appendix-external-services/attendance-queue.md
+++ b/src/appendix-external-services/attendance-queue.md
@ -1,22 +1,27 @@
 # Attendance Queue Module

-Human-attendant queue management for hybrid bot/human support workflows.
+Human-attendant queue management for hybrid bot/human support workflows, plus CRM automations for follow-ups, collections, scheduling, and sales.

 ## Overview

-The attendance queue module manages handoffs from bot to human agents, tracking conversation queues, attendant availability, and real-time assignment.
+The attendance queue module manages handoffs from bot to human agents, tracking conversation queues, attendant availability, and real-time assignment. It also provides automated CRM workflows that run without human intervention.
+
+---

 ## Configuration

 Create `attendant.csv` in your bot's `.gbai` folder:

 ```csv
-id,name,channel,preferences
-att-001,John Smith,whatsapp,sales
-att-002,Jane Doe,web,support
-att-003,Bob Wilson,all,technical
+id,name,channel,preferences,department
+att-001,John Smith,whatsapp,sales,commercial
+att-002,Jane Doe,web,support,customer-service
+att-003,Bob Wilson,all,technical,engineering
+att-004,Maria Santos,whatsapp,collections,finance
 ```

+---
+
 ## Queue Status

 | Status | Description |
@ -36,12 +41,298 @@ att-003,Bob Wilson,all,technical
 | `away` | Temporarily unavailable |
 | `offline` | Not working |

+---
+
+## CRM Automations
+
+The attendant module includes built-in CRM automations that handle common business workflows automatically.
+
+### Follow-Up Automation
+
+Automated follow-up sequences for leads and customers.
+
+```basic
+' follow-up.bas
+' Automated follow-up workflow
+
+SET SCHEDULE "follow-ups", "0 9 * * 1-5"
+
+' Find leads needing follow-up
+leads_1_day = FIND "leads", "status='new' AND DATEDIFF(NOW(), last_contact) = 1"
+leads_3_day = FIND "leads", "status='contacted' AND DATEDIFF(NOW(), last_contact) = 3"
+leads_7_day = FIND "leads", "status='contacted' AND DATEDIFF(NOW(), last_contact) = 7"
+
+' 1-day follow-up: Thank you message
+FOR EACH lead IN leads_1_day
+    SEND TEMPLATE lead.phone, "follow_up_thanks", lead.name, lead.interest
+    UPDATE "leads", "id=" + lead.id, "contacted", NOW()
+    INSERT "activities", lead.id, "follow_up", "1-day thank you sent", NOW()
+NEXT lead
+
+' 3-day follow-up: Value proposition
+FOR EACH lead IN leads_3_day
+    SEND TEMPLATE lead.phone, "follow_up_value", lead.name, lead.interest
+    UPDATE "leads", "id=" + lead.id, "nurturing", NOW()
+    INSERT "activities", lead.id, "follow_up", "3-day value prop sent", NOW()
+NEXT lead
+
+' 7-day follow-up: Special offer
+FOR EACH lead IN leads_7_day
+    SEND TEMPLATE lead.phone, "follow_up_offer", lead.name, "10%"
+    UPDATE "leads", "id=" + lead.id, "offer_sent", NOW()
+    INSERT "activities", lead.id, "follow_up", "7-day offer sent", NOW()
+    
+    ' Alert sales team for hot leads
+    IF lead.score >= 70 THEN
+        attendant = FIND "attendants", "department='commercial' AND status='online'"
+        IF attendant THEN
+            SEND MAIL attendant.email, "Hot Lead Follow-up: " + lead.name, "Lead " + lead.name + " received 7-day offer. Score: " + lead.score
+        END IF
+    END IF
+NEXT lead
+
+PRINT "Follow-ups completed: " + UBOUND(leads_1_day) + " 1-day, " + UBOUND(leads_3_day) + " 3-day, " + UBOUND(leads_7_day) + " 7-day"
+```
+
+### Collections Automation (Cobranças)
+
+Automated payment reminders and collection workflow.
+
+```basic
+' collections.bas
+' Automated payment collection workflow
+
+SET SCHEDULE "collections", "0 8 * * 1-5"
+
+' Find overdue invoices by age
+due_today = FIND "invoices", "status='pending' AND due_date = CURDATE()"
+overdue_3 = FIND "invoices", "status='pending' AND DATEDIFF(NOW(), due_date) = 3"
+overdue_7 = FIND "invoices", "status='pending' AND DATEDIFF(NOW(), due_date) = 7"
+overdue_15 = FIND "invoices", "status='pending' AND DATEDIFF(NOW(), due_date) = 15"
+overdue_30 = FIND "invoices", "status='pending' AND DATEDIFF(NOW(), due_date) >= 30"
+
+' Due today: Friendly reminder via WhatsApp
+FOR EACH invoice IN due_today
+    customer = FIND "customers", "id=" + invoice.customer_id
+    SEND TEMPLATE customer.phone, "payment_due_today", customer.name, invoice.id, invoice.amount
+    INSERT "collection_log", invoice.id, "reminder_due_today", NOW()
+NEXT invoice
+
+' 3 days overdue: First collection notice
+FOR EACH invoice IN overdue_3
+    customer = FIND "customers", "id=" + invoice.customer_id
+    SEND TEMPLATE customer.phone, "payment_overdue_3", customer.name, invoice.id, invoice.amount
+    SEND MAIL customer.email, "Pagamento Pendente - Fatura #" + invoice.id, "Sua fatura está vencida há 3 dias. Valor: R$ " + invoice.amount
+    UPDATE "invoices", "id=" + invoice.id, "first_notice_sent", NOW()
+    INSERT "collection_log", invoice.id, "first_notice", NOW()
+NEXT invoice
+
+' 7 days overdue: Second notice with urgency
+FOR EACH invoice IN overdue_7
+    customer = FIND "customers", "id=" + invoice.customer_id
+    SEND TEMPLATE customer.phone, "payment_overdue_7", customer.name, invoice.id, invoice.amount
+    UPDATE "invoices", "id=" + invoice.id, "second_notice_sent", NOW()
+    INSERT "collection_log", invoice.id, "second_notice", NOW()
+    
+    ' Notify collections team
+    SEND MAIL "cobranca@empresa.com", "Cobrança 7 dias: " + customer.name, "Cliente: " + customer.name + "\nFatura: " + invoice.id + "\nValor: R$ " + invoice.amount
+NEXT invoice
+
+' 15 days overdue: Final notice before action
+FOR EACH invoice IN overdue_15
+    customer = FIND "customers", "id=" + invoice.customer_id
+    late_fee = invoice.amount * 0.02
+    interest = invoice.amount * 0.01 * 15
+    total_due = invoice.amount + late_fee + interest
+    
+    SEND TEMPLATE customer.phone, "payment_final_notice", customer.name, invoice.id, total_due
+    UPDATE "invoices", "id=" + invoice.id, late_fee, interest, total_due, "final_notice_sent", NOW()
+    INSERT "collection_log", invoice.id, "final_notice", NOW()
+    
+    ' Assign to human attendant for follow-up call
+    attendant = FIND "attendants", "department='finance' AND status='online'"
+    IF attendant THEN
+        INSERT "queue", invoice.customer_id, attendant.id, "collection_call", "high", NOW()
+    END IF
+NEXT invoice
+
+' 30+ days overdue: Escalate to collections
+FOR EACH invoice IN overdue_30
+    IF invoice.status <> "collections" THEN
+        customer = FIND "customers", "id=" + invoice.customer_id
+        UPDATE "invoices", "id=" + invoice.id, "collections", NOW()
+        UPDATE "customers", "id=" + customer.id, "suspended"
+        
+        SEND MAIL "juridico@empresa.com", "Inadimplência 30+ dias: " + customer.name, "Cliente enviado para cobrança jurídica.\n\nCliente: " + customer.name + "\nFatura: " + invoice.id + "\nValor total: R$ " + invoice.total_due
+        INSERT "collection_log", invoice.id, "sent_to_collections", NOW()
+    END IF
+NEXT invoice
+
+PRINT "Collections processed: " + UBOUND(due_today) + " due today, " + UBOUND(overdue_30) + " sent to collections"
+```
+
+### Scheduling Automation (Agendamentos)
+
+Automated appointment scheduling and reminders.
+
+```basic
+' scheduling.bas
+' Automated appointment scheduling and reminders
+
+SET SCHEDULE "appointment-reminders", "0 7 * * *"
+
+' Find appointments for today and tomorrow
+today_appointments = FIND "appointments", "DATE(scheduled_at) = CURDATE() AND status='confirmed'"
+tomorrow_appointments = FIND "appointments", "DATE(scheduled_at) = DATE_ADD(CURDATE(), INTERVAL 1 DAY) AND status='confirmed'"
+
+' Send day-before reminders
+FOR EACH appt IN tomorrow_appointments
+    customer = FIND "customers", "id=" + appt.customer_id
+    staff = FIND "staff", "id=" + appt.staff_id
+    
+    appt_time = FORMAT(appt.scheduled_at, "HH:mm")
+    appt_date = FORMAT(appt.scheduled_at, "DD/MM/YYYY")
+    
+    SEND TEMPLATE customer.phone, "appointment_reminder_24h", customer.name, appt.service, appt_date, appt_time, staff.name
+    UPDATE "appointments", "id=" + appt.id, "reminder_24h_sent", NOW()
+NEXT appt
+
+' Send same-day reminders (2 hours before)
+FOR EACH appt IN today_appointments
+    IF DATEDIFF_HOURS(appt.scheduled_at, NOW()) <= 2 AND appt.reminder_2h_sent IS NULL THEN
+        customer = FIND "customers", "id=" + appt.customer_id
+        staff = FIND "staff", "id=" + appt.staff_id
+        
+        appt_time = FORMAT(appt.scheduled_at, "HH:mm")
+        
+        SEND TEMPLATE customer.phone, "appointment_reminder_2h", customer.name, appt.service, appt_time
+        UPDATE "appointments", "id=" + appt.id, "reminder_2h_sent", NOW()
+        
+        ' Notify staff
+        SEND TEMPLATE staff.phone, "staff_appointment_alert", staff.name, customer.name, appt.service, appt_time
+    END IF
+NEXT appt
+
+' Check for no-shows (30 min past appointment time)
+past_appointments = FIND "appointments", "scheduled_at < DATE_SUB(NOW(), INTERVAL 30 MINUTE) AND status='confirmed'"
+FOR EACH appt IN past_appointments
+    customer = FIND "customers", "id=" + appt.customer_id
+    UPDATE "appointments", "id=" + appt.id, "no_show"
+    INSERT "activities", appt.customer_id, "no_show", "Missed appointment: " + appt.service, NOW()
+    
+    ' Send reschedule offer
+    SEND TEMPLATE customer.phone, "missed_appointment", customer.name, appt.service
+NEXT appt
+
+PRINT "Reminders sent: " + UBOUND(tomorrow_appointments) + " for tomorrow, " + UBOUND(today_appointments) + " for today"
+```
+
+### Sales Automation (Vendas)
+
+Automated sales pipeline and lead scoring.
+
+```basic
+' sales-automation.bas
+' Automated sales pipeline management
+
+SET SCHEDULE "sales-automation", "0 8,14,18 * * 1-5"
+
+' Score and prioritize leads
+new_leads = FIND "leads", "score IS NULL OR score = 0"
+FOR EACH lead IN new_leads
+    score = 0
+    
+    ' Score based on source
+    IF lead.source = "website" THEN score = score + 20
+    IF lead.source = "referral" THEN score = score + 30
+    IF lead.source = "campaign" THEN score = score + 15
+    
+    ' Score based on company size
+    IF lead.company_size = "enterprise" THEN score = score + 25
+    IF lead.company_size = "mid-market" THEN score = score + 20
+    IF lead.company_size = "small" THEN score = score + 10
+    
+    ' Score based on engagement
+    page_views = FIND "analytics", "lead_id=" + lead.id + " AND type='page_view'"
+    score = score + MIN(UBOUND(page_views) * 2, 20)
+    
+    ' Score based on email opens
+    email_opens = FIND "email_tracking", "lead_id=" + lead.id + " AND opened=true"
+    score = score + MIN(UBOUND(email_opens) * 5, 25)
+    
+    UPDATE "leads", "id=" + lead.id, score, NOW()
+NEXT lead
+
+' Auto-assign hot leads to sales reps
+hot_leads = FIND "leads", "score >= 70 AND assigned_to IS NULL"
+FOR EACH lead IN hot_leads
+    ' Round-robin assignment
+    available_reps = FIND "attendants", "department='commercial' AND status='online'"
+    IF UBOUND(available_reps) > 0 THEN
+        ' Get rep with fewest active leads
+        rep = available_reps[0]
+        min_leads = 999
+        FOR EACH r IN available_reps
+            rep_leads = FIND "leads", "assigned_to='" + r.id + "' AND status NOT IN ('converted', 'lost')"
+            IF UBOUND(rep_leads) < min_leads THEN
+                min_leads = UBOUND(rep_leads)
+                rep = r
+            END IF
+        NEXT r
+        
+        UPDATE "leads", "id=" + lead.id, rep.id, NOW()
+        
+        ' Notify sales rep via WhatsApp
+        SEND TEMPLATE rep.phone, "new_hot_lead", rep.name, lead.name, lead.company, lead.score
+        
+        ' Create follow-up task
+        CREATE TASK "Contact hot lead: " + lead.name, rep.email, NOW()
+    END IF
+NEXT lead
+
+' Move stale opportunities
+stale_opportunities = FIND "opportunities", "DATEDIFF(NOW(), last_activity) > 14 AND stage NOT IN ('closed_won', 'closed_lost')"
+FOR EACH opp IN stale_opportunities
+    owner = FIND "attendants", "id=" + opp.owner_id
+    
+    ' Send reminder to owner
+    SEND TEMPLATE owner.phone, "stale_opportunity", owner.name, opp.name, opp.amount, DATEDIFF(NOW(), opp.last_activity)
+    
+    ' Create urgent task
+    CREATE TASK "URGENT: Update stale opportunity - " + opp.name, owner.email, NOW()
+    
+    INSERT "activities", opp.id, "stale_alert", "Opportunity marked as stale", NOW()
+NEXT opp
+
+' Generate daily pipeline report
+pipeline = FIND "opportunities", "stage NOT IN ('closed_won', 'closed_lost')"
+total_value = AGGREGATE "SUM", pipeline, "amount"
+weighted_value = 0
+FOR EACH opp IN pipeline
+    weighted_value = weighted_value + (opp.amount * opp.probability / 100)
+NEXT opp
+
+report = "📊 Pipeline Diário\n\n"
+report = report + "Total Pipeline: R$ " + FORMAT(total_value, "#,##0.00") + "\n"
+report = report + "Valor Ponderado: R$ " + FORMAT(weighted_value, "#,##0.00") + "\n"
+report = report + "Oportunidades Ativas: " + UBOUND(pipeline) + "\n"
+report = report + "Leads Quentes: " + UBOUND(hot_leads)
+
+SEND MAIL "vendas@empresa.com", "Pipeline Diário - " + FORMAT(NOW(), "DD/MM/YYYY"), report
+
+PRINT "Sales automation completed. Hot leads assigned: " + UBOUND(hot_leads)
+```
+
+---
+
 ## REST API Endpoints

-### GET /api/queue
+### Queue Management
+
+#### GET /api/queue
 List conversations in queue.

-### POST /api/queue/assign
+#### POST /api/queue/assign
 Assign conversation to attendant.

 ```json
@ -51,7 +342,7 @@ Assign conversation to attendant.
 }
 ```

-### POST /api/queue/transfer
+#### POST /api/queue/transfer
 Transfer conversation between attendants.

 ```json
@ -63,16 +354,95 @@ Transfer conversation between attendants.
 }
 ```

-### GET /api/attendants
+### Attendant Management
+
+#### GET /api/attendants
 List all attendants with stats.

+#### PUT /api/attendants/{id}/status
+Update attendant status.
+
+```json
+{
+    "status": "online"
+}
+```
+
+### CRM Automation
+
+#### GET /api/automation/status
+Check automation job status.
+
+#### POST /api/automation/trigger/{job_name}
+Manually trigger an automation job.
+
+---
+
 ## BASIC Keywords

+### Transfer to Human
+
 ```basic
+' Transfer to any available human
+TRANSFER TO HUMAN
+
+' Transfer to specific department
 TRANSFER TO HUMAN "sales"
+
+' Transfer with priority
 TRANSFER TO HUMAN "support", "high"
+
+' Transfer with context
+TRANSFER TO HUMAN "technical", "normal", "Customer needs help with API integration"
 ```

+### Create Lead
+
+```basic
+' Create lead from conversation
+CREATE LEAD name, email, phone, source
+
+' Create lead with company info
+CREATE LEAD name, email, phone, "website", company, "enterprise"
+```
+
+### Schedule Appointment
+
+```basic
+' Schedule appointment
+BOOK customer_email, service, date, time, staff_id
+
+' Schedule with duration
+BOOK customer_email, "Consultation", "2025-01-20", "14:00", staff_id, 60
+```
+
+---
+
+## WhatsApp Templates
+
+Configure these templates in your WhatsApp Business account:
+
+| Template Name | Purpose | Variables |
+|---------------|---------|-----------|
+| `follow_up_thanks` | 1-day follow-up | name, interest |
+| `follow_up_value` | 3-day value proposition | name, interest |
+| `follow_up_offer` | 7-day special offer | name, discount |
+| `payment_due_today` | Payment due reminder | name, invoice_id, amount |
+| `payment_overdue_3` | 3-day overdue notice | name, invoice_id, amount |
+| `payment_overdue_7` | 7-day overdue notice | name, invoice_id, amount |
+| `payment_final_notice` | 15-day final notice | name, invoice_id, total |
+| `appointment_reminder_24h` | Day-before reminder | name, service, date, time, staff |
+| `appointment_reminder_2h` | 2-hour reminder | name, service, time |
+| `missed_appointment` | No-show reschedule | name, service |
+| `new_hot_lead` | Hot lead alert for sales | rep_name, lead_name, company, score |
+| `stale_opportunity` | Stale deal reminder | rep_name, deal_name, amount, days |
+
+---
+
 ## See Also

 - [Human Approval](../chapter-06-gbdialog/keyword-human-approval.md)
+- [SEND TEMPLATE](../chapter-06-gbdialog/keyword-send-template.md)
+- [SET SCHEDULE](../chapter-06-gbdialog/keyword-set-schedule.md)
+- [CREATE LEAD](../chapter-06-gbdialog/keywords-lead-scoring.md)
+- [Sales CRM Template](../chapter-02/template-crm.md)
--- a/src/appendix-external-services/hosting-dns.md
+++ b/src/appendix-external-services/hosting-dns.md
@ -0,0 +1,325 @@
+# Hosting, DNS, and MDA Integration
+
+General Bots integrates with hosting providers, DNS services, and Mail Delivery Agents (MDA) for complete platform deployment.
+
+---
+
+## Overview
+
+A complete General Bots deployment typically includes:
+
+| Component | Purpose | Providers Supported |
+|-----------|---------|---------------------|
+| **Hosting** | Run BotServer | Any VPS, LXC, bare metal |
+| **DNS** | Domain management | Namecheap, Cloudflare, Route53 |
+| **MDA** | Email delivery | Stalwart, Postfix, external SMTP |
+| **AI/LLM** | Language models | OpenAI, Anthropic, local models |
+
+---
+
+## Namecheap Integration
+
+General Bots can automatically manage DNS records via the Namecheap API.
+
+### Configuration
+
+Add to your bot's `config.csv`:
+
+```csv
+name,value
+namecheap-api-user,your-username
+namecheap-api-key,stored-in-vault
+namecheap-username,your-username
+namecheap-client-ip,your-server-ip
+```
+
+> **Note**: API key is stored in Vault, not in config.csv. Only reference it by name.
+
+### Automatic DNS Setup
+
+When deploying a new bot instance, General Bots can:
+
+1. Create A record pointing to your server
+2. Create MX records for email
+3. Create TXT records for SPF/DKIM/DMARC
+4. Create CNAME for www subdomain
+
+### BASIC Keywords for DNS
+
+```basic
+' Create DNS record
+DNS SET "bot.example.com", "A", server_ip
+
+' Create MX record for email
+DNS SET "example.com", "MX", "mail.example.com", 10
+
+' Create SPF record
+DNS SET "example.com", "TXT", "v=spf1 mx a ip4:" + server_ip + " -all"
+
+' List current records
+records = DNS LIST "example.com"
+```
+
+### Supported DNS Providers
+
+| Provider | API Support | Auto-SSL |
+|----------|-------------|----------|
+| Namecheap | ✅ Full | ✅ Let's Encrypt |
+| Cloudflare | ✅ Full | ✅ Native |
+| Route53 | ✅ Full | ✅ ACM |
+| DigitalOcean | ✅ Full | ✅ Let's Encrypt |
+| Manual | Via config | Manual |
+
+---
+
+## Hosting Options
+
+### VPS Providers
+
+General Bots runs on any Linux VPS:
+
+| Provider | Minimum Spec | Recommended |
+|----------|--------------|-------------|
+| DigitalOcean | 2GB RAM, 1 vCPU | 4GB RAM, 2 vCPU |
+| Linode | 2GB RAM, 1 vCPU | 4GB RAM, 2 vCPU |
+| Vultr | 2GB RAM, 1 vCPU | 4GB RAM, 2 vCPU |
+| Hetzner | 2GB RAM, 2 vCPU | 4GB RAM, 2 vCPU |
+| AWS EC2 | t3.small | t3.medium |
+| GCP | e2-small | e2-medium |
+
+### LXC Container Deployment
+
+Recommended for production isolation:
+
+```bash
+# Create container
+lxc launch ubuntu:22.04 botserver
+
+# Configure resources
+lxc config set botserver limits.memory 4GB
+lxc config set botserver limits.cpu 2
+
+# Forward ports
+lxc config device add botserver http proxy listen=tcp:0.0.0.0:80 connect=tcp:127.0.0.1:8080
+lxc config device add botserver https proxy listen=tcp:0.0.0.0:443 connect=tcp:127.0.0.1:8443
+
+# Set environment for Vault
+lxc config set botserver environment.VAULT_ADDR="http://vault:8200"
+
+# Deploy
+lxc exec botserver -- ./botserver
+```
+
+### Docker Deployment
+
+```yaml
+version: '3.8'
+services:
+  botserver:
+    image: generalbots/botserver:latest
+    ports:
+      - "8080:8080"
+    environment:
+      - VAULT_ADDR=http://vault:8200
+    volumes:
+      - ./bots:/app/bots
+      - ./botserver-stack:/app/botserver-stack
+```
+
+---
+
+## MDA (Mail Delivery Agent) Integration
+
+General Bots includes Stalwart mail server for complete email functionality.
+
+### Built-in Stalwart
+
+Stalwart is automatically configured during bootstrap:
+
+| Feature | Status |
+|---------|--------|
+| IMAP | ✅ Enabled |
+| SMTP | ✅ Enabled |
+| JMAP | ✅ Enabled |
+| Spam filtering | ✅ SpamAssassin |
+| Virus scanning | ✅ ClamAV |
+| DKIM signing | ✅ Auto-configured |
+
+### Email Configuration
+
+In `config.csv`:
+
+```csv
+name,value
+email-domain,example.com
+email-dkim-selector,mail
+email-spam-threshold,5.0
+email-max-size-mb,25
+```
+
+### DNS Records for Email
+
+Required DNS records (auto-created with Namecheap integration):
+
+| Record | Type | Value |
+|--------|------|-------|
+| `mail.example.com` | A | Your server IP |
+| `example.com` | MX | `mail.example.com` (priority 10) |
+| `example.com` | TXT | `v=spf1 mx a -all` |
+| `mail._domainkey.example.com` | TXT | DKIM public key |
+| `_dmarc.example.com` | TXT | `v=DMARC1; p=quarantine` |
+
+### External SMTP
+
+To use external email providers instead:
+
+```csv
+name,value
+smtp-host,smtp.sendgrid.net
+smtp-port,587
+smtp-user,apikey
+smtp-secure,tls
+```
+
+Credentials stored in Vault:
+
+```bash
+vault kv put secret/botserver/smtp password="your-api-key"
+```
+
+---
+
+## AI/LLM Integration
+
+### Supported Providers
+
+| Provider | Models | Config Key |
+|----------|--------|------------|
+| OpenAI | GPT-4, GPT-3.5 | `llm-url=https://api.openai.com/v1` |
+| Anthropic | Claude 3 | `llm-url=https://api.anthropic.com` |
+| Groq | Llama, Mixtral | `llm-url=https://api.groq.com/openai/v1` |
+| DeepSeek | DeepSeek-V2 | `llm-url=https://api.deepseek.com` |
+| Local | Any GGUF | `llm-url=http://localhost:8081` |
+
+### Local LLM Setup
+
+Run local models with BotModels:
+
+```bash
+# Install BotModels
+./botserver install llm
+
+# Download a model
+./botserver model download llama-3-8b
+
+# Configure in config.csv
+```
+
+```csv
+name,value
+llm-url,http://localhost:8081
+llm-model,llama-3-8b.gguf
+llm-context-size,8192
+llm-gpu-layers,35
+```
+
+### AI Features
+
+| Feature | Description |
+|---------|-------------|
+| **Conversation** | Natural language chat |
+| **RAG** | Knowledge base search |
+| **Tool Calling** | Automatic BASIC tool invocation |
+| **Embeddings** | Document vectorization |
+| **Vision** | Image analysis (multimodal models) |
+| **Voice** | Speech-to-text, text-to-speech |
+
+---
+
+## Complete Deployment Example
+
+### 1. Provision Server
+
+```bash
+# On your VPS
+wget https://github.com/GeneralBots/botserver/releases/latest/botserver
+chmod +x botserver
+```
+
+### 2. Configure DNS (Namecheap)
+
+```basic
+' setup-dns.bas
+domain = "mybot.example.com"
+server_ip = "203.0.113.50"
+
+DNS SET domain, "A", server_ip
+DNS SET "mail." + domain, "A", server_ip
+DNS SET domain, "MX", "mail." + domain, 10
+DNS SET domain, "TXT", "v=spf1 mx a ip4:" + server_ip + " -all"
+
+PRINT "DNS configured for " + domain
+```
+
+### 3. Start BotServer
+
+```bash
+./botserver
+```
+
+### 4. Configure SSL
+
+```bash
+# Auto-configured with Let's Encrypt
+./botserver ssl enable mybot.example.com
+```
+
+### 5. Verify Email
+
+```basic
+' test-email.bas
+SEND MAIL "test@gmail.com", "Test from General Bots", "Email is working!"
+PRINT "Email sent successfully"
+```
+
+---
+
+## Troubleshooting
+
+### DNS Not Propagating
+
+1. Check Namecheap API credentials
+2. Verify client IP is whitelisted
+3. Wait up to 48 hours for propagation
+4. Use `dig` or `nslookup` to verify
+
+### Email Marked as Spam
+
+1. Verify SPF record is correct
+2. Check DKIM signature is valid
+3. Ensure DMARC policy is set
+4. Check IP reputation at mxtoolbox.com
+
+### SSL Certificate Errors
+
+1. Verify DNS A record points to server
+2. Check port 80 is accessible for ACME challenge
+3. Review Let's Encrypt rate limits
+4. Check certificate expiry
+
+### LLM Connection Failed
+
+1. Verify `llm-url` in config.csv
+2. Check API key in Vault
+3. Test endpoint with curl
+4. Review BotServer logs
+
+---
+
+## See Also
+
+- [LLM Providers](./llm-providers.md) — Detailed LLM configuration
+- [Storage](./storage.md) — S3-compatible storage setup
+- [Directory](./directory.md) — User authentication
+- [Channels](./channels.md) — WhatsApp, Telegram, etc.
+- [Installation](../chapter-01/installation.md) — Full installation guide
--- a/src/chapter-01/README.md
+++ b/src/chapter-01/README.md
@ -1,41 +1,130 @@
 # Chapter 01: Run and Talk

-Get General Bots running in 5 minutes.
+> **⚡ In a hurry?** Jump straight to [Quick Start](./quick-start.md) — you'll be chatting with your bot in 5 minutes.

-## What You'll Learn
+Get General Bots running and have your first conversation.

- How to start General Bots
- Your first conversation
- How sessions work
- Basic bot interaction
+---

-## Quick Start
+## What You'll Achieve
+
+By the end of this chapter, you will:
+
+- ✅ Have General Bots running on your machine
+- ✅ Understand what happens during bootstrap
+- ✅ Complete your first conversation with a bot
+- ✅ Know how sessions and channels work
+
+---
+
+## Choose Your Path
+
+| If You Want To... | Go To |
+|-------------------|-------|
+| Get running immediately | [Quick Start](./quick-start.md) |
+| Understand the architecture first | [Overview](./overview.md) |
+| See all installation options | [Installation](./installation.md) |
+| Learn about conversations | [First Conversation](./first-conversation.md) |
+| Understand session management | [Sessions and Channels](./sessions.md) |
+
+---
+
+## The 30-Second Version

-Download and run:
 ```bash
 ./botserver
 ```

-That's it. Everything installs automatically on first run.
+Open `http://localhost:8080`. Start chatting. That's it.

-## What Happens
+Everything installs automatically on first run—PostgreSQL, storage, cache, and your first bot.

-1. **Auto-Bootstrap**: Installs PostgreSQL, cache, storage, and LLM
-2. **Load Bots**: Finds `.gbai` folders and loads them
-3. **Start Server**: Opens on `http://localhost:8080`
-4. **Ready**: Talk to your bot
+---

-## First Conversation
+## How It Works

-Open browser, type a message, get a response. Simple.
+<div class="wa-chat">
+  <div class="wa-message user">
+    <div class="wa-bubble">
+      <p>How do I get started with General Bots?</p>
+      <div class="wa-time">09:00</div>
+    </div>
+  </div>
+  <div class="wa-message bot">
+    <div class="wa-bubble">
+      <p>Just three steps:</p>
+      <p>1️⃣ Download <code>botserver</code></p>
+      <p>2️⃣ Run <code>./botserver</code></p>
+      <p>3️⃣ Open your browser to localhost:8080</p>
+      <p>The bootstrap process handles everything else automatically!</p>
+      <div class="wa-time">09:00</div>
+    </div>
+  </div>
+  <div class="wa-message user">
+    <div class="wa-bubble">
+      <p>What gets installed?</p>
+      <div class="wa-time">09:01</div>
+    </div>
+  </div>
+  <div class="wa-message bot">
+    <div class="wa-bubble">
+      <p>📦 PostgreSQL (database)</p>
+      <p>📦 MinIO (file storage)</p>
+      <p>📦 Cache (Redis-compatible)</p>
+      <p>📦 Default bot templates</p>
+      <p>All in <code>botserver-stack/</code> — no system-wide installation!</p>
+      <div class="wa-time">09:01</div>
+    </div>
+  </div>
+</div>

-## Topics Covered
+---

- [Overview](./overview.md) - What General Bots does
- [Quick Start](./quick-start.md) - Get running fast
- [Installation](./installation.md) - Detailed setup options
- [First Conversation](./first-conversation.md) - Using your bot
- [Sessions](./sessions.md) - How conversations are managed
+## Topics in This Chapter
+
+### [Overview](./overview.md)
+What General Bots does and how it fits together.
+
+### [Quick Start](./quick-start.md)
+The fastest path from zero to running bot.
+
+### [Installation](./installation.md)
+Detailed setup options including LXC containers and production deployment.
+
+### [First Conversation](./first-conversation.md)
+Understanding how the bot responds and learns.
+
+### [Sessions and Channels](./sessions.md)
+How conversations are managed across WhatsApp, Web, Telegram, and more.
+
+---
+
+## Coming From Executive Vision?
+
+If you just read the [Executive Vision](../executive-vision.md), here's what to know:
+
+1. **Everything in that feature table?** It's all included in the single `botserver` binary
+2. **No configuration needed** — Bootstrap detects your system and sets everything up
+3. **Start simple** — Run it, chat with it, then customize
+
+The philosophy is: **get running first, understand later**.
+
+---
+
+## Prerequisites
+
+- **Operating System**: Linux, macOS, or Windows (WSL2 recommended)
+- **Disk Space**: ~2GB for botserver-stack
+- **RAM**: 4GB minimum, 8GB recommended
+- **Ports**: 8080 (web), 5432 (database), 9000 (storage)
+
+No Docker required. No cloud accounts. No API keys to start.
+
+---
+
+## Next Step
+
+**[Quick Start →](./quick-start.md)**

 ---

--- a/src/chapter-04-gbui/apps/chat.md
+++ b/src/chapter-04-gbui/apps/chat.md
@ -77,6 +77,8 @@ Bot responses support full Markdown rendering:
 - Links and images
 - Tables

+---
+
 ## Keyboard Shortcuts

 | Shortcut | Action |
@ -87,6 +89,8 @@ Bot responses support full Markdown rendering:
 | `/` | Open command menu |
 | `Escape` | Cancel current action |

+---
+
 ## API Endpoints

 ### WebSocket Connection
@ -112,7 +116,7 @@ ws://your-server:8080/ws
 | `/api/voice/stop` | POST | Stop voice recording |
 | `/api/suggestions` | GET | Get suggestion chips |

-
+---

 ## Example Conversations

@ -179,7 +183,7 @@ ws://your-server:8080/ws
  </div>
 </div>

-
+---

 ## Accessibility

@ -189,19 +193,7 @@ ws://your-server:8080/ws
 - Adjustable font sizes
 - ARIA labels on all interactive elements

-```html
-<main id="messages" 
-      role="log" 
-      aria-live="polite"
-      aria-label="Chat messages">
-</main>
-
-<button type="submit" 
-        aria-label="Send message"
-        title="Send">
-    ↑
-</button>
-```
+---

 ## Troubleshooting

@ -226,9 +218,11 @@ ws://your-server:8080/ws
 3. Clear browser cache
 4. Check for JavaScript errors

+---
+
 ## See Also

- [HTMX Architecture](../htmx-architecture.md) - How Chat uses HTMX
- [Suite Manual](../suite-manual.md) - Complete user guide
- [Tasks App](./tasks.md) - Create tasks from chat
- [Mail App](./mail.md) - Email integration
+- [HTMX Architecture](../htmx-architecture.md) — How Chat uses HTMX
+- [Suite Manual](../suite-manual.md) — Complete user guide
+- [Tasks App](./tasks.md) — Create tasks from chat
+- [Mail App](./mail.md) — Email integration
--- a/src/chapter-04-gbui/monitoring.md
+++ b/src/chapter-04-gbui/monitoring.md
@ -1,8 +1,8 @@
 # Monitoring Dashboard

-The Monitoring Dashboard provides real-time visibility into your General Bots deployment through an animated, interactive SVG visualization showing system health, active sessions, and resource utilization.
+The Monitoring Dashboard is the **live operations homepage** for your General Bots deployment. It provides real-time visibility into system health, active sessions, and resource utilization through an animated, interactive SVG visualization.

-## Live System Visualization
+## Live System Architecture

 <img src="../assets/suite/live-monitoring-organism.svg" alt="Live Monitoring Dashboard" style="max-width: 100%; height: auto;">

@ -14,113 +14,109 @@ The dashboard displays BotServer at the center orchestrating all interactions, w
 - **Top**: Real-time metrics panels for sessions, messages, and response time
 - **Bottom**: Resource utilization bars and activity ticker

+---
+
 ## Accessing the Dashboard

-Access monitoring from the Suite interface:
+The monitoring dashboard is the **default homepage** when accessing Suite:
+
+```/dev/null/monitoring-url.txt#L1
+http://localhost:8080/monitoring
+```
+
+Or from within Suite:
 1. Click the apps menu (⋮⋮⋮)
 2. Select **Monitoring**
-3. Or navigate directly to `/monitoring`

-## Dashboard Features
+---

-### Animated System Architecture
+## Real-Time Metrics

-The SVG visualization shows real-time data flow:
+### Active Sessions Panel

-| Component | Color | Description |
-|-----------|-------|-------------|
-| **BotServer** | Blue/Purple | Central orchestrator with rotating ring |
-| **PostgreSQL** | Blue | Primary database with cylinder icon |
-| **Qdrant** | Purple | Vector database with triangle nodes |
-| **MinIO** | Amber | Object storage with disk icon |
-| **BotModels** | Pink | AI/ML service with neural network icon |
-| **Cache** | Cyan | In-memory cache with lightning icon |
-| **Vault** | Green | Secrets management with lock icon |
+Displays current conversation sessions:
+
+```/dev/null/sessions-example.txt#L1-4
+Active Sessions: 12
+Peak Today: 47
+Avg Duration: 8m 32s
+Trend: ↑ +3 in last hour
+```
+
+### Messages Panel
+
+Shows message throughput:
+
+```/dev/null/messages-example.txt#L1-4
+Today: 1,234 messages
+This Hour: 89
+Avg Response: 1.2s
+Rate: 14.8 msg/min
+```
+
+### Resource Utilization
+
+Real-time system resources:
+
+| Resource | Current | Threshold |
+|----------|---------|-----------|
+| **CPU** | 65% | Warning > 80% |
+| **Memory** | 72% | Warning > 85% |
+| **GPU** | 45% | Warning > 90% |
+| **Disk** | 28% | Warning > 90% |
+
+---
+
+## Service Health Status
+
+Each service has a status indicator:
+
+| Service | Status | Health Check |
+|---------|--------|--------------|
+| **PostgreSQL** | 🟢 Running | Connection pool, query latency |
+| **Qdrant** | 🟢 Running | Vector count, search time |
+| **MinIO** | 🟢 Running | Storage usage, object count |
+| **BotModels** | 🟢 Running | Token usage, response time |
+| **Cache** | 🟢 Running | Hit rate, memory usage |
+| **Vault** | 🟢 Running | Seal status, policy count |

 ### Status Indicators

-Each service has a status dot:
-
 | Status | Color | Animation |
 |--------|-------|-----------|
 | **Running** | 🟢 Green | Gentle pulse |
 | **Warning** | 🟡 Amber | Fast pulse |
 | **Stopped** | 🔴 Red | No animation |

-### Real-Time Metrics
+---

-Three metric panels at the top update automatically:
+## Live Data Endpoints

-| Panel | Update Interval | Description |
-|-------|-----------------|-------------|
-| **Active Sessions** | 5 seconds | Current open conversations with trend |
-| **Messages Today** | 10 seconds | Total messages with hourly rate |
-| **Avg Response** | 10 seconds | Average response time in milliseconds |
-
-### Resource Utilization
-
-Resource bars show system health:
-
-| Resource | Gradient | Warning Threshold |
-|----------|----------|-------------------|
-| **CPU** | Blue/Purple | > 80% |
-| **Memory** | Green | > 85% |
-| **GPU** | Purple | > 90% |
-| **Disk** | Amber | > 90% |
-
-### Activity Ticker
-
-A live ticker at the bottom shows the latest system events with a pulsing green indicator.
-
-## View Modes
-
-Toggle between two views using the grid button or press `V`:
-
-### Live View (Default)
-The animated SVG visualization showing the complete system topology with flowing data packets.
-
-### Grid View
-Traditional panel-based layout with detailed tree views for each metric category:
- Sessions panel with active, peak, and duration
- Messages panel with counts and rates
- Resources panel with progress bars
- Services panel with health status
- Bots panel with active bot list
-
-## Keyboard Shortcuts
-
-| Shortcut | Action |
-|----------|--------|
-| `V` | Toggle between Live and Grid view |
-| `R` | Refresh all metrics |
-
-## HTMX Integration
-
-The dashboard uses HTMX for real-time updates without full page reloads:
+The dashboard pulls real data from these HTMX endpoints:

 | Endpoint | Interval | Data |
 |----------|----------|------|
-| `/api/monitoring/metric/sessions` | 5s | Session count |
-| `/api/monitoring/metric/messages` | 10s | Message count |
-| `/api/monitoring/metric/response_time` | 10s | Avg response |
-| `/api/monitoring/resources/bars` | 15s | Resource SVG bars |
+| `/api/monitoring/metric/sessions` | 5s | Session count, trend |
+| `/api/monitoring/metric/messages` | 10s | Message count, rate |
+| `/api/monitoring/metric/response_time` | 10s | Avg response time |
+| `/api/monitoring/resources/bars` | 15s | CPU, memory, GPU, disk |
 | `/api/monitoring/services/status` | 30s | Service health JSON |
-| `/api/monitoring/activity/latest` | 5s | Activity text |
-| `/api/monitoring/timestamp` | 5s | Last updated time |
+| `/api/monitoring/activity/latest` | 5s | Activity ticker text |
+| `/api/monitoring/bots/active` | 30s | Active bot list |
+
+---

 ## API Access

-Access monitoring data programmatically:
+### Full Status Endpoint

-### Get Full Status
-
-```/dev/null/monitoring-api.txt
+```/dev/null/api-call.txt#L1
 GET /api/monitoring/status
 ```

-**Response:**
+Returns complete system status:

-```/dev/null/monitoring-response.json
+```/dev/null/monitoring-response.json#L1-25
 {
  "sessions": {
    "active": 12,
@ -149,31 +145,89 @@ GET /api/monitoring/status
 }
 ```

-### Service-Specific Endpoints
+### Active Bots Endpoint

-| Endpoint | Returns |
-|----------|---------|
-| `/api/monitoring/services` | All service details |
-| `/api/monitoring/bots` | Active bot list |
-| `/api/monitoring/history?period=24h` | Historical metrics |
-| `/api/monitoring/prometheus` | Prometheus format export |
+```/dev/null/bots-api.txt#L1
+GET /api/monitoring/bots
+```

-## Component Health Details
+Returns list of deployed bots with metrics:

-| Component | Health Check | Warning Signs |
-|-----------|--------------|---------------|
-| **PostgreSQL** | Connection count, query rate | > 80 connections, slow queries |
-| **Qdrant** | Vector count, search latency | > 50ms search time |
-| **MinIO** | Storage usage, object count | > 80% storage used |
-| **BotModels** | Token usage, response latency | > 2s response time |
-| **Vault** | Seal status, policy count | Unsealed without auth |
-| **Cache** | Hit rate, memory usage | < 80% hit rate |
+```/dev/null/bots-response.json#L1-18
+{
+  "bots": [
+    {
+      "name": "default",
+      "status": "active",
+      "sessions_today": 34,
+      "messages_today": 567,
+      "avg_response_ms": 980
+    },
+    {
+      "name": "support",
+      "status": "active",
+      "sessions_today": 12,
+      "messages_today": 234,
+      "avg_response_ms": 1100
+    }
+  ]
+}
+```

-## Alerts Configuration
+### Historical Data
+
+```/dev/null/history-api.txt#L1
+GET /api/monitoring/history?period=24h
+```
+
+Returns time-series data for charting.
+
+### Prometheus Export
+
+```/dev/null/prometheus-api.txt#L1
+GET /api/monitoring/prometheus
+```
+
+Returns metrics in Prometheus format for external monitoring systems.
+
+---
+
+## View Modes
+
+Toggle between two views using the grid button or press `V`:
+
+### Live View (Default)
+
+The animated SVG visualization showing the complete system topology with flowing data packets. This is the recommended view for operations dashboards.
+
+### Grid View
+
+Traditional panel-based layout with detailed metrics:
+
+- **Sessions Panel**: Active, peak, average duration
+- **Messages Panel**: Counts, rates, response times
+- **Resources Panel**: Progress bars with thresholds
+- **Services Panel**: Health status for each component
+- **Bots Panel**: List of active bots with metrics
+
+---
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `V` | Toggle between Live and Grid view |
+| `R` | Refresh all metrics immediately |
+| `F` | Toggle fullscreen mode |
+| `?` | Show keyboard shortcuts |
+
+---
+
+## Alert Configuration

 Configure alert thresholds in `config.csv`:

-```/dev/null/config-alerts.csv
+```/dev/null/config-alerts.csv#L1-6
 name,value
 alert-cpu-threshold,80
 alert-memory-threshold,85
@ -182,78 +236,93 @@ alert-response-time-ms,5000
 alert-email,admin@example.com
 ```

-## Console Mode
+When thresholds are exceeded:
+1. Service status turns amber/red
+2. Alert notification sent to configured email
+3. Activity ticker shows alert message

-For terminal-based monitoring:
+---

-```/dev/null/console-command.bash
+## Console Mode Monitoring
+
+For terminal-based monitoring or headless servers:
+
+```/dev/null/console-command.sh#L1
 ./botserver --console --monitor
 ```

 Output:
-```/dev/null/console-output.txt
+
+```/dev/null/console-output.txt#L1-6
 [MONITOR] 2025-01-15 14:32:00
 Sessions: 12 active (peak: 47)
 Messages: 1,234 today (89/hour)
 CPU: 65% | MEM: 72% | GPU: 45%
 Services: 6/6 running
+Latest: User enrolled in Computer Science course
 ```

-## Tips & Best Practices
+---

-💡 **Watch the data packets** - Flowing animations indicate active communication between components
+## Component Health Details

-💡 **Monitor trends** - The session trend indicator (↑/↓) shows direction of change
+| Component | Metrics Monitored | Warning Signs |
+|-----------|-------------------|---------------|
+| **PostgreSQL** | Connection count, query rate, replication lag | > 80 connections, queries > 100ms |
+| **Qdrant** | Vector count, search latency, memory | > 50ms search, > 80% memory |
+| **MinIO** | Storage usage, object count, bandwidth | > 80% storage, high error rate |
+| **BotModels** | Token usage, response latency, queue depth | > 2s response, queue > 10 |
+| **Vault** | Seal status, policy count, auth failures | Sealed, repeated auth failures |
+| **Cache** | Hit rate, memory usage, evictions | < 80% hit rate, frequent evictions |

-💡 **Click services** - Click any service node in Live view to see detailed status
+---

-💡 **Set up alerts** - Configure thresholds before issues become critical
+## Best Practices

-💡 **Use keyboard shortcuts** - Press `R` for quick refresh, `V` to toggle views
+1. **Keep monitoring visible** — Use a dedicated screen or dashboard monitor for operations
+2. **Set appropriate thresholds** — Configure alerts before issues become critical
+3. **Watch data flow** — Animated packets indicate active communication between components
+4. **Monitor trends** — The session trend indicator (↑/↓) shows direction of change
+5. **Use historical data** — Query `/api/monitoring/history` for trend analysis
+6. **Enable Prometheus export** — Integrate with existing monitoring infrastructure

-💡 **Check historical data** - Query `/api/monitoring/history` for trend analysis
+---

 ## Troubleshooting

-### Dashboard not loading
+### Dashboard Not Loading

-**Possible causes:**
-1. WebSocket connection failed
-2. API endpoint unreachable
-3. Browser blocking HTMX
-
-**Solution:**
 1. Check browser console for errors
 2. Verify `/api/monitoring/status` returns data
-3. Refresh the page
+3. Ensure WebSocket connection is established
+4. Refresh the page

-### Metrics showing "--"
+### Metrics Showing "--"

-**Possible causes:**
-1. Initial load in progress
-2. API timeout
-3. Service unavailable
+1. Wait 5-10 seconds for initial data load
+2. Check network tab for failed API requests
+3. Verify all services are running
+4. Check BotServer logs for errors

-**Solution:**
-1. Wait 5-10 seconds for first update
-2. Check network tab for failed requests
-3. Verify services are running
+### Animations Stuttering

-### Animations stuttering
-
-**Possible causes:**
-1. High CPU usage
-2. Many browser tabs open
-3. Hardware acceleration disabled
-
-**Solution:**
-1. Close unused tabs
-2. Enable hardware acceleration in browser
+1. Close unused browser tabs
+2. Enable hardware acceleration in browser settings
 3. Use Grid view for lower resource usage
+4. Check if system CPU is overloaded
+
+### Service Showing Red
+
+1. Check service-specific logs in `botserver-stack/logs/`
+2. Verify Vault is unsealed
+3. Check database connection limits
+4. Restart the affected service
+
+---

 ## See Also

- [Monitoring API Reference](../chapter-10-api/monitoring-api.md)
- [Console Mode](./console-mode.md)
- [Configuration Options](../chapter-08-config/README.md)
- [Analytics App](./apps/analytics.md)
+- [Console Mode](./console-mode.md) — Terminal-based interface
+- [HTMX Architecture](./htmx-architecture.md) — How real-time updates work
+- [Suite Manual](./suite-manual.md) — Complete user guide
+- [Analytics App](./apps/analytics.md) — Business metrics and reporting
--- a/src/chapter-06-gbdialog/examples-consolidated.md
+++ b/src/chapter-06-gbdialog/examples-consolidated.md
--- a/src/executive-vision.md
+++ b/src/executive-vision.md
@ -189,8 +189,40 @@ Pragmatismo develops General Bots as an open-source platform for enterprise AI a

 ---

+## QUICK START
+
+Ready to see it in action? Skip to the hands-on guide:
+
+**[⚡ Quick Start: Run Your First Bot in 5 Minutes →](./chapter-01/quick-start.md)**
+
+Or continue reading for the full journey:
+
+| Path | Time | Best For |
+|------|------|----------|
+| [Quick Start](./chapter-01/quick-start.md) | 5 min | Developers who want to dive in immediately |
+| [Introduction](./introduction.md) | 10 min | Understanding the "No Forms" philosophy |
+| [Chapter 01](./chapter-01/README.md) | 15 min | Complete installation and first conversation |
+
+---
+
 ## NEXT STEPS

-[Chapter 01: Run and Talk →](./chapter-01/README.md)
+<div class="wa-chat">
+  <div class="wa-message user">
+    <div class="wa-bubble">
+      <p>I want to try General Bots now</p>
+      <div class="wa-time">09:00</div>
+    </div>
+  </div>
+  <div class="wa-message bot">
+    <div class="wa-bubble">
+      <p>Great! Just run:</p>
+      <p><code>./botserver</code></p>
+      <p>Then open http://localhost:8080</p>
+      <p>That's it! 🚀</p>
+      <div class="wa-time">09:00</div>
+    </div>
+  </div>
+</div>

-Get started with your General Bots deployment in minutes.
+[Chapter 01: Run and Talk →](./chapter-01/README.md)
--- a/src/introduction.md
+++ b/src/introduction.md
@ -1,7 +1,16 @@
 # Introduction to General Bots

+> **⚡ Want to skip ahead?** [Quick Start →](./chapter-01/quick-start.md) gets you running in 5 minutes.
+
 **Build conversational AI bots in minutes, not months.** General Bots lets you create intelligent chatbots by writing simple [BASIC scripts](./chapter-06-gbdialog/basics.md) and dropping in your [documents](./chapter-02/gbkb.md). No complex frameworks, no cloud dependencies, no AI expertise required.

+| Your Goal | Go To |
+|-----------|-------|
+| Run a bot NOW | [Quick Start](./chapter-01/quick-start.md) |
+| Understand the vision | Keep reading below |
+| Write your first script | [Chapter 06: BASIC Dialogs](./chapter-06-gbdialog/README.md) |
+| Add documents to bot | [Chapter 02: Packages](./chapter-02/README.md) |
+
 ## The No Forms Movement

 <img src="./assets/general-bots-2017.svg" alt="General Bots in 2017" style="max-height: 300px; width: 100%; object-fit: contain;">
@ -47,17 +56,57 @@ General Bots was born from this vision: **replace forms with conversations**.

 ### After: The Conversation Experience

-```
-User: I need help with my order
-Bot: I'd be happy to help! What's your order number?
-User: It's 12345
-Bot: Found it - your laptop order from last week. What's the issue?
-User: It arrived damaged
-Bot: I'm sorry to hear that. I'll create a return label for you. 
-     Should I send it to your email on file?
-User: Yes please
-Bot: Done! Check your inbox. Is there anything else?
-```
+<div class="wa-chat">
+  <div class="wa-message user">
+    <div class="wa-bubble">
+      <p>I need help with my order</p>
+      <div class="wa-time">10:30</div>
+    </div>
+  </div>
+  <div class="wa-message bot">
+    <div class="wa-bubble">
+      <p>I'd be happy to help! What's your order number?</p>
+      <div class="wa-time">10:30</div>
+    </div>
+  </div>
+  <div class="wa-message user">
+    <div class="wa-bubble">
+      <p>It's 12345</p>
+      <div class="wa-time">10:30</div>
+    </div>
+  </div>
+  <div class="wa-message bot">
+    <div class="wa-bubble">
+      <p>Found it - your laptop order from last week. What's the issue?</p>
+      <div class="wa-time">10:30</div>
+    </div>
+  </div>
+  <div class="wa-message user">
+    <div class="wa-bubble">
+      <p>It arrived damaged</p>
+      <div class="wa-time">10:31</div>
+    </div>
+  </div>
+  <div class="wa-message bot">
+    <div class="wa-bubble">
+      <p>I'm sorry to hear that. I'll create a return label for you.</p>
+      <p>Should I send it to your email on file?</p>
+      <div class="wa-time">10:31</div>
+    </div>
+  </div>
+  <div class="wa-message user">
+    <div class="wa-bubble">
+      <p>Yes please</p>
+      <div class="wa-time">10:31</div>
+    </div>
+  </div>
+  <div class="wa-message bot">
+    <div class="wa-bubble">
+      <p>✅ Done! Check your inbox. Is there anything else?</p>
+      <div class="wa-time">10:31</div>
+    </div>
+  </div>
+</div>

 **Benefits:**
 - Natural and intuitive