botbook/PROMPT.md

botbook Development Guide

Version: 6.2.0 Purpose: Documentation for General Bots (mdBook)

---

CRITICAL: Keyword Naming Rules

Keywords NEVER use underscores. Always use spaces.

Correct Syntax

SEND MAIL to, subject, body, attachments
GENERATE PDF template, data, output
MERGE PDF files, output
DELETE "url"
ON ERROR RESUME NEXT
SET BOT MEMORY key, value
KB STATISTICS

WRONG - Never Use Underscores

SEND_MAIL          ' WRONG!
GENERATE_PDF       ' WRONG!
DELETE_HTTP        ' WRONG!

Keyword Mappings

Write This	NOT This
SEND MAIL	SEND_MAIL
GENERATE PDF	GENERATE_PDF
MERGE PDF	MERGE_PDF
DELETE	DELETE_HTTP
SET HEADER	SET_HEADER
FOR EACH	FOR_EACH

---

OFFICIAL ICONS - MANDATORY

NEVER generate icons with LLM. Use official SVG icons from botui/ui/suite/assets/icons/

Usage in Documentation

<!-- Reference icons in docs -->
![Chat](../assets/icons/gb-chat.svg)

<!-- With HTML for sizing -->
<img src="../assets/icons/gb-analytics.svg" alt="Analytics" width="24">

---

STRUCTURE

botbook/
├── book.toml          # mdBook configuration
├── src/
│   ├── SUMMARY.md     # Table of contents
│   ├── README.md      # Introduction
│   ├── 01-introduction/   # Quick Start
│   ├── 02-templates/      # Package System
│   ├── 03-knowledge-base/ # Knowledge Base
│   ├── 06-gbdialog/       # BASIC Dialogs
│   ├── 08-config/         # Configuration
│   ├── 10-rest/           # REST API
│   └── assets/            # Images, diagrams
├── i18n/              # Translations
└── book/              # Generated output

---

DOCUMENTATION RULES

- All documentation MUST match actual source code
- Extract real keywords from botserver/src/basic/keywords/
- Use actual examples from botserver/templates/
- Version numbers must be 6.2.0
- No placeholder content - only verified features

---

NO ASCII DIAGRAMS - MANDATORY

NEVER use ASCII art diagrams. ALL diagrams must be SVG.

Prohibited ASCII Patterns

+-------+
|  Box  |
+-------+

What to Use Instead

Instead of...	Use...
ASCII box diagrams	SVG diagrams in assets/
ASCII flow charts	SVG with arrows and boxes
ASCII directory trees	Markdown tables

---

SVG DIAGRAM GUIDELINES

All SVGs must support light/dark modes:

<style>
  .title-text { fill: #1E1B4B; }
  .main-text { fill: #334155; }

  @media (prefers-color-scheme: dark) {
    .title-text { fill: #F1F5F9; }
    .main-text { fill: #E2E8F0; }
  }
</style>

---

CONVERSATION EXAMPLES

Use WhatsApp-style HTML format for bot interactions:

<div class="wa-chat">
  <div class="wa-message bot">
    <div class="wa-bubble">
      <p>Hello! How can I help?</p>
      <div class="wa-time">10:30</div>
    </div>
  </div>
  <div class="wa-message user">
    <div class="wa-bubble">
      <p>I want to enroll</p>
      <div class="wa-time">10:31</div>
    </div>
  </div>
</div>

---

SOURCE CODE REFERENCES

Topic	Source Location
BASIC Keywords	botserver/src/basic/keywords/
Database Models	botserver/src/core/shared/models.rs
API Routes	botserver/src/core/urls.rs
Configuration	botserver/src/core/config/
Templates	botserver/templates/

---

BUILDING BOTSERVER

CRITICAL: ALWAYS USE DEBUG BUILD DURING DEVELOPMENT

# CORRECT - Use debug build (FAST)
cargo build

# WRONG - NEVER use --release during development (SLOW)
# cargo build --release  # DO NOT USE!

# Run debug server
cargo run

Why Debug Build:

• Debug builds compile in ~30 seconds
• Release builds take 5-10 minutes with LTO
• Debug builds are sufficient for development and testing
• Only use --release for production deployment

---

BUILDING DOCUMENTATION

# Install mdBook
cargo install mdbook

# Build documentation
cd botbook && mdbook build

# Serve locally with hot reload
mdbook serve --open

---

TESTING PROCEDURES

Tool Testing Workflow

CRITICAL: NO STOP UNTIL NO MORE ERRORS IN TOOLS

When testing bot tools, follow this sequential process WITHOUT STOPPING:

1. Test Tool #1
   ├─ Fill form one field at a time (if multi-step form)
   ├─ Verify NO ERRORS in output
   ├─ Check Result types are NOT visible (no "core::result::Result<..." strings)
   ├─ Verify database save (if applicable)
   ├─ IF ERRORS FOUND: FIX THEM IMMEDIATELY, RE-TEST SAME TOOL
   ├─ ONLY move to next tool when CURRENT tool has ZERO errors

2. Test Tool #2
   └─ (repeat process - DO NOT STOP if errors found)

3. Continue until ALL tools tested with ZERO errors

IMPORTANT:

• Do NOT stop testing to summarize or ask questions
• Do NOT move to next tool if current tool has errors
• Fix errors immediately, rebuild, re-test same tool
• Only proceed when current tool is completely error-free

Error Patterns to Watch For

CRITICAL ERRORS (Must Fix Before Proceeding):

• core::result::Result<alloc::string::String, alloc::string::String> in output
• invalid input syntax for type timestamp
• Some("Desculpe, houve um erro...")
• Empty balloon messages
• Rust debug info visible to users

Playwright Testing Tricks

// Click tool button
await page.getByRole('button', { name: 'Evento/Iluminação' }).click();

// Wait for response
await page.waitForTimeout(3000);

// Take snapshot
await page.snapshot();

// Fill form field by field
await page.getByRole('textbox').fill('field value');
await page.getByRole('textbox').press('Enter');

Test Documentation

After testing each tool, document:

1. Tool name and ID
2. All required parameters
3. Expected behavior
4. Any issues found and fixes applied
5. Final test result (PASS/FAIL)

---

REMEMBER

• Accuracy - Must match botserver source code
• Completeness - No placeholder sections
• Clarity - Accessible to BASIC enthusiasts
• Keywords - NEVER use underscores - always spaces
• NO ASCII art - Use SVG diagrams only
• Version 6.2.0 - Always reference 6.2.0
• GIT WORKFLOW - ALWAYS push to ALL repositories (github, pragmatismo)
• TESTING - Test tools ONE BY ONE, fix ALL errors before moving to next tool
• NO STOP - DO NOT STOP testing until ALL tools have ZERO errors - fix immediately and re-test