snow-flow 4.5.3 → 4.5.5

package/CLAUDE.md

@@ -582,28 +582,72 @@ Snow-Flow includes 18 specialized MCP servers, each providing comprehensive Serv
 - Performance Analytics setup
 - CAB meeting management
 
-### 14. ServiceNow Flow, Workspace & Mobile Server
-**Purpose:** Flow Designer, Workspace configuration, and Mobile app management
+### 14. ServiceNow Flow, Workspace & Mobile Server + UI Builder
+**Purpose:** Flow Designer, Agent Workspace configuration, Mobile app management, and complete UI Builder integration
 
-**Key Tools:**
+**Flow Designer Tools:**
 - `snow_list_flows` - List and discover Flow Designer flows
 - `snow_execute_flow` - Execute existing flows programmatically
 - `snow_get_flow_execution_status` - Monitor flow execution status
 - `snow_get_flow_execution_history` - View flow execution history
 - `snow_get_flow_details` - Get detailed flow configuration
 - `snow_import_flow_from_xml` - Import flows from XML (only programmatic creation method)
-- `snow_create_workspace` - Create workspaces
-- `snow_configure_mobile_app` - Configure mobile app
+
+**Agent Workspace Tools:**
+- `snow_create_workspace` - Create agent workspace configurations
+- `snow_create_workspace_tab` - Add custom workspace tabs
+- `snow_create_contextual_panel` - Add contextual side panels
+- `snow_discover_workspaces` - Find all workspace configurations
+
+**Mobile App Tools:**
+- `snow_configure_mobile_app` - Configure mobile applications
 - `snow_send_push_notification` - Send push notifications
 - `snow_configure_offline_sync` - Configure offline sync
 
+**🆕 COMPLETE UI BUILDER INTEGRATION (15 NEW TOOLS!):**
+
+**UI Builder Page Management (sys_ux_page):**
+- `snow_create_uib_page` - Create UI Builder pages with automatic routing
+- `snow_update_uib_page` - Update page configuration and metadata
+- `snow_delete_uib_page` - Delete pages with comprehensive dependency validation
+- `snow_discover_uib_pages` - Find all UI Builder pages with filtering
+
+**UI Builder Component Library (sys_ux_lib_*):**
+- `snow_create_uib_component` - Create custom UI components with source code
+- `snow_update_uib_component` - Update component definitions and source
+- `snow_discover_uib_components` - Browse ServiceNow built-in + custom components
+- `snow_clone_uib_component` - Clone and modify existing components
+
+**UI Builder Data Integration (sys_ux_data_broker):**
+- `snow_create_uib_data_broker` - Connect ServiceNow tables/scripts/REST to pages
+- `snow_configure_uib_data_broker` - Update queries, caching, and refresh settings
+
+**UI Builder Layout Management (sys_ux_page_element):**
+- `snow_add_uib_page_element` - Add components to pages with full configuration
+- `snow_update_uib_page_element` - Update component properties and positioning  
+- `snow_remove_uib_page_element` - Remove elements with dependency checking
+
+**UI Builder Advanced Features:**
+- `snow_create_uib_page_registry` - Configure URL routing and access control
+- `snow_discover_uib_routes` - Find all page routes with security info
+- `snow_create_uib_client_script` - Add client-side JavaScript for pages
+- `snow_create_uib_client_state` - Manage page state and persistence
+- `snow_create_uib_event` - Create custom events for components
+- `snow_analyze_uib_page_performance` - Performance analysis and optimization
+- `snow_validate_uib_page_structure` - Structure validation and best practices
+- `snow_discover_uib_page_usage` - Usage analytics and complexity scoring
+
 **Important:** Flow creation is only supported through Flow Designer UI, not programmatically
 
 **Features:**
 - Flow Designer automation
-- Workspace configuration
-- Mobile app management
-- Push notification system
+- Complete Agent Workspace configuration
+- Mobile app management with push notifications
+- **Complete UI Builder/UXF integration** - Full Now Experience Framework development
+- **Conversational UI development** - Create modern ServiceNow UIs through natural language
+- **Component library management** - Custom component development and reuse
+- **Performance optimization** - Built-in UI Builder performance analysis
+- **Structure validation** - Comprehensive dependency and integrity checking
 
 ### 15. ServiceNow CMDB, Event, HR, CSM & DevOps Server
 **Purpose:** CMDB management, Event processing, HR services, Customer Service, and DevOps

package/README.md

@@ -31,9 +31,24 @@ Snow-Flow is a conversational ServiceNow development platform that bridges Claud
 
 ## Quick Start
 
+### Prerequisites 
+
+⚠️ **CRITICAL:** Claude Code must be installed and running BEFORE using Snow-Flow to prevent stdio connection errors!
+
+```bash
+# 1. FIRST: Install Claude Code
+npm install -g @anthropic-ai/claude-code
+
+# 2. Login and start Claude Code
+claude login
+cd /your/project/directory
+claude --dangerously-skip-permissions
+```
+
 ### Installation
 
 ```bash
+# 2. THEN: Install Snow-Flow (while Claude Code is running)
 npm install -g snow-flow
 ```
 
@@ -43,6 +58,9 @@ npm install -g snow-flow
 # Initialize configuration
 snow-flow init
 
+# Authenticate with ServiceNow
+snow-flow auth login
+
 # Create a ServiceNow widget with AI agents
 snow-flow swarm "create incident dashboard widget with real-time charts" --max-agents 3
 
@@ -60,6 +78,34 @@ snow-flow auth login
 snow-flow auth status
 ```
 
+#### ServiceNow OAuth Configuration
+
+To set up OAuth in your ServiceNow instance:
+
+1. **Navigate to System OAuth → Application Registry**
+2. **Click "New" → "Create an OAuth API endpoint"** (not client credentials)
+3. **Fill required fields:**
+   - Name: `Snow-Flow Integration`
+   - Client ID: `snow-flow-client`  
+   - Redirect URL: `http://localhost:3000/callback`
+4. **Save and copy the Client ID and Client Secret**
+5. **Run `snow-flow auth login`** - this opens browser for authentication
+
+#### Common Authentication Issues
+
+**❌ "Could not find artifact with sys_id xyz..."**
+- **Real cause:** OAuth token expired (misleading error message)
+- **Solution:** `snow-flow auth login`
+- **Note:** Fixed in v4.5.3 with clear OAuth error messages
+
+**❌ Stdio connection errors**
+- **Cause:** Claude Code not running before Snow-Flow  
+- **Solution:** Start Claude Code first: `claude --dangerously-skip-permissions`
+
+**❌ Permission errors**
+- **Cause:** Not logged into Claude Code
+- **Solution:** `claude login` before using Snow-Flow
+
 ## Core Features
 
 ### 🤖 Intelligent Agent Coordination

package/dist/cli.js

@@ -1550,7 +1550,7 @@ program
     .option('--skip-mcp', 'Skip MCP server activation prompt')
     .option('--force', 'Overwrite existing files without prompting')
     .action(async (options) => {
-    console.log(chalk_1.default.blue.bold(`\n🚀 Initializing Snow-Flow Project v${version_js_1.VERSION}...`));
+    console.log(chalk_1.default.blue.bold(`\n🏔️ Snow-Flow v${version_js_1.VERSION} - Conversational ServiceNow Development`));
     console.log('='.repeat(60));
     const targetDir = process.cwd();
     try {
@@ -1575,15 +1575,12 @@ program
         // Create README files
         await createReadmeFiles(targetDir, options.force);
         console.log(chalk_1.default.green.bold('\n✅ Snow-Flow project initialized successfully!'));
-        console.log('\n📋 Created files and directories:');
-        console.log('   ✓ .claude/ - Claude Code configuration');
-        console.log('   ✓ .swarm/ - Swarm session management');
-        console.log('   ✓ .snow-flow/ - Snow-Flow project data (Queen, memory, tests)');
-        console.log('   ✓ memory/ - Persistent memory storage');
-        console.log('   ✓ .env - ServiceNow OAuth configuration');
-        console.log('   ✓ .mcp.json - MCP server configuration');
-        console.log('   ✓ CLAUDE.md - Development documentation');
-        console.log('   ✓ README.md - Project documentation');
+        console.log('\n📋 Created Snow-Flow configuration:');
+        console.log('   ✓ .claude/ - Claude Code MCP configuration');
+        console.log('   ✓ .mcp.json - 20+ ServiceNow MCP servers (235+ tools)');
+        console.log('   ✓ CLAUDE.md - Complete development guide');
+        console.log('   ✓ README.md - Current capabilities documentation');
+        console.log('   ✓ .snow-flow/ - Project workspace and memory');
         if (!options.skipMcp) {
             // Start MCP servers automatically
             console.log(chalk_1.default.yellow.bold('\n🚀 Starting MCP servers in the background...'));
@@ -1606,10 +1603,12 @@ program
             }
         }
         console.log(chalk_1.default.blue.bold('\n🎯 Next steps:'));
-        console.log('1. Edit .env file with your ServiceNow credentials');
-        console.log('2. Run: ' + chalk_1.default.cyan('snow-flow auth login'));
-        console.log('3. Start developing: ' + chalk_1.default.cyan('snow-flow swarm "your objective"'));
-        console.log('\n📚 Full documentation: https://github.com/groeimetai/snow-flow');
+        console.log(chalk_1.default.red.bold('⚠️  IMPORTANT: Ensure Claude Code is running first!'));
+        console.log('1. Start Claude Code: ' + chalk_1.default.cyan('claude --dangerously-skip-permissions'));
+        console.log('2. Authenticate Snow-Flow: ' + chalk_1.default.cyan('snow-flow auth login'));
+        console.log('3. Start developing: ' + chalk_1.default.cyan('snow-flow swarm "create incident dashboard"'));
+        console.log('\n📚 Complete documentation: ' + chalk_1.default.blue('https://snow-flow.dev'));
+        console.log('💡 UI Builder, Agent Workspaces, and 235+ tools now available');
         // Force exit to prevent hanging
         process.exit(0);
     }