Add templates for authentication, enrollment, and greeting flows with detailed explanations and examples

docs/src/chapter-05/template-auth.md

@@ -1 +1,21 @@
 # auth.bas
+
+```basic
+REM Simple authentication flow
+SET attempts = 0
+LABEL auth_loop
+HEAR password
+IF password = "secret123" THEN
+    TALK "Authentication successful."
+ELSE
+    SET attempts = attempts + 1
+    IF attempts >= 3 THEN
+        TALK "Too many attempts. Goodbye."
+        EXIT
+    ENDIF
+    TALK "Incorrect password. Try again."
+    GOTO auth_loop
+ENDIF
+```
+
+This template demonstrates a basic password check with a limited number of attempts. It uses the `HEAR`, `TALK`, `SET`, `IF`, `ELSE`, `GOTO`, and `EXIT` keywords to manage the dialog flow.

docs/src/chapter-05/templates/auth.md

@@ -0,0 +1,31 @@
+# auth.bas (Template)
+
+This template demonstrates a simple authentication flow using the BASIC dialog language.
+
+```basic
+REM Simple authentication flow
+SET attempts = 0
+LABEL auth_loop
+HEAR password
+IF password = "secret123" THEN
+    TALK "Authentication successful."
+ELSE
+    SET attempts = attempts + 1
+    IF attempts >= 3 THEN
+        TALK "Too many attempts. Goodbye."
+        EXIT
+    ENDIF
+    TALK "Incorrect password. Try again."
+    GOTO auth_loop
+ENDIF
+```
+
+**Purpose**
+
+- Shows how to collect a password with `HEAR`.
+- Limits the number of attempts to three.
+- Uses `TALK` to give feedback and `EXIT` to end the dialog after too many failures.
+
+**Keywords used:** `SET`, `HEAR`, `IF`, `ELSE`, `GOTO`, `EXIT`, `TALK`.
+
+---

docs/src/chapter-05/templates/enrollment.md

@@ -0,0 +1,74 @@
+# enrollment.bas (Template)
+
+A comprehensive enrollment dialog that gathers user information, confirms it, and saves it to a CSV file.
+
+```basic
+REM Enrollment Tool Example
+
+## Complete Enrollment Script
+
+PARAM name AS string          LIKE "Abreu Silva"
+DESCRIPTION "Required full name of the individual."
+
+PARAM birthday AS date        LIKE "23/09/2001"
+DESCRIPTION "Required birth date of the individual in DD/MM/YYYY format."
+
+PARAM email AS string         LIKE "abreu.silva@example.com"
+DESCRIPTION "Required email address for contact purposes."
+
+PARAM personalid AS integer   LIKE "12345678900"
+DESCRIPTION "Required Personal ID number of the individual (only numbers)."
+
+PARAM address AS string       LIKE "Rua das Flores, 123 - SP"
+DESCRIPTION "Required full address of the individual."
+
+DESCRIPTION "This is the enrollment process, called when the user wants to enrol. Once all information is collected, confirm the details and inform them that their enrollment request has been successfully submitted. Provide a polite and professional tone throughout the interaction."
+
+REM Enrollment Process
+TALK "Welcome to the enrollment process! Let's get you registered."
+
+TALK "First, what is your full name?"
+HEAR name
+
+TALK "Thank you. What is your birth date? (DD/MM/YYYY)"
+HEAR birthday
+
+TALK "What is your email address?"
+HEAR email
+
+TALK "Please provide your Personal ID number (numbers only):"
+HEAR personalid
+
+TALK "Finally, what is your full address?"
+HEAR address
+
+REM Validate and confirm
+TALK "Please confirm your details:"
+TALK "Name: " + name
+TALK "Birth Date: " + birthday
+TALK "Email: " + email
+TALK "Personal ID: " + personalid
+TALK "Address: " + address
+
+TALK "Are these details correct? (yes/no)"
+HEAR confirmation
+
+IF confirmation = "yes" THEN
+    REM Save to CSV file
+    SAVE "enrollments.csv", name, birthday, email, personalid, address
+    TALK "Thank you! Your enrollment has been successfully submitted. You will receive a confirmation email shortly."
+ELSE
+    TALK "Let's start over with the correct information."
+    REM In a real implementation, you might loop back or use a different approach
+END IF
+```
+
+**Purpose**
+
+- Shows how to define parameters with `PARAM` and `DESCRIPTION`.
+- Demonstrates a multi‑step data collection flow using `HEAR` and `TALK`.
+- Confirms data before persisting it via `SAVE`.
+
+**Keywords used:** `PARAM`, `DESCRIPTION`, `HEAR`, `TALK`, `IF`, `ELSE`, `SAVE`.
+
+---

docs/src/chapter-05/templates/start.md

@@ -0,0 +1,25 @@
+# start.bas (Template)
+
+A minimal greeting and help flow to get users started.
+
+```basic
+REM Basic greeting and help flow
+SET user_name = "Guest"
+TALK "Hello, " + user_name + "! How can I help you today?"
+HEAR user_input
+IF user_input = "help" THEN
+    TALK "Sure, I can assist with account info, orders, or support."
+ELSE
+    TALK "Sorry, I didn't understand."
+ENDIF
+```
+
+**Purpose**
+
+- Shows how to set a variable with `SET`.
+- Uses `TALK` to send a message and `HEAR` to receive user input.
+- Demonstrates simple branching with `IF/ELSE`.
+
+**Keywords used:** `SET`, `TALK`, `HEAR`, `IF`, `ELSE`.
+
+---

prompts/dev/docs/docs-summary.md

@@ -1,166 +1,48 @@
-# Prompt for Generating GeneralBots mdBook Documentation
+**Task:** Generate comprehensive mdBook documentation for the GeneralBots application by analyzing the actual source code and filling all documentation files with accurate, complete information.
 
-**Goal**  
+**Objective:** Create complete, professional documentation for BASIC enthusiasts that accurately reflects the GeneralBots codebase.
-Generate a complete **mdBook** that documents the GeneralBots application for a user with basic knowledge of large‑language models (LLM).
 
-**Rules**  
+**Source Analysis Requirements:**
-- Use **only real keywords** and features that exist in the source code (no invented commands).  
+- Analyze all files in `@/src` directory structure
-- Include Rust code **exclusively** in the **gbapp** chapter.  
+- Extract real keywords from `src/basic/keywords/`
-- Keep the tone simple, beginner‑friendly, and instructional.  
+- Document actual database models from `src/shared/models.rs`
-- Base all information on the actual code base:  
+- Reference real example scripts from `templates/`
-  - Keywords in `src/basic/keywords/`  
+- Use only verified features that exist in the codebase
-  - Database models in `src/shared/models.rs`  
-  - Example scripts in `templates/`
 
-**Required Markdown Structure (headings)**  
+**Documentation Standards:**
+- Maintain beginner-friendly, instructional tone
+- Include Rust code examples ONLY in the gbapp chapter
+- Use real keywords and commands from the source code
+- Structure content according to the required markdown headings
+- Ensure all documentation can be built with `mdbook build docs/src`
 
-1. **Run and Talk** – How to start the server and interact using `TALK` / `HEAR`.  
+**Required Sections to Complete:**
-2. **About Packages** – Overview of the four package types (`.gbdialog`, `.gbkb`, `.gbtheme`, `.gbot`).  
+1. **Run and Talk** - Server startup and TALK/HEAR interaction
-3. **gbkb Reference** – Explain `ADD_KB`, `SET_KB`, `ADD_WEBSITE`.  
+2. **About Packages** - Four package types explanation
-4. **gbtheme Reference** – Describe UI theming via CSS/HTML.  
+3. **gbkb Reference** - ADD_KB, SET_KB, ADD_WEBSITE documentation
-5. **gbdialog Reference** – List the three example scripts (`start.bas`, `auth.bas`, `update-summary.bas`) and the core keywords (`TALK`, `HEAR`, `LLM`, etc.).  
+4. **gbtheme Reference** - UI theming with CSS/HTML
-6. **gbapp Reference** – Show a minimal Rust snippet that registers a keyword (e.g., `ADD_TOOL`).  
+5. **gbdialog Reference** - Example scripts and core keywords
-7. **gbot Reference** – Explain the `config.csv` format and editable parameters.  
+6. **gbapp Reference** - Rust keyword registration examples
-8. **Tooling** – Table of all built‑in keywords with one‑line descriptions.  
+7. **gbot Reference** - config.csv format and parameters
-9. **Feature‑Matrix** – Table mapping features to the chapters/keywords that implement them.  
+8. **Tooling** - Complete keyword reference table
-10. **Contributing** – Steps for contributors (fork, branch, tests, formatting).  
+9. **Feature-Matrix** - Features to implementation mapping
-11. **Appendix I – Database Model** – Summarise the main tables from `src/shared/models.rs`.  
+10. **Contributing** - Development workflow guidelines
-12. **Glossary** – Definitions of extensions and key concepts.
+11. **Appendix I - Database Model** - models.rs table summaries
+12. **Glossary** - Key terms and extension definitions
 
-**Output Requirements**  
+**Output Specifications:**
+- Generate only the markdown content (no external commentary)
+- Include proper fenced code blocks with language tags
+- Provide a complete table of contents with markdown links
+- Ensure all sections are fully populated with real information
+- Skip files that already contain substantial content
+- Base all examples on actual code from the repository
 
-- Produce **only** the markdown content (no surrounding explanations).  
+**Quality Requirements:**
-- Use fenced code blocks with appropriate language tags (`bas` for BASIC scripts, `rust` for Rust snippets).  
+- Accuracy: All information must match the source code
-- Include a **Table of Contents** with markdown links to each chapter.  
+- Completeness: Every required section must be fully developed
-- Ensure the document can be built directly with `mdbook build docs/src`.  
+- Clarity: Explanations should be accessible to BASIC enthusiasts
+- Consistency: Maintain uniform formatting and style throughout
+- Practicality: Include working examples and practical usage tips
 
-**Example Skeleton (to be expanded by the generator)**  
+When ready, output the complete markdown document that satisfies all specifications above.
-
-```markdown
-# GeneralBots User Documentation (mdBook)
-
-## Table of Contents
-- [Run and Talk](#run-and-talk)
-- [About Packages](#about-packages)
-- [gbkb Reference](#gbkb-reference)
-- [gbtheme Reference](#gbtheme-reference)
-- [gbdialog Reference](#gbdialog-reference)
-- [gbapp Reference](#gbapp-reference)
-- [gbot Reference](#gbot-reference)
-- [Tooling](#tooling)
-- [Feature‑Matrix](#feature-matrix)
-- [Contributing](#contributing)
-- [Appendix I – Database Model](#appendix‑i---database-model)
-- [Glossary](#glossary)
-
-## Run and Talk
-```bas
-TALK "Welcome! How can I help you today?"
-HEAR user_input
-```
-*Start the server:* `cargo run --release`
-
-## About Packages
-| Component | Extension | Role |
-|-----------|-----------|------|
-| Dialog scripts | `.gbdialog` | BASIC‑style conversational logic |
-| Knowledge bases | `.gbkb` | Vector‑DB collections |
-| UI themes | `.gbtheme` | CSS/HTML assets |
-| Bot config | `.gbot` | CSV mapping to `UserSession` |
-
-## gbkb Reference
-...
-
-## gbapp Reference
-```rust
-pub fn add_tool_keyword(state: Arc<AppState>, user: UserSession, engine: &mut Engine) {
-    // registration logic …
-}
-```
-
-
-When you are ready, output the full markdown document that satisfies the specifications above.  
-*Do not include any commentary outside the markdown itself.*
-
-# FORMAT Keyword
-
-The **FORMAT** keyword formats numbers, dates, and text for display. Use it when you need a quick, readable representation without writing custom code.
-
-## Syntax
-```basic
-RESULT = FORMAT(VALUE, PATTERN)
-```
-
-## BASIC EXAMPLE
-```basic
-NUMBER = 1234.56
-TEXT = "John"
-DATE = "2024-03-15 14:30:00"
-TALK FORMAT(NUMBER, "n")      ' 1234.56
-TALK FORMAT(TEXT, "Hello @!") ' Hello John!
-TALK FORMAT(DATE, "dd/MM/yyyy") ' 15/03/2024
-```
-- **VALUE** – any number, date string (`YYYY‑MM‑DD HH:MM:SS`), or text.
-- **PATTERN** – a short format string (see tables below).
-
-## Quick Reference
-
-### Numeric Patterns
-| Pattern | Example | Output |
-|---------|---------|--------|
-| `n` | `FORMAT(1234.5, "n")` | `1234.50` |
-| `F` | `FORMAT(1234.5, "F")` | `1234.50` |
-| `f` | `FORMAT(1234.5, "f")` | `1234` |
-| `0%` | `FORMAT(0.85, "0%")` | `85%` |
-| `C2[en]` | `FORMAT(1234.5, "C2[en]")` | `$1,234.50` |
-| `C2[pt]` | `FORMAT(1234.5, "C2[pt]")` | `R$ 1.234,50` |
-
-### Date Patterns
-| Code | Meaning | Example |
-|------|---------|---------|
-| `yyyy` | 4‑digit year | `2024` |
-| `yy`   | 2‑digit year | `24` |
-| `MM`   | month (01‑12) | `03` |
-| `M`    | month (1‑12) | `3` |
-| `dd`   | day (01‑31) | `05` |
-| `d`    | day (1‑31) | `5` |
-| `HH`   | 24‑hour (00‑23) | `14` |
-| `hh`   | 12‑hour (01‑12) | `02` |
-| `mm`   | minutes (00‑59) | `05` |
-| `ss`   | seconds (00‑59) | `09` |
-| `tt`   | AM/PM | `PM` |
-
-**Example**
-```basic
-DATE = "2024-03-15 14:30:25"
-TALK FORMAT(DATE, "dd/MM/yyyy HH:mm")   ' 15/03/2024 14:30
-```
-
-### Text Patterns
-| Placeholder | Effect |
-|-------------|--------|
-| `@` | Insert original text |
-| `!` | Upper‑case |
-| `&` | Lower‑case |
-
-**Example**
-```basic
-NAME = "Maria"
-TALK FORMAT(NAME, "Hello, !")   ' Hello, MARIA
-```
-
-## Practical Tips
-- **Test each pattern** in isolation before combining.
-- **Locale codes** (`en`, `pt`, `fr`, …) go inside `C2[…]` for currency.
-- **Dates must follow** `YYYY‑MM‑DD HH:MM:SS`; otherwise formatting fails.
-- **Combine patterns** by nesting calls:
-  ```basic
-  TALK FORMAT(FORMAT(VALUE, "C2[en]"), "!")   ' $1,234.50 (uppercase not needed here)
-  ```
-
-## Common Pitfalls
-- Using a date pattern on a non‑date string → returns the original string.
-- Forgetting locale brackets (`C2[en]`) → defaults to system locale.
-- Mixing placeholders (`@`, `!`, `&`) in the same pattern – only the last one applies.
-
-Use **FORMAT** whenever you need a clean, user‑friendly output without extra code. It keeps scripts short and readable.