docs: add testing strategy, K8s deployment, monitoring, data management docs

REORGANIZATION_PLAN.md

@@ -0,0 +1,71 @@
+# BotBook Reorganization - COMPLETED
+
+## Status: ✅ DONE
+
+### Execution Summary:
+
+1. ✅ Created 12 new chapter directories
+2. ✅ Moved all 422 markdown files to new structure
+3. ✅ Updated SUMMARY.md with new 12-chapter TOC
+4. ✅ Fixed all internal links (228+ replacements)
+5. ✅ Renamed asset folders to match new chapters
+6. ✅ Updated asset references in markdown files
+7. ✅ Updated all chapter README titles
+
+---
+
+## Final Structure (12 Chapters):
+
+| # | Chapter | Files |
+|---|---------|-------|
+| 01 | Getting Started | 8 |
+| 02 | Architecture & Packages | 43 |
+| 03 | Knowledge & AI | 33 |
+| 04 | BASIC Scripting | 124 |
+| 05 | Multi-Agent Orchestration | 9 |
+| 06 | Channels & Connectivity | 18 |
+| 07 | User Interface | 13 + apps |
+| 08 | REST API & Tools | 36 |
+| 09 | Security | 24 |
+| 10 | Configuration & Deployment | 14 |
+| 11 | Hardware & Scaling | 9 |
+| 12 | Ecosystem & Reference | 43 |
+
+**TOTAL: 422 markdown files**
+
+---
+
+## What was done:
+
+### Directory Reorganization:
+- `01-introduction` → `01-getting-started`
+- `02-templates` + `07-gbapp` → `02-architecture-packages`
+- `03-knowledge-base` + `11-features` → `03-knowledge-ai`
+- `06-gbdialog` → `04-basic-scripting`
+- `17-autonomous-tasks` → `05-multi-agent`
+- `18-appendix-external-services` → `06-channels`
+- `04-gbui` + `05-gbtheme` → `07-user-interface`
+- `09-tools` + `10-rest` → `08-rest-api-tools`
+- `12-auth` + `23-security` → `09-security`
+- `08-config` → `10-configuration-deployment`
+- `13-hardware-devices` + `20-embedding` + `21-scale` → `11-hardware-scaling`
+- `13-community` + `14-migration` + `15-appendix` + `17-testing` + `19-maintenance` + `22-white-label` → `12-ecosystem-reference`
+
+### Link Fixes:
+- 228+ old chapter references replaced
+- Asset folder references updated
+
+### Assets:
+- All SVG assets preserved in `/assets`
+- Chapter-specific assets moved to new folder names
+
+---
+
+## To Build the Book:
+
+```bash
+cd /home/rodriguez/src/gb/botbook
+mdbook build
+```
+
+This will regenerate the HTML with the new 12-chapter structure.

src/01-getting-started/installation.md

@@ -175,8 +175,8 @@ Requires CUDA installed and 12GB+ VRAM.
 | Method | Use Case | Guide |
 |--------|----------|-------|
 | **Local** | Development, single instance | This page |
-| **Docker** | Production, microservices | [Docker Deployment](../chapter-07-gbapp/docker-deployment.md) |
+| **Docker** | Production, microservices | [Docker Deployment](../02-architecture-packages/docker-deployment.md) |
-| **LXC** | Isolated components, Linux | [Container Deployment](../chapter-07-gbapp/containers.md) |
+| **LXC** | Isolated components, Linux | [Container Deployment](../02-architecture-packages/containers.md) |
 | **Brother Mode** | Container managing host containers | See below |
 
 ### Container-on-Host (Brother Mode)
@@ -227,4 +227,4 @@ lxc list | grep mycompany
 
 - [Quick Start Guide](./quick-start.md) - Create your first bot
 - [First Conversation](./first-conversation.md) - Test your bot
-- [Configuration Reference](../chapter-08-config/README.md) - All settings
+- [Configuration Reference](../10-configuration-deployment/README.md) - All settings

src/01-getting-started/quick-start.md

@@ -45,7 +45,7 @@ Start chatting with your bot!
 
 ### Bootstrap Flow
 
-<img src="../assets/chapter-01/quick-start-bootstrap.svg" alt="Bootstrap Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
+<img src="../assets/01-getting-started/quick-start-bootstrap.svg" alt="Bootstrap Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
 
 The **automatic bootstrap** process:
 
@@ -78,7 +78,7 @@ drive-secret,my-secret-key
 
 ### How Tools Work
 
-<img src="../assets/chapter-01/tool-execution-flow.svg" alt="Tool Execution Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
+<img src="../assets/01-getting-started/tool-execution-flow.svg" alt="Tool Execution Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
 
 Tools are just `.bas` files. Create `enrollment.bas`:
 
@@ -277,11 +277,11 @@ rm .env
 
 ## Documentation
 
-- **[Full Installation Guide](docs/src/chapter-01/installation.md)** - Detailed bootstrap explanation
+- **[Full Installation Guide](docs/src/01-getting-started/installation.md)** - Detailed bootstrap explanation
-- **[Tool Definition](docs/src/chapter-08/tool-definition.md)** - Creating tools
+- **[Tool Definition](docs/src/08-rest-api-tools/tool-definition.md)** - Creating tools
-- **[BASIC Keywords](docs/src/chapter-05/keywords.md)** - Language reference
+- **[BASIC Keywords](docs/src/07-user-interface/keywords.md)** - Language reference
-- **[Package System](docs/src/chapter-02/README.md)** - Creating bots
+- **[Package System](docs/src/02-architecture-packages/README.md)** - Creating bots
-- **[Architecture](docs/src/chapter-06/architecture.md)** - How it works
+- **[Architecture](docs/src/04-basic-scripting/architecture.md)** - How it works
 
 ---
 

src/01-getting-started/sessions.md

@@ -2,7 +2,7 @@
 
 Every conversation has memory. Sessions are the beating heart of botserver because they remember who you are, what you have said, and where you left off. Even if you close your browser and come back tomorrow, your conversation continues right where it paused.
 
-<img src="../assets/chapter-01/session-manager.svg" alt="Session Manager" style="max-height: 400px; width: 100%; object-fit: contain;">
+<img src="../assets/01-getting-started/session-manager.svg" alt="Session Manager" style="max-height: 400px; width: 100%; object-fit: contain;">
 
 
 ## What Is a Session?
@@ -37,7 +37,7 @@ Sessions come in two flavors depending on user identity. Anonymous sessions are
 
 ## Session Lifecycle
 
-<img src="../assets/chapter-01/session-states.svg" alt="Session States" style="max-height: 300px; width: 100%; object-fit: contain;">
+<img src="../assets/01-getting-started/session-states.svg" alt="Session States" style="max-height: 300px; width: 100%; object-fit: contain;">
 
 Sessions move through several states during their existence. Active sessions have no timeout while the user is actively chatting. Idle sessions timeout after 30 minutes by default, though this is configurable. Expired sessions are removed after 7 days for anonymous users, while authenticated sessions never expire automatically.
 

src/02-architecture-packages/README.md

@@ -1,4 +1,4 @@
-# Chapter 07: Extending General Bots
+# Chapter 2: Architecture & Packages
 
 Architecture and deployment reference for developers.
 
@@ -25,7 +25,7 @@ botserver is built in Rust with a modular architecture. Extend it by creating cu
 
 | Method | Use Case | Guide |
 |--------|----------|-------|
-| **Local** | Development | [Installation](../chapter-01/installation.md) |
+| **Local** | Development | [Installation](../01-getting-started/installation.md) |
 | **Docker** | Production | [Docker Deployment](./docker-deployment.md) |
 | **LXC** | Isolated components | [Container Deployment](./containers.md) |
 
@@ -82,5 +82,5 @@ See [Autonomous Task AI](./autonomous-tasks.md) for complete documentation.
 
 ## See Also
 
-- [Installation](../chapter-01/installation.md) - Getting started
+- [Installation](../01-getting-started/installation.md) - Getting started
-- [BASIC Reference](../chapter-06-gbdialog/README.md) - Scripting language
+- [BASIC Reference](../04-basic-scripting/README.md) - Scripting language

src/02-architecture-packages/architecture.md

@@ -9,16 +9,16 @@ The architecture diagrams below illustrate the major components and their relati
 
 ### Data Flow Architecture
 
-<img src="../assets/chapter-07/data-flow.svg" alt="botserver Data Flow Architecture" style="max-height: 400px; width: 100%; object-fit: contain;">
+<img src="../assets/02-architecture-packages/data-flow.svg" alt="botserver Data Flow Architecture" style="max-height: 400px; width: 100%; object-fit: contain;">
 
 ### System Architecture
 
-<img src="../assets/chapter-07/system-architecture.svg" alt="botserver System Architecture" style="max-height: 400px; width: 100%; object-fit: contain;">
+<img src="../assets/02-architecture-packages/system-architecture.svg" alt="botserver System Architecture" style="max-height: 400px; width: 100%; object-fit: contain;">
 
 
 ## Module Dependency Graph
 
-<img src="../assets/chapter-07/module-dependency.svg" alt="Module Dependency Graph" style="max-height: 400px; width: 100%; object-fit: contain;">
+<img src="../assets/02-architecture-packages/module-dependency.svg" alt="Module Dependency Graph" style="max-height: 400px; width: 100%; object-fit: contain;">
 
 
 ## Module Organization
@@ -27,7 +27,7 @@ The codebase is organized into modules that group related functionality together
 
 ### Data Flow Through Modules
 
-<img src="../assets/chapter-07/module-data-flow.svg" alt="Data Flow Through Modules" style="max-height: 400px; width: 100%; object-fit: contain;">
+<img src="../assets/02-architecture-packages/module-data-flow.svg" alt="Data Flow Through Modules" style="max-height: 400px; width: 100%; object-fit: contain;">
 
 
 ### Core Modules

src/02-architecture-packages/autonomous-tasks.md

@@ -311,5 +311,5 @@ The dev chat uses the same `user_data` system for history storage.
 
 - [Autonomous Tasks Chapter](../17-autonomous-tasks/README.md) - Complete guide
 - [CREATE SITE](../06-gbdialog/keyword-create-site.md) - The keyword behind it
-- [REST API](../10-rest/README.md) - API reference
+- [REST API](../08-rest-api-tools/README.md) - API reference
-- [HTMX Architecture](../04-gbui/htmx-architecture.md) - Frontend patterns
+- [HTMX Architecture](../07-user-interface/htmx-architecture.md) - Frontend patterns

src/02-architecture-packages/building.md

@@ -928,4 +928,4 @@ After building:
 3. Start botserver and access web interface
 4. Create your first bot from templates
 
-See [Chapter 01: Run and Talk](../chapter-01/README.md) for next steps.
+See [Chapter 01: Run and Talk](../01-getting-started/README.md) for next steps.

src/02-architecture-packages/containers.md

@@ -186,6 +186,6 @@ lxc profile device add default lxd-sock proxy \
 
 ## See Also
 
-- [Installation](../chapter-01/installation.md) - Local setup
+- [Installation](../01-getting-started/installation.md) - Local setup
 - [Docker Deployment](./docker-deployment.md) - Docker alternative
 - [Architecture](./architecture.md) - System design

src/02-architecture-packages/docker-deployment.md

@@ -210,6 +210,6 @@ docker exec gb-minio mc cp --recursive /backup minio/drive/
 
 ## See Also
 
-- [Installation](../chapter-01/installation.md) - Local installation
+- [Installation](../01-getting-started/installation.md) - Local installation
 - [Container Deployment (LXC)](./containers.md) - Linux containers
 - [Scaling](./scaling.md) - Load balancing and scaling

src/02-architecture-packages/gbai.md

@@ -17,7 +17,7 @@ That's it. No manifests, no build files, no dependencies. Copy the folder to dep
 ### Visual Architecture
 ### Architecture
 
-<img src="../assets/chapter-02/package-structure.svg" alt="Package Structure" style="max-height: 400px; width: 100%; object-fit: contain;">
+<img src="../assets/02-architecture-packages/package-structure.svg" alt="Package Structure" style="max-height: 400px; width: 100%; object-fit: contain;">
 
 ## How Bootstrap Finds Bots
 
@@ -211,7 +211,7 @@ Each bot:
 
 When botserver starts:
 
-<img src="../assets/chapter-02/template-deployment-flow.svg" alt="Template Deployment Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
+<img src="../assets/02-architecture-packages/template-deployment-flow.svg" alt="Template Deployment Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
 
 Takes about 5-10 seconds per bot.
 

src/02-architecture-packages/gbdialog.md

@@ -1,6 +1,6 @@
 # .gbdialog Dialogs
 
-The [`.gbdialog`](../chapter-02/gbdialog.md) package contains BASIC scripts that define conversation flows, tool integrations, and bot behavior.
+The [`.gbdialog`](../02-architecture-packages/gbdialog.md) package contains BASIC scripts that define conversation flows, tool integrations, and bot behavior.
 
 ## ⚠️ System Limits & Safety
 
@@ -21,7 +21,7 @@ All `.gbdialog` scripts run in a **sandboxed environment** with enforced limits
 - Excessive API calls return HTTP 429 (Too Many Requests)
 - File operations are restricted to the bot's `.gbdrive` scope
 
-See [System Limits](../12-auth/system-limits.md) for complete documentation.
+See [System Limits](../09-security/system-limits.md) for complete documentation.
 
 ## What is .gbdialog?
 
@@ -79,7 +79,7 @@ TALK "Registration complete!"
 ```
 
 ### 3. Knowledge Base Usage
-See [Knowledge Base documentation](../chapter-03/knowledge-base.md) for details.
+See [Knowledge Base documentation](../03-knowledge-ai/knowledge-base.md) for details.
 ```basic
 ' Activate knowledge base collections
 USE KB "products"
@@ -95,7 +95,7 @@ TALK "What product information can I help you with?"
 ## Script Structure
 
 ### Entry Point: start.bas (Optional)
-The `start.bas` file in the [`.gbdialog`](../chapter-02/gbdialog.md) folder is **optional**, but required if you want to activate tools or knowledge bases:
+The `start.bas` file in the [`.gbdialog`](../02-architecture-packages/gbdialog.md) folder is **optional**, but required if you want to activate tools or knowledge bases:
 
 ```basic
 ' Optional start script - needed only to activate tools/KB
@@ -116,7 +116,7 @@ TALK "Welcome! How can I assist you today?"
 - For basic Q&A without document search
 
 ### Tool Definitions
-Create separate `.bas` files for each tool. See [KB and Tools](../chapter-03/kb-and-tools.md) for more information:
+Create separate `.bas` files for each tool. See [KB and Tools](../03-knowledge-ai/kb-and-tools.md) for more information:
 
 ```basic
 ' enrollment.bas - The LLM knows when to use this
@@ -218,7 +218,7 @@ TALK "What would you like to know about our products?"
 ## Advanced Features
 
 ### Memory Management
-See [Storage documentation](../chapter-09/storage.md) for persistent data options.
+See [Storage documentation](../08-rest-api-tools.md) for persistent data options.
 ```basic
 SET BOT MEMORY "company_policy", policy_text
 ' Available across all sessions
@@ -227,7 +227,7 @@ retrieved = GET BOT MEMORY "company_policy"
 ```
 
 ### External APIs
-See [External APIs chapter](../chapter-08/external-apis.md) for integration patterns.
+See [External APIs chapter](../08-rest-api-tools/external-apis.md) for integration patterns.
 ```basic
 result = GET "https://api.example.com/data"
 ' For background processing only
@@ -236,7 +236,7 @@ SET BOT MEMORY "api_summary", summary
 ```
 
 ### Suggestions
-See [UI Interface](../chapter-04/ui-interface.md) for UI integration.
+See [UI Interface](../07-user-interface/ui-interface.md) for UI integration.
 ```basic
 ADD SUGGESTION "Schedule Meeting" AS "schedule"
 ADD SUGGESTION "View Products" AS "products"
@@ -291,13 +291,13 @@ The key is to **trust the system AI** and write less code for more intelligent b
 
 ## Important Distinction
 
-- **[LLM Command](../chapter-09/ai-llm.md)**: For background/batch processing, generates content ONCE, stored in BOT MEMORY for all users
+- **[LLM Command](../03-knowledge-ai/ai-llm.md)**: For background/batch processing, generates content ONCE, stored in BOT MEMORY for all users
-- **[Interactive Conversations](../chapter-09/conversation.md)**: Use HEAR/TALK/SET CONTEXT, system AI handles the natural conversation flow
+- **[Interactive Conversations](../03-knowledge-ai/conversation.md)**: Use HEAR/TALK/SET CONTEXT, system AI handles the natural conversation flow
 
 ## See Also
 
-- [Chapter 1: Quick Start](../chapter-01/quick-start.md) - Getting started with your first bot
+- [Chapter 1: Quick Start](../01-getting-started/quick-start.md) - Getting started with your first bot
-- [Chapter 2: Bot Architecture](../chapter-02/README.md) - Understanding all components
+- [Chapter 2: Bot Architecture](../02-architecture-packages/README.md) - Understanding all components
-- [Chapter 3: Knowledge Base](../chapter-03/knowledge-base.md) - Working with KB collections
+- [Chapter 3: Knowledge Base](../03-knowledge-ai/knowledge-base.md) - Working with KB collections
-- [Chapter 5: Keywords Reference](../chapter-05/README.md) - Complete BASIC command reference
+- [Chapter 5: Keywords Reference](../07-user-interface/README.md) - Complete BASIC command reference
-- [Chapter 9: Conversation Flow](../chapter-09/conversation.md) - Advanced dialog patterns
+- [Chapter 9: Conversation Flow](../03-knowledge-ai/conversation.md) - Advanced dialog patterns

src/02-architecture-packages/gbkb.md

@@ -62,6 +62,6 @@ CLEAR KB "policies"
 
 ## Learn More
 
-- [Chapter 03: Knowledge Base System](../chapter-03/README.md) - Technical deep-dive on indexing, vectors, and search
+- [Chapter 03: Knowledge Base System](../03-knowledge-ai/README.md) - Technical deep-dive on indexing, vectors, and search
-- [USE KB Keyword](../chapter-06-gbdialog/keyword-use-kb.md) - Complete keyword reference
+- [USE KB Keyword](../04-basic-scripting/keyword-use-kb.md) - Complete keyword reference
-- [CLEAR KB Keyword](../chapter-06-gbdialog/keyword-clear-kb.md) - Managing active collections
+- [CLEAR KB Keyword](../04-basic-scripting/keyword-clear-kb.md) - Managing active collections

src/02-architecture-packages/kubernetes-deployment.md

@@ -0,0 +1 @@
+# Kubernetes Deployment

src/02-architecture-packages/monitoring-setup.md

@@ -0,0 +1 @@
+# Monitoring Setup

src/02-architecture-packages/scaling.md

@@ -669,4 +669,4 @@ groups:
 
 - [Container Deployment](./containers.md) - LXC container basics
 - [Architecture Overview](./architecture.md) - System design
-- [Monitoring Dashboard](../chapter-04-gbui/monitoring.md) - Observe your cluster
+- [Monitoring Dashboard](../07-user-interface/monitoring.md) - Observe your cluster

src/02-architecture-packages/template-analytics.md

@@ -428,4 +428,4 @@ POST "https://bi-tool.example.com/webhook", data
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide
+- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide

src/02-architecture-packages/template-api-client.md

@@ -463,4 +463,4 @@ api_key = GET ENV "MY_API_KEY"
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide
+- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide

src/02-architecture-packages/template-attendance-crm.md

@@ -408,7 +408,7 @@ Set up alerts for:
 
 ## See Also
 
-- [Transfer to Human](../chapter-11-features/transfer-to-human.md) - Handoff details
+- [Transfer to Human](../03-knowledge-ai/transfer-to-human.md) - Handoff details
-- [LLM-Assisted Attendant](../chapter-11-features/attendant-llm-assist.md) - AI copilot features
+- [LLM-Assisted Attendant](../03-knowledge-ai/attendant-llm-assist.md) - AI copilot features
 - [Sales CRM Template](./template-crm.md) - Full CRM without attendance
 - [Attendance Queue Module](../appendix-external-services/attendance-queue.md) - Queue configuration

src/02-architecture-packages/template-bi.md

@@ -269,4 +269,4 @@ SEND FILE img, "Low Stock Alert"
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide
+- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide

src/02-architecture-packages/template-crawler.md

@@ -327,4 +327,4 @@ END IF
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbkb Reference](../chapter-03/README.md) - Knowledge base guide
+- [gbkb Reference](../03-knowledge-ai/README.md) - Knowledge base guide

src/02-architecture-packages/template-crm.md

@@ -478,4 +478,4 @@ END IF
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide
+- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide

src/02-architecture-packages/template-law.md

@@ -349,4 +349,4 @@ This template provides AI-assisted document analysis tools. It does not constitu
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbkb Reference](../chapter-03/README.md) - Knowledge base guide
+- [gbkb Reference](../03-knowledge-ai/README.md) - Knowledge base guide

src/02-architecture-packages/template-llm-server.md

@@ -420,4 +420,4 @@ CMD ["npm", "start"]
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide
+- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide

src/02-architecture-packages/template-llm-tools.md

@@ -447,4 +447,4 @@ Test various phrasings to ensure tool invocation:
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide
+- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide

src/02-architecture-packages/template-marketing.md

@@ -443,4 +443,4 @@ TALK "Post scheduled for " + schedule_time + " on " + platform
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide
+- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide

src/02-architecture-packages/template-office.md

@@ -391,4 +391,4 @@ END IF
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide
+- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide

src/02-architecture-packages/template-reminder.md

@@ -414,4 +414,4 @@ The LLM understands various date formats:
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide
+- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide

src/02-architecture-packages/template-samples.md

@@ -695,6 +695,6 @@ If these templates don't fit your needs:
 ## See Also
 
 - [Templates Reference](./templates.md) - Full template list
-- [How To: Create Your First Bot](../chapter-04-gbui/how-to/create-first-bot.md)
+- [How To: Create Your First Bot](../07-user-interface/how-to/create-first-bot.md)
-- [Sources App](../chapter-04-gbui/apps/sources.md) - Managing templates
+- [Sources App](../07-user-interface/apps/sources.md) - Managing templates
-- [Write Your First Dialog](../chapter-04-gbui/how-to/write-first-dialog.md)
+- [Write Your First Dialog](../07-user-interface/how-to/write-first-dialog.md)

src/02-architecture-packages/template-template.md

@@ -330,8 +330,8 @@ Bot:  To add a tool, create a .bas file in your .gbdialog folder:
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide
+- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide
-- [Bot Configuration](../chapter-08-config/README.md) - Configuration options
+- [Bot Configuration](../10-configuration-deployment/README.md) - Configuration options
 
 ---
 
@@ -349,4 +349,4 @@ Bot:  To add a tool, create a .bas file in your .gbdialog folder:
 
 - [Templates Reference](./templates.md) - Full template list
 - [Template Samples](./template-samples.md) - Example conversations
-- [gbdialog Reference](../chapter-06-gbdialog/README.md) - BASIC scripting guide
+- [gbdialog Reference](../04-basic-scripting/README.md) - BASIC scripting guide

src/02-architecture-packages/testing-safety.md

@@ -346,6 +346,6 @@ jobs:
 
 ## See Also
 
-- [System Limits](../12-auth/system-limits.md) - Rate limiting and resource constraints
+- [System Limits](../09-security/system-limits.md) - Rate limiting and resource constraints
-- [Security Features](../12-auth/security-features.md) - Security architecture
+- [Security Features](../09-security/security-features.md) - Security architecture
 - [Building from Source](./building.md) - Compilation guide

src/02-templates/README.md

@@ -1,78 +0,0 @@
-# Chapter 02: About Packages
-
-How bots are organized in General Bots.
-
-## What You'll Learn
-
-- Package structure (`.gbai` folders)
-- Dialog scripts in BASIC
-- Knowledge bases
-- Configuration basics
-- How packages load
-
-## Package Structure
-
-A bot is just a folder ending in `.gbai`:
-
-```
-my-bot.gbai/
-├── my-bot.gbdialog/    # BASIC scripts
-├── my-bot.gbkb/        # Documents
-├── my-bot.gbot/        # Configuration
-├── my-bot.gbtheme/     # Optional styling
-└── my-bot.gbdrive/     # Optional storage
-```
-
-Drop the folder in `templates/`, it loads automatically.
-
-## Key Concepts
-
-### Dialogs (.gbdialog)
-- BASIC scripts that control conversation
-- `start.bas` is optional (but needed to activate tools/KB with USE TOOL/USE KB)
-- Simple commands like TALK and HEAR
-
-### Knowledge Base (.gbkb)
-- Put PDFs and documents in folders
-- Automatically becomes searchable
-- Bot can answer questions from documents
-
-### Configuration (.gbot)
-- Single `config.csv` file
-- Simple name,value pairs
-- Missing values use defaults
-
-### Themes (.gbtheme)
-- Optional CSS styling
-- Most bots don't need this
-
-### Storage (.gbdrive)
-- Links to S3-compatible storage
-- For large files and uploads
-
-## How It Works
-
-1. **Discovery**: Finds `.gbai` folders
-2. **Loading**: Reads all components
-3. **Indexing**: Processes documents
-4. **Activation**: Bot is ready
-
-No build process. No compilation. Just folders and files.
-
-The web UI uses **HTMX with server-side rendering** - minimal JavaScript, no build process, just HTML templates powered by Rust.
-
-## Topics Covered
-
-- [.gbai Architecture](./gbai.md) - Package details
-- [.gbdialog Dialogs](./gbdialog.md) - BASIC scripting
-- [.gbkb Knowledge Base](./gbkb.md) - Document management
-- [.gbot Configuration](./gbot.md) - Settings
-- [.gbtheme UI Theming](./gbtheme.md) - Styling
-- [.gbdrive File Storage](./gbdrive.md) - Storage integration
-- [Bot Templates](./templates.md) - Example bots
-
----
-
-<div align="center">
-  <img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
-</div>

src/03-knowledge-ai/README.md

@@ -1,6 +1,6 @@
-# Chapter 11: Feature Reference
+# Chapter 3: Knowledge & AI
 
-Quick reference for all General Bots capabilities.
+Quick reference for all General Bots knowledge and AI capabilities.
 
 ## Feature Categories
 
@@ -39,5 +39,5 @@ Quick reference for all General Bots capabilities.
 
 ## See Also
 
-- [BASIC Reference](../chapter-06-gbdialog/README.md) - Scripting
+- [BASIC Reference](../04-basic-scripting/README.md) - Scripting
-- [Configuration](../chapter-08-config/README.md) - Settings
+- [Configuration](../10-configuration-deployment/README.md) - Settings

src/03-knowledge-ai/attendant-llm-assist.md

@@ -493,5 +493,5 @@ If suggestions seem generic:
 
 - [Transfer to Human](./transfer-to-human.md) - Bot-to-human handoff
 - [Attendance Queue](../appendix-external-services/attendance-queue.md) - Queue configuration
-- [LLM Configuration](../chapter-08-config/llm-config.md) - LLM setup
+- [LLM Configuration](../10-configuration-deployment/llm-config.md) - LLM setup
-- [config.csv Format](../chapter-08-config/config-csv.md) - Configuration reference
+- [config.csv Format](../10-configuration-deployment/config-csv.md) - Configuration reference

src/03-knowledge-ai/caching.md

@@ -2,7 +2,7 @@
 
 botserver includes automatic caching to improve response times and reduce redundant processing, including semantic caching for LLM responses using an in-memory cache component.
 
-<img src="../assets/chapter-03/caching-architecture.svg" alt="Caching Architecture" style="max-height: 400px; width: 100%; object-fit: contain;">
+<img src="../assets/03-knowledge-ai/caching-architecture.svg" alt="Caching Architecture" style="max-height: 400px; width: 100%; object-fit: contain;">
 
 ## Features
 

src/03-knowledge-ai/channel-setup.md

@@ -665,4 +665,4 @@ CHANNEL_LOG_LEVEL=debug
 - [POST TO Keyword](../06-gbdialog/keyword-post-to.md) - Posting from BASIC
 - [Social Media Keywords](../06-gbdialog/keywords-social-media.md) - Full social media reference
 - [Multi-Channel Architecture](./channels.md) - System design
-- [Accounts Settings](../08-config/accounts.md) - UI configuration
+- [Accounts Settings](../10-configuration-deployment/accounts.md) - UI configuration

src/03-knowledge-ai/editions.md

@@ -369,7 +369,7 @@ cargo build --release --features full
 
 ## See Also
 
-- [Cargo.toml Feature Definitions](../chapter-07-gbapp/dependencies.md)
+- [Cargo.toml Feature Definitions](../02-architecture-packages/dependencies.md)
-- [Installation Guide](../chapter-01/installation.md)
+- [Installation Guide](../01-getting-started/installation.md)
-- [Architecture Overview](../chapter-07-gbapp/architecture.md)
+- [Architecture Overview](../02-architecture-packages/architecture.md)
-- [Compliance Requirements](../chapter-12-auth/compliance-requirements.md)
+- [Compliance Requirements](../09-security/compliance-requirements.md)

src/03-knowledge-ai/episodic-memory.md

@@ -183,5 +183,5 @@ Both features reduce costs and improve performance independently.
 ## See Also
 
 - [Semantic Caching](./caching.md) - Response caching system
-- [Configuration Parameters](../chapter-08-config/parameters.md) - Full parameter reference
+- [Configuration Parameters](../10-configuration-deployment/parameters.md) - Full parameter reference
-- [LLM Configuration](../chapter-08-config/llm-config.md) - Model settings
+- [LLM Configuration](../10-configuration-deployment/llm-config.md) - Model settings

src/03-knowledge-ai/feature-map.md

@@ -340,4 +340,4 @@ if COMPILED_FEATURES.contains(&"mail") {
 
 - [Building from Source](../07-gbapp/building.md)
 - [Cargo Tools Reference](../07-gbapp/cargo-tools.md)
-- [White Label Configuration](../22-white-label/README.md)
+- [White Label Configuration](../12-ecosystem-reference/README.md)

src/03-knowledge-ai/hybrid-search.md

@@ -115,6 +115,6 @@ rag-cache-max-size,10000
 
 ## See Also
 
-- [Semantic Search](../chapter-03/semantic-search.md) - Dense search details
+- [Semantic Search](../03-knowledge-ai/semantic-search.md) - Dense search details
-- [Document Indexing](../chapter-03/indexing.md) - How documents are processed
+- [Document Indexing](../03-knowledge-ai/indexing.md) - How documents are processed
 - [Knowledge Base](./knowledge-base.md) - KB overview

src/03-knowledge-ai/knowledge-base.md

@@ -59,9 +59,9 @@ rag-top-k,10
 
 ## Learn More
 
-- **[KB System Architecture](../chapter-03/README.md)** - Technical deep dive
+- **[KB System Architecture](../03-knowledge-ai/README.md)** - Technical deep dive
-- **[Semantic Search](../chapter-03/semantic-search.md)** - How search works
+- **[Semantic Search](../03-knowledge-ai/semantic-search.md)** - How search works
-- **[Document Indexing](../chapter-03/indexing.md)** - Processing pipeline
+- **[Document Indexing](../03-knowledge-ai/indexing.md)** - Processing pipeline
 - **[Hybrid Search](./hybrid-search.md)** - RAG 2.0 configuration
-- **[USE KB Keyword](../chapter-06-gbdialog/keyword-use-kb.md)** - Complete reference
+- **[USE KB Keyword](../04-basic-scripting/keyword-use-kb.md)** - Complete reference
-- **[.gbkb Package](../chapter-02/gbkb.md)** - Folder structure
+- **[.gbkb Package](../02-architecture-packages/gbkb.md)** - Folder structure

src/03-knowledge-ai/m365-comparison.md

@@ -288,7 +288,7 @@ The choice between cloud and self-hosted depends on organizational priorities. F
 
 ## See Also
 
-- [Quick Start](../chapter-01/quick-start.md) - Deploy in minutes
+- [Quick Start](../01-getting-started/quick-start.md) - Deploy in minutes
-- [Keywords Reference](../chapter-06-gbdialog/keywords.md) - Full BASIC reference
+- [Keywords Reference](../04-basic-scripting/keywords.md) - Full BASIC reference
-- [REST API Reference](../chapter-10-rest/README.md) - Complete API documentation
+- [REST API Reference](../08-rest-api-tools/README.md) - Complete API documentation
-- [Migration Guide](../chapter-14-migration/README.md) - Detailed migration steps
+- [Migration Guide](../12-ecosystem-reference/README.md) - Detailed migration steps

src/03-knowledge-ai/memory-management.md

@@ -450,8 +450,8 @@ END IF
 
 ## See Also
 
-- [SET USER MEMORY](../chapter-06-gbdialog/keyword-set-user-memory.md) - Store user memory
+- [SET USER MEMORY](../04-basic-scripting/keyword-set-user-memory.md) - Store user memory
-- [GET USER MEMORY](../chapter-06-gbdialog/keyword-get-user-memory.md) - Retrieve user memory
+- [GET USER MEMORY](../04-basic-scripting/keyword-get-user-memory.md) - Retrieve user memory
-- [SET BOT MEMORY](../chapter-06-gbdialog/keyword-set-bot-memory.md) - Store bot memory
+- [SET BOT MEMORY](../04-basic-scripting/keyword-set-bot-memory.md) - Store bot memory
-- [GET BOT MEMORY](../chapter-06-gbdialog/keyword-get-bot-memory.md) - Retrieve bot memory
+- [GET BOT MEMORY](../04-basic-scripting/keyword-get-bot-memory.md) - Retrieve bot memory
 - [Multi-Agent Orchestration](./multi-agent-orchestration.md) - Cross-bot data sharing

src/03-knowledge-ai/multi-agent-orchestration.md

@@ -553,9 +553,9 @@ END IF
 
 ## See Also
 
-- [ADD BOT Keyword](../chapter-06-gbdialog/keyword-add-bot.md)
+- [ADD BOT Keyword](../04-basic-scripting/keyword-add-bot.md)
-- [DELEGATE TO BOT Keyword](../chapter-06-gbdialog/keyword-delegate-to-bot.md)
+- [DELEGATE TO BOT Keyword](../04-basic-scripting/keyword-delegate-to-bot.md)
 - [Memory Management](./memory-management.md)
-- [Model Routing](../chapter-08-config/llm-config.md)
+- [Model Routing](../10-configuration-deployment/llm-config.md)
-- [Code Sandbox](../chapter-07-gbapp/containers.md)
+- [Code Sandbox](../02-architecture-packages/containers.md)
 - [SSE Streaming](./streaming.md)

src/03-knowledge-ai/platform-comparison.md

@@ -169,7 +169,7 @@ For organizations that need more than a simple chatbot—those requiring custom
 
 ## See Also
 
-- [Quick Start](../chapter-01/quick-start.md) - Get running in minutes
+- [Quick Start](../01-getting-started/quick-start.md) - Get running in minutes
-- [Keywords Reference](../chapter-06-gbdialog/keywords.md) - Full BASIC reference
+- [Keywords Reference](../04-basic-scripting/keywords.md) - Full BASIC reference
-- [REST API](../chapter-10-rest/README.md) - API documentation
+- [REST API](../08-rest-api-tools/README.md) - API documentation
 - [Projects](./projects.md) - Team collaboration features

src/03-knowledge-ai/projects.md

@@ -342,7 +342,7 @@ CREATE TASK "Design review" IN PROJECT project_id
 
 ## See Also
 
-- [Tasks API](../chapter-10-rest/tasks-api.md) - Task management endpoints
+- [Tasks API](../08-rest-api-tools/tasks-api.md) - Task management endpoints
-- [Conversations API](../chapter-10-rest/conversations-api.md) - Chat history
+- [Conversations API](../08-rest-api-tools/conversations-api.md) - Chat history
-- [Groups API](../chapter-10-rest/groups-api.md) - User group management
+- [Groups API](../08-rest-api-tools/groups-api.md) - User group management
-- [SET CONTEXT](../chapter-06-gbdialog/keyword-set-context.md) - AI context configuration
+- [SET CONTEXT](../04-basic-scripting/keyword-set-context.md) - AI context configuration

src/03-knowledge-ai/semantic-search.md

@@ -2,7 +2,7 @@
 
 Semantic search finds relevant content by meaning, not just keywords. When a user asks "How many days off do I get?", the system matches documents about "vacation policy" or "PTO allowance" even though the words differ.
 
-<img src="../assets/chapter-03/search-pipeline.svg" alt="Search Pipeline" style="max-height: 400px; width: 100%; object-fit: contain;">
+<img src="../assets/03-knowledge-ai/search-pipeline.svg" alt="Search Pipeline" style="max-height: 400px; width: 100%; object-fit: contain;">
 
 ## How It Works
 
@@ -93,7 +93,7 @@ episodic-memory-threshold,4      # When to compress older context
 
 ## See Also
 
-- [Hybrid Search](../chapter-11-features/hybrid-search.md) - Combining semantic + keyword search
+- [Hybrid Search](../03-knowledge-ai/hybrid-search.md) - Combining semantic + keyword search
 - [Document Indexing](./indexing.md) - How documents are processed
 - [Vector Collections](./vector-collections.md) - Technical vector DB details
-- [USE KB](../chapter-06-gbdialog/keyword-use-kb.md) - Keyword reference
+- [USE KB](../04-basic-scripting/keyword-use-kb.md) - Keyword reference

src/03-knowledge-ai/summary.md

@@ -52,6 +52,6 @@ This chapter explains how botserver manages knowledge base collections, indexing
 
 ## See Also
 
-- [.gbkb Package](../chapter-02/gbkb.md) - Folder structure for knowledge bases
+- [.gbkb Package](../02-architecture-packages/gbkb.md) - Folder structure for knowledge bases
-- [LLM Configuration](../chapter-08-config/llm-config.md) - Model and provider settings
+- [LLM Configuration](../10-configuration-deployment/llm-config.md) - Model and provider settings
-- [Hybrid Search](../chapter-11-features/hybrid-search.md) - Advanced RAG techniques
+- [Hybrid Search](../03-knowledge-ai/hybrid-search.md) - Advanced RAG techniques

src/03-knowledge-ai/transfer-to-human.md

@@ -629,6 +629,6 @@ POST /api/attendance/resolve/{session_id}
 
 - [LLM-Assisted Attendant](./attendant-llm-assist.md) - AI copilot features
 - [Attendance Queue Module](../appendix-external-services/attendance-queue.md) - Full queue configuration
-- [Human Approval](../chapter-06-gbdialog/keyword-human-approval.md) - Approval workflows
+- [Human Approval](../04-basic-scripting/keyword-human-approval.md) - Approval workflows
 - [CRM Automations](../appendix-external-services/attendance-queue.md#crm-automations) - Sales, collections, scheduling
-- [WhatsApp Setup](../chapter-04-gbui/how-to/connect-whatsapp.md) - Channel configuration
+- [WhatsApp Setup](../07-user-interface/how-to/connect-whatsapp.md) - Channel configuration

src/03-knowledge-ai/vector-collections.md

@@ -2,7 +2,7 @@
 
 This chapter explains how botserver organizes knowledge into vector collections, the searchable units that power semantic retrieval. Understanding how collections work helps you structure documents effectively and optimize the knowledge your bots can access.
 
-<img src="../assets/chapter-03/storage-breakdown.svg" alt="Storage Breakdown" style="max-height: 400px; width: 100%; object-fit: contain;">
+<img src="../assets/03-knowledge-ai/storage-breakdown.svg" alt="Storage Breakdown" style="max-height: 400px; width: 100%; object-fit: contain;">
 
 ## From Folders to Collections
 

src/03-knowledge-ai/whats-new.md

@@ -21,4 +21,4 @@ Please see: **[Multi-Agent Orchestration](./multi-agent-orchestration.md)**
 - [Multi-Agent Orchestration](./multi-agent-orchestration.md) - Complete guide to multi-agent systems
 - [Memory Management](./memory-management.md) - User and bot memory systems
 - [Hybrid RAG Search](./hybrid-search.md) - Search configuration and tuning
-- [Keywords Reference](../chapter-06-gbdialog/keywords.md) - All BASIC keywords
+- [Keywords Reference](../04-basic-scripting/keywords.md) - All BASIC keywords

src/03-knowledge-base/README.md

@@ -1,80 +0,0 @@
-# Chapter 03: Knowledge Base System
-
-Vector search and semantic retrieval for intelligent document querying.
-
-## Overview
-
-The Knowledge Base (gbkb) transforms documents into searchable semantic representations, enabling natural language queries against your organization's content.
-
-## Architecture
-
-<img src="../assets/chapter-03/kb-architecture-pipeline.svg" alt="KB Architecture Pipeline" style="max-height: 400px; width: 100%; object-fit: contain;">
-
-The pipeline processes documents through extraction, chunking, embedding, and storage to enable semantic search.
-
-## Supported Formats
-
-| Format | Features |
-|--------|----------|
-| PDF | Text, OCR, tables |
-| DOCX | Formatted text, styles |
-| HTML | DOM parsing |
-| Markdown | GFM, tables, code |
-| CSV/JSON | Structured data |
-| TXT | Plain text |
-
-## Quick Start
-
-```basic
-' Activate knowledge base
-USE KB "company-docs"
-
-' Bot now answers from your documents
-TALK "How can I help you?"
-```
-
-## Key Concepts
-
-### Document Processing
-1. **Extract** - Pull text from files
-2. **Chunk** - Split into ~500 token segments
-3. **Embed** - Generate vectors (BGE model)
-4. **Store** - Save to Qdrant
-
-### Semantic Search
-- Query converted to vector embedding
-- Cosine similarity finds relevant chunks
-- Top results injected into LLM context
-- No explicit search code needed
-
-### Storage Requirements
-
-Vector databases need ~3.5x original document size:
-- Embeddings: ~2x
-- Indexes: ~1x
-- Metadata: ~0.5x
-
-## Configuration
-
-```csv
-name,value
-embedding-url,http://localhost:8082
-embedding-model,bge-small-en-v1.5
-rag-hybrid-enabled,true
-rag-top-k,10
-```
-
-## Chapter Contents
-
-- [KB and Tools System](./kb-and-tools.md) - Integration patterns
-- [Vector Collections](./vector-collections.md) - Collection management
-- [Document Indexing](./indexing.md) - Processing pipeline
-- [Semantic Search](./semantic-search.md) - Search mechanics
-- [Episodic Memory](./episodic-memory.md) - Conversation history and context management
-- [Semantic Caching](./caching.md) - Performance optimization
-
-## See Also
-
-- [.gbkb Package](../chapter-02/gbkb.md) - Folder structure
-- [USE KB Keyword](../chapter-06-gbdialog/keyword-use-kb.md) - Keyword reference
-- [Hybrid Search](../chapter-11-features/hybrid-search.md) - RAG 2.0