diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 9015755e6..3423ac5e5 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -37,12 +37,14 @@
# Part IV - User Interface
- [Chapter 04: .gbui Interface Reference](./chapter-04-gbui/README.md)
+ - [Suite User Manual](./chapter-04-gbui/suite-manual.md)
- [UI Structure](./chapter-04-gbui/ui-structure.md)
- [default.gbui - Full Desktop](./chapter-04-gbui/default-gbui.md)
- [single.gbui - Simple Chat](./chapter-04-gbui/single-gbui.md)
- [Console Mode](./chapter-04-gbui/console-mode.md)
- [Player - Media Viewer](./chapter-04-gbui/player.md)
- [Monitoring Dashboard](./chapter-04-gbui/monitoring.md)
+ - [HTMX Architecture](./chapter-04-gbui/htmx-architecture.md)
# Part V - Themes and Styling
diff --git a/docs/src/chapter-04-gbui/htmx-architecture.md b/docs/src/chapter-04-gbui/htmx-architecture.md
index 8c4526e72..00ffc3d84 100644
--- a/docs/src/chapter-04-gbui/htmx-architecture.md
+++ b/docs/src/chapter-04-gbui/htmx-architecture.md
@@ -1 +1,535 @@
# HTMX Architecture
+
+## Overview
+
+General Bots Suite uses **HTMX** for its user interface - a modern approach that delivers the interactivity of a single-page application without the complexity of JavaScript frameworks like React, Vue, or Angular.
+
+> **Why HTMX?**
+> - Simpler code, easier maintenance
+> - Server-rendered HTML (fast, SEO-friendly)
+> - Progressive enhancement
+> - No build step required
+> - Smaller payload than SPA frameworks
+
+---
+
+## How HTMX Works
+
+### Traditional Web vs HTMX
+
+**Traditional (Full Page Reload):**
+```
+User clicks → Browser requests full page → Server returns entire HTML → Browser replaces everything
+```
+
+**HTMX (Partial Update):**
+```
+User clicks → HTMX requests fragment → Server returns HTML snippet → HTMX updates only that part
+```
+
+### Core Concept
+
+HTMX extends HTML with attributes that define:
+1. **What triggers the request** (`hx-trigger`)
+2. **Where to send it** (`hx-get`, `hx-post`)
+3. **What to update** (`hx-target`)
+4. **How to update it** (`hx-swap`)
+
+---
+
+## HTMX Attributes Reference
+
+### Request Attributes
+
+| Attribute | Purpose | Example |
+|-----------|---------|---------|
+| `hx-get` | GET request to URL | `hx-get="/api/tasks"` |
+| `hx-post` | POST request | `hx-post="/api/tasks"` |
+| `hx-put` | PUT request | `hx-put="/api/tasks/1"` |
+| `hx-patch` | PATCH request | `hx-patch="/api/tasks/1"` |
+| `hx-delete` | DELETE request | `hx-delete="/api/tasks/1"` |
+
+### Trigger Attributes
+
+| Attribute | Purpose | Example |
+|-----------|---------|---------|
+| `hx-trigger` | Event that triggers request | `hx-trigger="click"` |
+| | Load on page | `hx-trigger="load"` |
+| | Periodic polling | `hx-trigger="every 5s"` |
+| | Keyboard event | `hx-trigger="keyup changed delay:300ms"` |
+
+### Target & Swap Attributes
+
+| Attribute | Purpose | Example |
+|-----------|---------|---------|
+| `hx-target` | Element to update | `hx-target="#results"` |
+| `hx-swap` | How to insert content | `hx-swap="innerHTML"` |
+| | | `hx-swap="outerHTML"` |
+| | | `hx-swap="beforeend"` |
+| | | `hx-swap="afterbegin"` |
+
+---
+
+## Suite Architecture
+
+### File Structure
+
+```
+ui/suite/
+├── index.html # Main entry point with navigation
+├── default.gbui # Full desktop layout
+├── single.gbui # Simple chat layout
+├── designer.html # Visual dialog designer
+├── editor.html # Code editor
+├── settings.html # User settings
+├── css/
+│ └── app.css # Global styles
+├── js/
+│ ├── layout.js # Layout management
+│ └── theme-manager.js # Theme switching
+├── chat/
+│ ├── chat.html # Chat component
+│ └── chat.css # Chat styles
+├── drive/
+│ └── index.html # File manager
+├── tasks/
+│ ├── tasks.html # Task manager
+│ └── tasks.css # Task styles
+├── mail/
+│ ├── mail.html # Email client
+│ └── mail.css # Email styles
+├── calendar/
+│ └── calendar.html # Calendar view
+├── meet/
+│ ├── meet.html # Video meetings
+│ └── meet.css # Meeting styles
+├── paper/
+│ └── paper.html # Document editor
+├── research/
+│ └── research.html # AI search
+├── analytics/
+│ └── analytics.html # Dashboards
+├── sources/
+│ └── index.html # Prompts & templates
+├── tools/
+│ └── compliance.html # Security scanner
+└── monitoring/
+ └── ... # System monitoring
+```
+
+### Loading Pattern
+
+The Suite uses **lazy loading** - components load only when needed:
+
+```html
+
+
+ Chat
+
+```
+
+When user clicks "Chat":
+1. HTMX requests `/ui/suite/chat/chat.html`
+2. Server returns the Chat HTML fragment
+3. HTMX inserts it into `#main-content`
+4. Only Chat code loads, not entire app
+
+---
+
+## Component Patterns
+
+### 1. Load on Page View
+
+```html
+
+
+```
+
+### 2. Form Submission
+
+```html
+
+
+```
+
+**Flow:**
+1. User types task, clicks Add
+2. HTMX POSTs form data to `/api/tasks`
+3. Server creates task, returns HTML for new task item
+4. HTMX inserts at beginning of `#task-list`
+5. Form resets automatically
+
+### 3. Click Actions
+
+```html
+
+
+ Review quarterly report
+
+ 🗑
+
+
+```
+
+### 4. Search with Debounce
+
+```html
+
+🔄
+
+```
+
+**Flow:**
+1. User types in search box
+2. After 300ms of no typing, HTMX sends request
+3. Spinner shows during request
+4. Results replace `#search-results` content
+
+### 5. Real-time Updates (WebSocket)
+
+```html
+
+
+```
+
+**Flow:**
+1. WebSocket connects on load
+2. History loads via HTMX GET
+3. New messages sent via WebSocket (`ws-send`)
+4. Server pushes updates to all connected clients
+
+### 6. Polling for Updates
+
+```html
+
+
+
+
+```
+
+### 7. Infinite Scroll
+
+```html
+
+
+
+
+
+ Loading more...
+
+
+ Review quarterly report
+
+
+ Update documentation
+
+```
+
+### Swap Strategies
+
+| Strategy | Effect |
+|----------|--------|
+| `innerHTML` | Replace contents of target |
+| `outerHTML` | Replace entire target element |
+| `beforeend` | Append inside target (at end) |
+| `afterbegin` | Prepend inside target (at start) |
+| `beforebegin` | Insert before target |
+| `afterend` | Insert after target |
+| `delete` | Delete target element |
+| `none` | Don't swap (for side effects) |
+
+---
+
+## CSS Integration
+
+### Loading Indicators
+
+```css
+/* Hidden by default */
+.htmx-indicator {
+ display: none;
+}
+
+/* Shown during request */
+.htmx-request .htmx-indicator {
+ display: inline-block;
+}
+
+/* Or when indicator IS the requesting element */
+.htmx-request.htmx-indicator {
+ display: inline-block;
+}
+```
+
+### Transition Effects
+
+```css
+/* Fade in new content */
+.htmx-settling {
+ opacity: 0;
+}
+
+.htmx-swapping {
+ opacity: 0;
+ transition: opacity 0.2s ease-out;
+}
+```
+
+---
+
+## JavaScript Integration
+
+### HTMX Events
+
+```javascript
+// After any HTMX swap
+document.body.addEventListener('htmx:afterSwap', (e) => {
+ console.log('Content updated:', e.detail.target);
+});
+
+// Before request
+document.body.addEventListener('htmx:beforeRequest', (e) => {
+ console.log('Sending request to:', e.detail.pathInfo.path);
+});
+
+// After request completes
+document.body.addEventListener('htmx:afterRequest', (e) => {
+ if (e.detail.successful) {
+ console.log('Request succeeded');
+ } else {
+ console.error('Request failed');
+ }
+});
+
+// On WebSocket message
+document.body.addEventListener('htmx:wsAfterMessage', (e) => {
+ console.log('Received:', e.detail.message);
+});
+```
+
+### Triggering HTMX from JavaScript
+
+```javascript
+// Trigger an HTMX request programmatically
+htmx.trigger('#task-list', 'load');
+
+// Make an AJAX request
+htmx.ajax('GET', '/api/tasks', {
+ target: '#task-list',
+ swap: 'innerHTML'
+});
+
+// Process new HTMX content
+htmx.process(document.getElementById('new-content'));
+```
+
+---
+
+## Designer Page Architecture
+
+The visual dialog designer uses a hybrid approach:
+
+### Canvas Management (JavaScript)
+```javascript
+// State managed in JavaScript
+const state = {
+ nodes: new Map(), // Node data
+ connections: [], // Connections between nodes
+ zoom: 1, // Canvas zoom level
+ pan: { x: 0, y: 0 } // Canvas position
+};
+```
+
+### File Operations (HTMX)
+```html
+
+
+ Open File
+
+
+
+
+ Save
+
+```
+
+### Drag-and-Drop (JavaScript)
+```javascript
+// Toolbox items are draggable
+toolboxItems.forEach(item => {
+ item.addEventListener('dragstart', (e) => {
+ e.dataTransfer.setData('nodeType', item.dataset.nodeType);
+ });
+});
+
+// Canvas handles drop
+canvas.addEventListener('drop', (e) => {
+ const nodeType = e.dataTransfer.getData('nodeType');
+ createNode(nodeType, e.clientX, e.clientY);
+});
+```
+
+---
+
+## Performance Considerations
+
+### 1. Minimize Request Size
+
+Return only what's needed:
+```html
+
+...
+
+
+
+```
+
+### 2. Use Appropriate Triggers
+
+```html
+
+hx-trigger="every 30s"
+hx-trigger="every 1s"
+
+
+hx-trigger="keyup changed delay:300ms"
+hx-trigger="keyup"
+```
+
+### 3. Lazy Load Heavy Content
+
+```html
+
+
+
+```
+
+### 4. Use `hx-boost` for Navigation
+
+```html
+
+
+ Page 1
+ Page 2
+
+```
+
+---
+
+## Security
+
+### CSRF Protection
+
+HTMX automatically includes CSRF tokens:
+
+```html
+
+ ${field.label}
+
+
+ `;
+ } else if (field.type === 'select') {
+ const options = field.options.map(opt =>
+ `${opt} `
+ ).join('');
+ fieldsHtml += `
+
+ ${field.label}
+ ${options}
+
+ `;
+ } else {
+ fieldsHtml += `
+
+ ${field.label}
+
+ `;
+ }
+ });
+
+ let portsHtml = '';
+ if (template.hasInput) {
+ portsHtml += `
`;
+ }
+ if (template.hasOutput) {
+ portsHtml += `
`;
+ }
+ if (template.hasOutputTrue) {
+ portsHtml += `
`;
+ }
+ if (template.hasOutputFalse) {
+ portsHtml += `
`;
+ }
+
+ const nodeEl = document.createElement('div');
+ nodeEl.className = 'node';
+ nodeEl.id = node.id;
+ nodeEl.style.left = node.x + 'px';
+ nodeEl.style.top = node.y + 'px';
+ nodeEl.innerHTML = `
+
+
+ ${fieldsHtml}
+
+ ${portsHtml}
+ `;
+
+ // Make draggable
+ nodeEl.addEventListener('mousedown', (e) => {
+ if (e.target.classList.contains('node-port')) return;
+ selectNode(node.id);
+ startNodeDrag(e, node);
+ });
+
+ // Field change handlers
+ nodeEl.querySelectorAll('.node-field-input, .node-field-select').forEach(input => {
+ input.addEventListener('change', (e) => {
+ node.fields[e.target.dataset.field] = e.target.value;
+ saveToHistory();
+ });
+ });
+
+ // Port handlers for connections
+ nodeEl.querySelectorAll('.node-port').forEach(port => {
+ port.addEventListener('mousedown', (e) => {
+ e.stopPropagation();
+ startConnection(node.id, port.dataset.port);
+ });
+ port.addEventListener('mouseup', (e) => {
+ e.stopPropagation();
+ endConnection(node.id, port.dataset.port);
+ });
+ });
+
+ document.getElementById('canvas-inner').appendChild(nodeEl);
+ }
+
+ function getNodeIcon(type) {
+ const icons = {
+ 'TALK': '
+
+
+
+ ${paths}
+ `;
+ }
+
+ // Properties Panel
+ function updatePropertiesPanel() {
+ const content = document.getElementById('properties-content');
+ const empty = document.getElementById('properties-empty');
+
+ if (!state.selectedNode) {
+ content.style.display = 'none';
+ empty.style.display = 'block';
+ return;
+ }
+
+ const node = state.nodes.get(state.selectedNode);
+ if (!node) return;
+
+ const template = nodeTemplates[node.type];
+ empty.style.display = 'none';
+ content.style.display = 'block';
+
+ let html = `
+
+
Node Info
+
+ Type
+
+
+ ID
+
+
+
Properties
+ `;
+
+ template.fields.forEach(field => {
+ const value = node.fields[field.name] || '';
+ if (field.type === 'textarea') {
+ html += `
+
+ ${field.label}
+
+
+ `;
+ } else {
+ html += `
+
+ ${field.label}
+
+ `;
+ }
+ });
+
+ html += '
+