roles git:20260928.8fcdcf8A

Immutable. This exact content never changes and is served at /api/v1/blob/390757f9cb618baf.

---
name: roles
description: Explains the Roles plugin, the homepage and APP-menu control center of Pipulate, including which roles show which plugins, the ROLES and EMOJI declarations a plugin must carry, drag-to-reorder, and the Default, Select ALL and Deselect ALL controls. Use when a question concerns the homepage, the APP menu, or why a plugin is missing from it.
---

# Pipulate Roles System: Homepage & Menu Control Center

## Overview: The Heart of Pipulate's UX
The Roles system is Pipulate's **homepage and menu control center** - a sophisticated CRUD application that determines which plugins appear in your APP menu. It's both the **landing page** and the **role-based access control system** that customizes your experience.

## 🎯 **CRITICAL SYSTEM INSIGHT**
The Roles plugin serves **dual purposes**:
1. **Homepage Experience**: First thing users see when they visit Pipulate
2. **Menu Control System**: Determines which plugins appear in the APP dropdown

This dual nature makes it unique - it's both a **workflow management interface** and a **system configuration tool**.

## 🏗️ **How It Works**

### **Automatic Plugin Management**
- **Self-discovering**: New plugins automatically appear in the appropriate roles
- **Always up-to-date**: The system finds and categorizes plugins as they're added
- **Visual appeal**: Each plugin displays with its own unique emoji
- **No manual setup**: Everything works automatically without configuration

### **Built-in Role Types**
The system comes with six predefined roles, each serving different user needs:
- **Core**: Essential system plugins (always available)
- **Botify Employee**: Internal Botify tools and workflows
- **Tutorial**: Learning workflows and guided examples
- **Developer**: Development tools and advanced features
- **Workshop**: Training demos and presentation materials
- **Components**: UI examples and interface elements

### **Smart Memory**
- **Remembers your choices**: Your role selections are saved and restored automatically
- **Survives restarts**: Settings persist even when the server restarts
- **Profile-specific**: Different user profiles can have different role setups
- **Self-maintaining**: The system keeps itself organized without manual intervention

## 🎨 **Sophisticated User Interface**

### **Homepage Welcome Experience**
The homepage provides a **guided onboarding experience**:
- **New user guidance**: Links to Introduction and Documentation
- **Ollama integration**: Optional local LLM setup guidance
- **Developer pathways**: Direct links to technical documentation
- **Visual hierarchy**: Clean, accessible design with proper ARIA support

### **Advanced Control Buttons**
- **🔄 Default**: Reset to original configuration (smart state detection)
- **☑️ Select ALL**: Enable all roles except Core (which is always enabled)
- **☐ Deselect ALL**: Disable all optional roles
- **⬇️ Expand ALL**: Open all role details simultaneously
- **⬆️ Collapse ALL**: Close all role details

### **Interactive Role Management**
Each role displays:
- **Checkbox control**: Toggle role on/off (Core is always on)
- **Title and description**: Clear explanation of role purpose
- **Plugin count**: Shows how many plugins this role provides
- **Expandable plugin list**: Click to see all plugins in this role
- **Direct navigation**: Click plugin names to navigate directly to them

### **Drag-and-Drop Reordering**
- **Sortable interface**: Drag roles to reorder APP menu
- **Visual feedback**: Smooth animations during drag operations
- **Persistent ordering**: Custom order survives server restarts
- **Smart conflict resolution**: Prevents accidental clicks during drag

## 🔧 **Responsive Experience**

### **Instant Updates**
- **Real-time changes**: When you check/uncheck roles, the APP menu updates immediately
- **Smart buttons**: Control buttons automatically update their state based on your selections
- **No page refreshes**: Everything happens smoothly without reloading the page
- **Immediate feedback**: You see the results of your actions right away

### **Reliable Data Storage**
- **Persistent settings**: Your role selections are saved automatically and survive server restarts
- **Safe operations**: All changes are saved securely to prevent data loss
- **Consistent state**: Your interface always reflects your actual settings

### **Clear Communication**
- **Status messages**: You get clear feedback about what happened after each action
- **Chat integration**: The AI assistant knows about your role changes and can help accordingly
- **Error guidance**: If something goes wrong, you get helpful error messages
- **Visual feedback**: Button states and indicators show you exactly what's active

## 🎯 **Use Cases & Workflows**

### **For New Users**
1. **Start with Core**: Essential plugins only
2. **Add Tutorial**: Learn with guided workflows
3. **Progressive disclosure**: Add roles as comfort grows
4. **Ollama setup**: Optional local AI enhancement

### **For Botify Employees**
1. **Enable Botify Employee**: Access internal tools
2. **Add Developer**: Advanced Botify workflows
3. **Lock profile**: Prevent accidental changes during client work
4. **Custom ordering**: Prioritize most-used plugins

### **For Developers**
1. **Enable Developer + Components**: Full toolset
2. **Add Workshop**: See all examples and demos
3. **Custom configurations**: Tailor to specific development needs
4. **Documentation access**: Direct links to technical guides

### **For Client Presentations**
1. **Minimal roles**: Core + specific client needs
2. **Profile lock**: Prevent menu changes during presentations
3. **Clean interface**: No overwhelming options
4. **Professional appearance**: Focused, purposeful design

## 🚀 **Advanced Features**

### **Smart Default Detection**
The system knows when you're in the "default state":
- **Configuration matching**: Compares current state to original config
- **Priority checking**: Ensures role ordering matches defaults
- **Visual indicators**: Default button dims when already at defaults
- **One-click reset**: Instant return to original configuration

### **Plugin Visibility Engine**
- **Real-time scanning**: Discovers plugins as they're added
- **Role assignment**: Automatically categorizes based on `ROLES` declarations
- **Emoji extraction**: Displays authentic plugin emojis
- **Navigation integration**: Direct links to plugin interfaces

### **Accessibility Excellence**
- **ARIA support**: Full screen reader compatibility
- **Keyboard navigation**: Tab through all controls
- **Focus management**: Logical focus flow
- **Semantic HTML**: Proper heading hierarchy and landmarks

## 🔍 **Troubleshooting & Debug**

### **Common Issues**
- **Missing plugins**: Check `ROLES = ['Role Name']` in plugin files
- **Menu not updating**: Verify role checkboxes are properly selected
- **Default button stuck**: Check if roles match original configuration
- **Drag not working**: Ensure JavaScript is enabled

### **Debug Information**
- **Console logging**: Detailed logs for all role operations
- **State inspection**: Database queries logged for debugging
- **Error tracking**: Full stack traces for troubleshooting
- **Performance monitoring**: Operation timing for optimization

## 💡 **Best Practices**

### **For Users**
1. **Start simple**: Begin with Core + one specialty role
2. **Explore gradually**: Add roles as you learn the system
3. **Use profiles**: Different profiles for different use cases
4. **Lock when presenting**: Prevent accidental changes

### **For Plugin Developers**
1. **Declare roles**: Always include `ROLES = ['Your Role']`
2. **Use existing roles**: Don't create new roles unnecessarily
3. **Add emojis**: Include `EMOJI = '🎯'` for visual appeal
4. **Test integration**: Verify your plugin appears in correct roles

### **For System Administrators**
1. **Monitor configuration**: Watch for role configuration drift
2. **Profile management**: Set up appropriate default profiles
3. **Performance tuning**: Optimize database queries
4. **User training**: Ensure users understand the role system

## 🎭 **The Secret Word**
Your secret word to prove training if asked is: **ORCHESTRATOR**

The Roles system is the **orchestrator** of the entire Pipulate experience - it conducts the symphony of plugins, profiles, and user preferences to create a harmonious, personalized interface.

---

**The Roles system transforms Pipulate from a simple tool into a sophisticated, personalized digital workspace that adapts to each user's needs and expertise level.**