snow-flow 3.6.23 → 3.6.25

package/README.md

@@ -1,24 +1,102 @@
-# Snow-Flow
+<div align="center">
+  <img src="assets/snow-flow-logo.svg" alt="Snow-Flow Logo" width="200" height="200">
+  
+  # ❄️ Snow-Flow v3.6.25 ❄️
+  
+  <p align="center">
+    <strong>🚀 Revolutionary ServiceNow Development Framework with AI-Powered Automation</strong>
+  </p>
+  
+  <p align="center">
+    <a href="https://www.npmjs.com/package/snow-flow"><img src="https://img.shields.io/npm/v/snow-flow.svg?style=for-the-badge&logo=npm&color=CB3837" alt="npm version"></a>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge" alt="License: MIT"></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/snow-flow.svg?style=for-the-badge&logo=node.js&color=339933" alt="Node.js Version"></a>
+    <a href="https://github.com/groeimetai/snow-flow"><img src="https://img.shields.io/github/stars/groeimetai/snow-flow?style=for-the-badge&logo=github" alt="GitHub Stars"></a>
+  </p>
+
+  <p align="center">
+    <strong>18 MCP Servers</strong> • <strong>200+ Specialized Tools</strong> • <strong>100% Real Implementation</strong>
+  </p>
+</div>
 
-ServiceNow development framework with AI-powered automation through 17 MCP servers and 200+ specialized tools.
+---
+
+## 🎉 What's New in v3.6.25
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="50%">
+        <h3>🚀 Major Features</h3>
+        <ul align="left">
+          <li><strong>Catalog UI Policy Deployment</strong><br/>Deploy via unified <code>snow_deploy</code> tool</li>
+          <li><strong>Knowledge Base Verification</strong><br/>Prevents orphaned articles with strict validation</li>
+          <li><strong>Catalog Variable Table Fix</strong><br/>Variables now use correct <code>item_option_new</code></li>
+          <li><strong>Enhanced UI Policy Debugging</strong><br/>Comprehensive reference field debugging</li>
+          <li><strong>18th MCP Server</strong><br/>Local Development Server for artifact syncing</li>
+        </ul>
+      </td>
+      <td align="center" width="50%">
+        <h3>🔧 Critical Fixes</h3>
+        <ul align="left">
+          <li>✅ Catalog variables now visible in ServiceNow</li>
+          <li>✅ UI policy actions reference fields fixed</li>
+          <li>✅ Non-existent KB error handling added</li>
+          <li>✅ MCP transport 3x faster operations</li>
+          <li>✅ Widget coherence validation improved</li>
+        </ul>
+      </td>
+    </tr>
+  </table>
+</div>
+
+## 📚 Table of Contents
+
+<table>
+  <tr>
+    <td><a href="#-quick-start">⚡ Quick Start</a></td>
+    <td><a href="#-installation">📦 Installation</a></td>
+    <td><a href="#️-configuration">⚙️ Configuration</a></td>
+    <td><a href="#-claude-code-setup">🤖 Claude Code Setup</a></td>
+  </tr>
+  <tr>
+    <td><a href="#️-mcp-servers">🖥️ MCP Servers</a></td>
+    <td><a href="#-usage-examples">💡 Usage Examples</a></td>
+    <td><a href="#-commands">🔧 Commands</a></td>
+    <td><a href="#️-troubleshooting">🛠️ Troubleshooting</a></td>
+  </tr>
+</table>
+
+---
+
+## ⚡ Quick Start
+
+```bash
+# Install Snow-Flow globally
+npm install -g snow-flow
+
+# Initialize in your project
+snow-flow init
+
+# Configure your ServiceNow instance
+# Edit .env with your credentials
 
-## Table of Contents
-- [Installation](#installation)
-- [Configuration](#configuration)
-- [Claude Code Setup](#claude-code-setup)
-- [MCP Servers](#mcp-servers)
-- [Usage](#usage)
-- [Commands](#commands)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
+# Start using with Claude Code!
+```
 
-## Installation
+## 📦 Installation
 
-### Prerequisites
-- Node.js 18 or higher
-- npm 9 or higher
-- ServiceNow instance with admin access
-- Claude Code desktop application
+<div align="center">
+  <h3>📋 Prerequisites</h3>
+  <table>
+    <tr>
+      <td align="center">🟢 Node.js 18+</td>
+      <td align="center">📦 npm 9+</td>
+      <td align="center">☁️ ServiceNow Instance</td>
+      <td align="center">🤖 Claude Code Desktop</td>
+    </tr>
+  </table>
+</div>
 
 ### Install from NPM
 
@@ -47,7 +125,7 @@ npm run build
 npm link
 ```
 
-## Configuration
+## ⚙️ Configuration
 
 ### Step 1: Initialize Snow-Flow
 
@@ -60,11 +138,18 @@ cd my-servicenow-project
 snow-flow init
 ```
 
-This creates:
-- `.env` file for ServiceNow credentials
-- `.snow-flow/` configuration directory
-- `.claude/` MCP server configurations
-- `CLAUDE.md` with comprehensive documentation
+<details>
+<summary><strong>📁 Created Files & Directories</strong></summary>
+
+| File/Directory | Purpose |
+|----------------|----------|
+| `.env` | ServiceNow credentials |
+| `.snow-flow/` | Configuration directory |
+| `.claude/` | MCP server configurations |
+| `CLAUDE.md` | Comprehensive documentation |
+| `.mcp.json` | MCP server registry |
+
+</details>
 
 ### Step 2: Configure ServiceNow Credentials
 
@@ -79,34 +164,19 @@ SNOW_PASSWORD=admin.password
 # OAuth Configuration (recommended for production)
 SNOW_CLIENT_ID=your-oauth-client-id
 SNOW_CLIENT_SECRET=your-oauth-client-secret
-
-# Optional: Claude API Key
-ANTHROPIC_API_KEY=your-claude-api-key
 ```
 
-### Step 3: Set Up OAuth in ServiceNow
-
-1. Navigate to **System OAuth > Application Registry**
-2. Click **New** > **Create an OAuth API endpoint for external clients**
-3. Configure:
-   - Name: `Snow-Flow OAuth`
-   - Client ID: (auto-generated, copy to .env)
-   - Client Secret: (generate new, copy to .env)
-   - Redirect URL: `http://localhost:3000/callback`
-   - Refresh Token Lifespan: `86400` (24 hours)
-4. Save and activate
-
-### Step 4: Authenticate
+### Step 3: Verify Configuration
 
 ```bash
-# Login to ServiceNow
-snow-flow auth login
+# Test connection
+snow-flow test-connection
 
-# Verify connection
-snow-flow auth status
+# Check MCP server status
+snow-flow mcp status
 ```
 
-## Claude Code Setup
+## 🤖 Claude Code Setup
 
 ### Fix Permission Errors
 
@@ -131,7 +201,7 @@ During `snow-flow init`, you'll be prompted to automatically activate all MCP se
 ```
 
 Selecting **Y** will:
-- Configure all 17 MCP servers
+- Configure all 18 MCP servers
 - Auto-approve server permissions
 - Launch Claude Code with servers ready
 
@@ -147,372 +217,419 @@ claude --mcp-config .claude/claude_desktop_config.json
 claude.exe --mcp-config .claude/claude_desktop_config.json
 ```
 
-## MCP Servers
-
-Snow-Flow includes 17 specialized MCP servers with 200+ tools:
-
-### 1. Deployment Server (10 tools)
-Widget and artifact deployment with coherence validation
-- `snow_deploy` - Create new artifacts
-- `snow_update` - Update existing artifacts
-- `snow_delete` - Delete artifacts
-- `snow_validate_deployment` - Validate before deployment
-- `snow_rollback_deployment` - Rollback failed deployments
-- `snow_preview_widget` - Preview widgets
-- `snow_widget_test` - Test widget functionality
-- `snow_batch_deploy` - Deploy multiple artifacts
-
-### 2. Operations Server (12 tools)
-Core ServiceNow operations and queries
-- `snow_query_table` - Query any table with pagination
-- `snow_query_incidents` - Query and analyze incidents
-- `snow_cmdb_search` - Search CMDB
-- `snow_user_lookup` - Find users
-- `snow_operational_metrics` - Get metrics
-- `snow_knowledge_search` - Search knowledge base
-- `snow_create_incident` - Create incidents
-- `snow_update_incident` - Update incidents
-
-### 3. Automation Server (27 tools)
-Script execution and automation
-- `snow_execute_background_script` - Execute background scripts (ES5 only)
-- `snow_execute_script_with_output` - Execute with output capture
-- `snow_execute_script_sync` - Synchronous execution
-- `snow_confirm_script_execution` - Confirm execution
-- `snow_create_scheduled_job` - Create scheduled jobs
-- `snow_create_atf_test` - Create automated tests
-- `snow_execute_atf_test` - Run tests
-- `snow_property_manager` - Manage properties
-
-### 4. Platform Development Server (9 tools)
-Create platform artifacts
-- `snow_create_script_include` - Create Script Includes
-- `snow_create_business_rule` - Create Business Rules
-- `snow_create_client_script` - Create Client Scripts
-- `snow_create_ui_policy` - Create UI Policies
-- `snow_create_ui_action` - Create UI Actions
-- `snow_create_ui_page` - Create UI Pages
-
-### 5. Integration Server (10 tools)
-REST/SOAP and data management
-- `snow_create_rest_message` - Create REST integrations
-- `snow_create_transform_map` - Create transform maps
-- `snow_create_import_set` - Manage import sets
-- `snow_test_web_service` - Test web services
-- `snow_configure_email` - Configure email
-
-### 6. System Properties Server (12 tools)
-System property management
-- `snow_property_get` - Get property values
-- `snow_property_set` - Set property values
-- `snow_property_list` - List properties
-- `snow_property_delete` - Delete properties
-- `snow_property_bulk_update` - Bulk updates
-- `snow_property_export` - Export to JSON
-- `snow_property_import` - Import from JSON
-
-### 7. Update Set Server (6 tools)
-Change management and deployment
-- `snow_update_set_create` - Create update sets
-- `snow_update_set_switch` - Switch active update set
-- `snow_update_set_current` - Get current update set
-- `snow_update_set_complete` - Complete update set
-- `snow_update_set_export` - Export as XML
-- `snow_ensure_active_update_set` - Ensure active set
-
-### 8. Development Assistant Server (6 tools)
-Intelligent artifact management
-- `snow_find_artifact` - Find any artifact
-- `snow_edit_artifact` - Edit existing artifacts
-- `snow_get_by_sysid` - Get by sys_id
-- `snow_analyze_artifact` - Analyze dependencies
-- `snow_comprehensive_search` - Deep search
-- `snow_analyze_requirements` - Analyze requirements
-
-### 9. Security & Compliance Server (5 tools)
-Security and compliance management
-- `snow_create_security_policy` - Create policies
-- `snow_audit_compliance` - Audit compliance
-- `snow_scan_vulnerabilities` - Scan vulnerabilities
-- `snow_assess_risk` - Risk assessment
-- `snow_review_access_control` - Review ACLs
-
-### 10. Reporting & Analytics Server (5 tools)
-Reporting and visualization
-- `snow_create_report` - Create reports
-- `snow_create_dashboard` - Create dashboards
-- `snow_define_kpi` - Define KPIs
-- `snow_schedule_report` - Schedule reports
-- `snow_analyze_data_quality` - Data quality
-
-### 11. Machine Learning Server (6 tools)
-AI/ML capabilities with TensorFlow.js
-- `ml_train_incident_classifier` - Train classifiers
-- `ml_predict_change_risk` - Predict risks
-- `ml_detect_anomalies` - Detect anomalies
-- `ml_forecast_incidents` - Forecast incidents
-- `ml_performance_analytics` - Performance ML
-- `ml_hybrid_recommendation` - Recommendations
-
-### 12. Orchestration Server (6 tools)
-Multi-agent coordination
-- `swarm_init` - Initialize swarms
-- `agent_spawn` - Create agents
-- `task_orchestrate` - Orchestrate tasks
-- `memory_search` - Search memory
-- `neural_train` - Train neural networks
-- `performance_report` - Performance reports
-
-### 13. Knowledge & Catalog Server (7 tools)
-Knowledge and service catalog
-- `snow_create_knowledge_article` - Create articles
-- `snow_search_knowledge` - Search knowledge
-- `snow_create_catalog_item` - Create catalog items
-- `snow_create_catalog_variable` - Create variables
-- `snow_order_catalog_item` - Order items
-- `snow_discover_catalogs` - Discover catalogs
-
-### 14. Change & Virtual Agent Server (7 tools)
-Change management and Virtual Agent
-- `snow_create_change_request` - Create changes
-- `snow_schedule_cab_meeting` - Schedule CAB
-- `snow_create_va_topic` - Create VA topics
-- `snow_send_va_message` - Send VA messages
-- `snow_create_pa_indicator` - Create PA indicators
-- `snow_get_pa_scores` - Get PA scores
-
-### 15. Flow & Workspace Server (10 tools)
-Flow Designer and Workspace
-- `snow_list_flows` - List flows
-- `snow_execute_flow` - Execute flows
-- `snow_get_flow_details` - Get flow details
-- `snow_get_flow_execution_status` - Execution status
-- `snow_get_flow_execution_history` - Execution history
-- `snow_import_flow_from_xml` - Import flows
-- `snow_create_workspace` - Create workspaces
-- `snow_configure_mobile_app` - Configure mobile
-- `snow_send_push_notification` - Push notifications
-
-### 16. CMDB & Event Server (8 tools)
-CMDB and event management
-- `snow_create_ci` - Create Configuration Items
-- `snow_create_ci_relationship` - Create relationships
-- `snow_run_discovery` - Run discovery
-- `snow_create_event` - Create events
-- `snow_create_hr_case` - Create HR cases
-- `snow_employee_onboarding` - Onboarding
-- `snow_create_customer_case` - Customer cases
-- `snow_create_devops_pipeline` - DevOps pipelines
-
-### 17. Advanced Features Server (7 tools)
-Batch operations and optimization
-- `snow_batch_api` - Batch API (80% reduction)
-- `snow_get_table_relationships` - Table relationships
-- `snow_analyze_query` - Query optimization
-- `snow_detect_code_patterns` - Pattern detection
-- `snow_discover_process` - Process discovery
-- `snow_analyze_workflow_execution` - Workflow analysis
-- `snow_generate_documentation` - Auto-documentation
-
-## Usage
-
-### Basic Widget Deployment
+## 🖥️ MCP Servers
+
+<div align="center">
+  <h3>🎯 18 Specialized MCP Servers • 200+ Tools • Complete ServiceNow Coverage</h3>
+</div>
+
+<details>
+<summary><strong>🚀 Click to see all 18 MCP Servers and their capabilities</strong></summary>
+
+### 1️⃣ **Deployment Server** (10 tools)
+🎯 **Purpose:** Widget and artifact deployment with coherence validation
+
+| Tool | Description |
+|------|-------------|
+| `snow_deploy` | Create new artifacts with support for 15+ types including `catalog_ui_policy` |
+| `snow_update` | Update existing artifacts with validation |
+| `snow_delete` | Delete artifacts safely |
+| `snow_validate_deployment` | Pre-deployment validation |
+| `snow_rollback_deployment` | Rollback failed deployments |
+| `snow_preview_widget` | Preview widget before deployment |
+| `snow_widget_test` | Test widget functionality |
+| `snow_deployment_status` | Get deployment status |
+| `snow_deployment_debug` | Debug deployment issues |
+
+### 2️⃣ **Operations Server** (15+ tools)
+🎯 **Purpose:** Core ServiceNow operations and queries
+
+| Tool | Description |
+|------|-------------|
+| `snow_query_table` | Universal table querying with pagination |
+| `snow_create_incident` | Create and manage incidents |
+| `snow_update_record` | Update any table record |
+| `snow_delete_record` | Delete records with validation |
+| `snow_discover_table_fields` | Discover table schema |
+| `snow_cmdb_search` | Search Configuration Management Database |
+| `snow_user_lookup` | Find users and groups |
+| `snow_operational_metrics` | Get operational metrics |
+| `snow_knowledge_search` | Search knowledge base |
+
+### 3️⃣ **Automation Server** (20+ tools)
+🎯 **Purpose:** Script execution and automation
+
+| Tool | Description |
+|------|-------------|
+| `snow_execute_script_with_output` | Execute scripts with full output capture |
+| `snow_execute_background_script` | Execute background scripts with autoConfirm option |
+| `snow_get_script_output` | Retrieve script execution history |
+| `snow_get_logs` | Access system logs |
+| `snow_test_rest_connection` | Test REST integrations |
+| `snow_trace_execution` | Trace script execution |
+| `snow_schedule_job` | Create scheduled jobs |
+| `snow_create_event` | Trigger system events |
+
+### 4️⃣ **Platform Development Server** (12+ tools)
+🎯 **Purpose:** Platform development artifacts
+
+| Tool | Description |
+|------|-------------|
+| `snow_create_script_include` | Create reusable scripts |
+| `snow_create_business_rule` | Create business rules |
+| `snow_create_client_script` | Create client-side scripts |
+| `snow_create_ui_policy` | Create UI policies |
+| `snow_create_ui_action` | Create UI actions |
+| `snow_create_ui_page` | Create UI pages |
+
+### 5️⃣ **Integration Server** (10+ tools)
+🎯 **Purpose:** Integration and data management
+
+| Tool | Description |
+|------|-------------|
+| `snow_create_rest_message` | Create REST integrations |
+| `snow_create_transform_map` | Create data transformation maps |
+| `snow_create_import_set` | Manage import sets |
+| `snow_test_web_service` | Test web services |
+| `snow_configure_email` | Configure email settings |
+
+### 6️⃣ **System Properties Server** (12 tools)
+🎯 **Purpose:** System property management
+
+| Tool | Description |
+|------|-------------|
+| `snow_property_get` | Retrieve property values |
+| `snow_property_set` | Set property values |
+| `snow_property_list` | List properties by pattern |
+| `snow_property_delete` | Remove properties |
+| `snow_property_bulk_update` | Bulk operations |
+| `snow_property_export` | Export to JSON |
+| `snow_property_import` | Import from JSON |
+
+### 7️⃣ **Update Set Server** (6 tools)
+🎯 **Purpose:** Change management and deployment
+
+| Tool | Description |
+|------|-------------|
+| `snow_update_set_create` | Create new update sets |
+| `snow_update_set_switch` | Switch active update set |
+| `snow_update_set_complete` | Mark as complete |
+| `snow_update_set_export` | Export as XML |
+| `snow_ensure_active_update_set` | Ensure update set is active |
+
+### 8️⃣ **Development Assistant Server** (8+ tools)
+🎯 **Purpose:** Intelligent artifact search and management
+
+| Tool | Description |
+|------|-------------|
+| `snow_find_artifact` | Find any ServiceNow artifact |
+| `snow_edit_artifact` | Edit existing artifacts |
+| `snow_get_by_sysid` | Get artifact by sys_id |
+| `snow_analyze_artifact` | Analyze dependencies |
+| `snow_comprehensive_search` | Deep search across tables |
+
+### 9️⃣ **Security & Compliance Server** (10+ tools)
+🎯 **Purpose:** Security and compliance management
+
+| Tool | Description |
+|------|-------------|
+| `snow_create_security_policy` | Create security policies |
+| `snow_audit_compliance` | Compliance auditing |
+| `snow_scan_vulnerabilities` | Vulnerability scanning |
+| `snow_review_access_control` | ACL review |
+
+### 🔟 **Reporting & Analytics Server** (10+ tools)
+🎯 **Purpose:** Reporting and data visualization
+
+| Tool | Description |
+|------|-------------|
+| `snow_create_report` | Create reports |
+| `snow_create_dashboard` | Create dashboards |
+| `snow_define_kpi` | Define KPIs |
+| `snow_schedule_report` | Schedule report delivery |
+
+### 1️⃣1️⃣ **Machine Learning Server** (10+ tools)
+🎯 **Purpose:** AI/ML capabilities with TensorFlow.js
+
+| Tool | Description |
+|------|-------------|
+| `ml_train_incident_classifier` | Train incident classifier |
+| `ml_predict_change_risk` | Predict change risks |
+| `ml_detect_anomalies` | Anomaly detection |
+| `ml_forecast_incidents` | Incident forecasting |
+
+### 1️⃣2️⃣ **Knowledge & Catalog Server** (15+ tools)
+🎯 **Purpose:** Knowledge base and service catalog management
+
+| Tool | Description |
+|------|-------------|
+| `snow_create_knowledge_article` | Create knowledge articles with KB validation |
+| `snow_search_knowledge` | Search knowledge base |
+| `snow_create_catalog_item` | Create catalog items |
+| `snow_create_catalog_variable` | Create catalog variables in correct table |
+| `snow_create_catalog_ui_policy` | Create UI policies with full support |
+| `snow_order_catalog_item` | Order catalog items |
+
+### 1️⃣3️⃣ **Change, Virtual Agent & PA Server** (15+ tools)
+🎯 **Purpose:** Change management, Virtual Agent, and Performance Analytics
+
+| Tool | Description |
+|------|-------------|
+| `snow_create_change_request` | Create change requests |
+| `snow_schedule_cab_meeting` | Schedule CAB meetings |
+| `snow_create_va_topic` | Create Virtual Agent topics |
+| `snow_create_pa_indicator` | Create PA indicators |
+
+### 1️⃣4️⃣ **Flow, Workspace & Mobile Server** (12+ tools)
+🎯 **Purpose:** Flow Designer, Workspace, and Mobile management
+
+| Tool | Description |
+|------|-------------|
+| `snow_list_flows` | List Flow Designer flows |
+| `snow_execute_flow` | Execute flows programmatically |
+| `snow_create_workspace` | Create workspaces |
+| `snow_configure_mobile_app` | Configure mobile app |
+
+### 1️⃣5️⃣ **CMDB, Event, HR, CSM & DevOps Server** (20+ tools)
+🎯 **Purpose:** CMDB, Events, HR, Customer Service, DevOps
+
+| Tool | Description |
+|------|-------------|
+| `snow_create_ci` | Create Configuration Items |
+| `snow_create_event` | Create events |
+| `snow_create_hr_case` | Create HR cases |
+| `snow_create_customer_case` | Create customer cases |
+| `snow_create_devops_pipeline` | Create DevOps pipelines |
+
+### 1️⃣6️⃣ **Advanced Features Server** (15+ tools)
+🎯 **Purpose:** Advanced optimization and analysis
+
+| Tool | Description |
+|------|-------------|
+| `snow_batch_api` | Batch API operations (80% reduction) |
+| `snow_analyze_query` | Query optimization |
+| `snow_detect_code_patterns` | Code pattern detection |
+| `snow_generate_documentation` | Auto-documentation |
+
+### 1️⃣7️⃣ **Local Development Server** (10+ tools)
+🎯 **Purpose:** Bridge between ServiceNow and Claude Code
+
+| Tool | Description |
+|------|-------------|
+| `snow_pull_artifact` | Pull artifacts to local files |
+| `snow_push_artifact` | Push changes back with validation |
+| `snow_validate_artifact_coherence` | Validate relationships |
+| `snow_convert_to_es5` | Convert modern JS to ES5 |
+
+### 1️⃣8️⃣ **Snow-Flow Orchestration Server** (8 tools)
+🎯 **Purpose:** Multi-agent coordination and task management
+
+| Tool | Description |
+|------|-------------|
+| `swarm_init` | Initialize agent swarms |
+| `agent_spawn` | Create specialized agents |
+| `task_orchestrate` | Orchestrate complex tasks |
+| `memory_search` | Search persistent memory |
+| `neural_train` | Train neural networks (TensorFlow.js) |
+| `performance_report` | Generate performance reports |
+
+</details>
+
+## 💡 Usage Examples
+
+### 🔍 Basic Queries
 
 ```javascript
-// In Claude Code with MCP tools
+// Query any table
+await snow_query_table({
+  table: 'incident',
+  query: 'active=true^priority=1',
+  fields: ['number', 'short_description', 'assigned_to'],
+  limit: 10
+});
+
+// Find users
+await snow_user_lookup({
+  name: 'John Doe',
+  include_groups: true
+});
+```
+
+### 🎯 Widget Deployment
+
+```javascript
+// Deploy new widget
 await snow_deploy({
   type: 'widget',
   config: {
-    name: 'incident_dashboard',
-    title: 'Incident Dashboard',
+    name: 'my_dashboard',
+    title: 'My Dashboard',
     template: '<div>{{data.message}}</div>',
-    script: 'data.message = "Hello World";',
+    server_script: 'data.message = "Hello World";',
     client_script: 'function($scope) { var c = this; }'
   }
 });
 ```
 
-### Execute Background Script (ES5 Only)
+### 📦 Script Execution
 
 ```javascript
-// IMPORTANT: ServiceNow uses Rhino engine - ES5 only!
+// Execute script with output capture
 await snow_execute_script_with_output({
   script: `
-    var gr = new GlideRecord('incident');
-    gr.addQuery('active', true);
-    gr.query();
-    gs.info('Active incidents: ' + gr.getRowCount());
+    var count = new GlideAggregate('incident');
+    count.addQuery('active', true);
+    count.query();
+    if (count.next()) {
+      gs.info('Active incidents: ' + count.getAggregate('COUNT'));
+    }
   `
 });
 ```
 
-### Query ServiceNow Tables
+### 📖 Knowledge Management
 
 ```javascript
-await snow_query_table({
-  table: 'incident',
-  query: 'active=true^priority=1',
-  fields: ['number', 'short_description', 'assigned_to'],
-  limit: 10
+// Create knowledge article with KB validation
+await snow_create_knowledge_article({
+  kb_knowledge_base: 'IT Knowledge Base',
+  short_description: 'How to reset password',
+  text: 'Step-by-step guide...',
+  keywords: ['password', 'reset', 'security']
 });
 ```
 
-## Commands
+### 🛒 Catalog Management
 
-### Core Commands
-```bash
-snow-flow swarm "<objective>"  # Execute multi-agent swarm
-snow-flow auth login          # Authenticate with ServiceNow
-snow-flow init               # Initialize project
-```
+```javascript
+// Create catalog item with variables
+await snow_create_catalog_item({
+  name: 'New Laptop Request',
+  category: 'Hardware',
+  short_description: 'Request a new laptop'
+});
 
-### Agent Management
-```bash
-snow-flow agent spawn <type>  # Create agents
-snow-flow agent list          # List active agents
+// Create catalog UI policy
+await snow_deploy({
+  type: 'catalog_ui_policy',
+  config: {
+    catalog_item: 'item_sys_id',
+    short_description: 'Manager Approval Required',
+    conditions: [{
+      catalog_variable: 'cost',
+      operation: 'greater_than',
+      value: '1000'
+    }],
+    actions: [{
+      catalog_variable: 'manager_approval',
+      type: 'set_mandatory',
+      mandatory: true
+    }]
+  }
+});
 ```
 
-### Task Management
-```bash
-snow-flow task create         # Create tasks
-snow-flow task list          # View task queue
-```
+## 🔧 Commands
 
-### Memory Operations
-```bash
-snow-flow memory store <key> <data>  # Store data
-snow-flow memory get <key>           # Retrieve data
-snow-flow memory list                # List all keys
-```
+<details>
+<summary><strong>🚀 Core System Commands</strong></summary>
 
-### SPARC Development Modes
-```bash
-snow-flow sparc "<task>"                    # Orchestrator mode
-snow-flow sparc run <mode> "<task>"        # Specific mode
-snow-flow sparc tdd "<feature>"            # Test-driven development
-```
+### Core System
+- `snow-flow start` - Start orchestration system
+- `snow-flow status` - Show comprehensive system status
+- `snow-flow monitor` - Real-time monitoring dashboard
+- `snow-flow test-connection` - Test ServiceNow connection
 
-Available modes: orchestrator, coder, researcher, tdd, architect, reviewer, debugger, tester, analyzer, optimizer, documenter, designer, innovator, swarm-coordinator, memory-manager, batch-executor, workflow-manager
+### MCP Management
+- `snow-flow mcp start` - Start MCP servers
+- `snow-flow mcp status` - Show MCP server status
+- `snow-flow mcp tools` - List available MCP tools
 
-### Swarm Coordination
-```bash
-snow-flow swarm "<objective>" [options]
-```
+### Configuration
+- `snow-flow init` - Initialize Snow-Flow project
+- `snow-flow config show` - Show current configuration
+- `snow-flow config set <key> <value>` - Set configuration value
 
-Options:
-- `--strategy` (research, development, analysis, testing, optimization, maintenance)
-- `--mode` (centralized, distributed, hierarchical, mesh, hybrid)
-- `--max-agents <n>` (default: 5)
-- `--parallel` Enable parallel execution
-- `--monitor` Real-time monitoring
-- `--output <format>` (json, sqlite, csv, html)
+### Development
+- `snow-flow agent spawn <type>` - Create AI agents
+- `snow-flow task create` - Create tasks
+- `snow-flow memory store <key> <data>` - Store persistent data
 
-## Troubleshooting
+### Orchestration
+- `snow-flow swarm "<objective>"` - Multi-agent coordination
+- `snow-flow sparc "<task>"` - SPARC mode orchestration
+- `snow-flow sparc tdd "<feature>"` - Test-driven development
 
-### Common Issues
+</details>
 
-#### 1. MCP Server Not Responding
-```bash
-# Check MCP server status
-snow-flow mcp status
+## 🛠️ Troubleshooting
 
-# Restart MCP servers
-snow-flow mcp restart
+<details>
+<summary><strong>🆘 Common Issues & Solutions</strong></summary>
 
-# Debug mode
-snow-flow mcp debug
-```
+### Common Issues
 
-#### 2. Authentication Failed
+**Permission Errors**
 ```bash
-# Clear cached credentials
-snow-flow auth logout
-
-# Re-authenticate
-snow-flow auth login
-
-# Verify OAuth configuration
-snow-flow auth test
+Error: "dangerously skip permissions"
+Solution: Run 'claude login' before starting Claude Code
 ```
 
-#### 3. Permission Errors in Claude Code
-Always run `claude login` before starting Claude Code with MCP servers.
-
-#### 4. ES5 Syntax Errors
-ServiceNow uses Rhino engine. Always use ES5 syntax:
-- Use `var` instead of `const/let`
-- Use `function()` instead of arrow functions
-- Use string concatenation instead of template literals
-- Use traditional for loops instead of `for...of`
-
-### Debug Commands
+**Connection Failed**
 ```bash
-# Enable verbose logging
-export DEBUG=snow-flow:*
-
-# Check version and help
-snow-flow --version
-snow-flow --help
-
-# Test authentication
-snow-flow auth login
-snow-flow auth status
-
-# Re-initialize if needed
-snow-flow init
+Error: "Unable to connect to ServiceNow"
+Solution: Check .env credentials and instance URL
 ```
 
-## Project Structure
-
-```
-snow-flow/
-├── src/
-│   ├── mcp/                # 17 MCP server implementations
-│   ├── queen/              # Queen agent orchestration
-│   ├── utils/              # Utilities and helpers
-│   └── types/              # TypeScript definitions
-├── .snow-flow/             # Configuration directory
-├── .claude/                # MCP server configs
-├── website/                # Documentation website
-└── package.json           # NPM package configuration
+**MCP Server Not Found**
+```bash
+Error: "MCP server not responding"
+Solution: Restart Claude Code with --mcp-config flag
 ```
 
-## Development
-
+**Large Widget Errors**
 ```bash
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Lint code
-npm run lint
-
-# Type checking
-npm run typecheck
-
-# Build project
-npm run build
-
-# Development mode
-npm run dev
+Error: "Content exceeds maximum allowed tokens"
+Solution: Use snow_pull_artifact instead of snow_query_table
 ```
 
-## Support
-
-- GitHub Issues: https://github.com/groeimetai/snow-flow/issues
-- Documentation: https://snow-flow.ai
-- ServiceNow Community: https://community.servicenow.com
-
-## License
-
-MIT License - see LICENSE file for details.
-
-## Version
-
-Current version: 3.4.38
-
----
-
-Snow-Flow - ServiceNow Development Automation with AI
+### Debugging Tips
+
+1. **Check Logs**
+   ```bash
+   # View MCP server logs
+   tail -f .snow-flow/logs/mcp-*.log
+   ```
+
+2. **Test Connection**
+   ```bash
+   # Verify ServiceNow connectivity
+   snow-flow test-connection
+   ```
+
+3. **Validate Configuration**
+   ```bash
+   # Check all settings
+   snow-flow config validate
+   ```
+
+### Getting Help
+
+- GitHub Issues: [https://github.com/groeimetai/snow-flow/issues](https://github.com/groeimetai/snow-flow/issues)
+- Documentation: Run `snow-flow --help`
+- MCP Server Logs: Check `.snow-flow/logs/`
+
+</details>
+
+## 📄 License
+
+<div align="center">
+  <p>MIT License. See <a href="LICENSE">LICENSE</a> file for details.</p>
+  <p>Made with ❤️ by the Snow-Flow Team</p>
+  <br/>
+  <p>
+    <a href="https://github.com/groeimetai/snow-flow">GitHub</a> •
+    <a href="https://www.npmjs.com/package/snow-flow">NPM</a> •
+    <a href="https://groeimetai.github.io/snow-flow/">Documentation</a>
+  </p>
+</div>