snow-flow 8.37.26 → 8.38.0

package/README.md

@@ -1,1001 +1,238 @@
-# 🏔️ Snow-Flow
+<p align="center">
+  <picture>
+    <img src="packages/console/app/src/asset/logo-ornate-light.svg" alt="SnowCode logo" width="300">
+  </picture>
+</p>
 
-**Multi-LLM ServiceNow Development Platform**
+<h1 align="center">SnowCode</h1>
+<h3 align="center">AI-Powered ServiceNow Development IDE</h3>
+<p align="center"><strong>Part of the Snow-Flow Enterprise Suite</strong></p>
 
-[![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic--2.0-blue.svg?style=for-the-badge)](https://www.elastic.co/licensing/elastic-license)
-[![Node.js](https://img.shields.io/node/v/snow-flow.svg?style=for-the-badge&logo=node.js&color=339933)](https://nodejs.org)
-
-**Develop ServiceNow through conversation • 413 Tools • 2 MCP Servers • 75+ LLM Providers • Works with ANY AI coding assistant**
-
----
+<p align="center">
+  <a href="https://github.com/groeimetai/snow-flow"><img alt="GitHub" src="https://img.shields.io/github/stars/groeimetai/snow-flow?style=flat-square" /></a>
+  <a href="https://github.com/groeimetai/snow-flow"><img alt="Snow-Flow" src="https://img.shields.io/badge/snow--flow-350%2B%20tools-blue?style=flat-square" /></a>
+  <a href="#enterprise-edition"><img alt="Enterprise" src="https://img.shields.io/badge/enterprise-available-green?style=flat-square" /></a>
+</p>
 
-## What is Snow-Flow?
+# Snow-Flow
 
-Snow-Flow transforms ServiceNow development into a **conversational experience**. Instead of clicking through ServiceNow's web interface, you develop through natural conversation with your AI coding assistant using **any LLM provider** you prefer.
+**The Free ServiceNow Build Agent Alternative**
 
-### The Problem
-
-Traditional ServiceNow development means:
-- ❌ Manual navigation through complex web UIs
-- ❌ Context switching between modules
-- ❌ Repetitive clicking and form filling
-- ❌ Limited to browser-based development
-- ❌ Locked into specific AI providers
-
-### The Solution
+[![npm](https://img.shields.io/npm/v/snow-flow?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/snow-flow)
+[![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic--2.0-blue.svg?style=for-the-badge)](https://www.elastic.co/licensing/elastic-license)
+[![GitHub stars](https://img.shields.io/github/stars/groeimetai/snow-flow?style=for-the-badge&logo=github)](https://github.com/groeimetai/snow-flow)
 
-Snow-Flow provides:
-- ✅ **Conversational Development**: Build through natural language
-- ✅ **413 ServiceNow Tools**: Complete API coverage via 2 unified MCP servers
-- ✅ **75+ LLM Providers**: Claude, GPT-4o, Gemini, Llama, Mistral, DeepSeek, Groq, or ANY provider via SnowCode
-- ✅ **100% Free Option**: Ollama, LM Studio, Jan - run models locally offline
-- ✅ **Local Development**: Pull artifacts to local files, edit with native tools
-- ✅ **Local ML Training**: TensorFlow.js neural networks (runs locally, trains on ServiceNow data)
-- ✅ **Universal Compatibility**: Works with SnowCode, Claude Code, Cursor, Windsurf, Continue.dev, Cline
+**Built by developers, for developers.** Snow-Flow is an open-source ServiceNow development platform with 410+ MCP tools. Use any AI model you want - Claude, GPT-4, Gemini, Llama, or run completely free with Ollama.
 
 ---
 
-## 🚀 Quick Start (3 Minutes)
-
-### Installation
+## Get Started in 60 Seconds
 
 ```bash
-# Install Snow-Flow globally
+# Install
 npm install -g snow-flow
 
-# Initialize your project
+# Initialize (creates config files)
 snow-flow init
-```
-
-Snow-Flow will automatically:
-- ✅ Detect and install SnowCode (recommended AI coding platform)
-- ✅ Generate configuration files (`.env`, `.snow-code/config.json`)
-- ✅ Set up 2 MCP servers with 413 ServiceNow tools
-- ✅ Create documentation (`AGENTS.md`, `README.md`)
-
-### Configuration
-
-```bash
-# Edit .env file with your credentials
-vi .env
-```
-
-**Required settings:**
-```bash
-# ServiceNow OAuth
-SNOW_INSTANCE=your-instance.service-now.com
-SNOW_CLIENT_ID=your-client-id
-SNOW_CLIENT_SECRET=your-client-secret
-
-# Choose ONE LLM provider
-DEFAULT_LLM_PROVIDER=anthropic  # or openai, google, ollama, etc.
-
-# Option 1: Claude Pro/Max (leave API key empty)
-ANTHROPIC_API_KEY=
-
-# Option 2: Pay-per-use API
-ANTHROPIC_API_KEY=sk-ant-your-key
-
-# Option 3: Free local (Ollama)
-DEFAULT_LLM_PROVIDER=ollama
-OLLAMA_BASE_URL=http://localhost:11434
-DEFAULT_OLLAMA_MODEL=llama3.3
-```
-
-### Authentication
 
-```bash
-# One command authenticates EVERYTHING
+# Authenticate (ServiceNow + optional enterprise services)
 snow-flow auth login
+
+# Start building
+snow-flow swarm "create an incident dashboard widget"
 ```
 
-**What happens:**
-1. **Claude Pro/Max users**: Browser opens automatically for Anthropic login
-2. **API key users**: Skips to step 2
-3. **ServiceNow**: Browser opens for OAuth authentication
-4. **Done**: You're ready to develop!
+That's it. You're now developing ServiceNow through conversation.
 
-### SnowCode Setup
+---
 
-For detailed SnowCode configuration (MCP servers, environment variables, troubleshooting), see:
+## Why Snow-Flow?
 
-📖 **[SNOWCODE-SETUP.md](SNOWCODE-SETUP.md)** - Complete SnowCode configuration guide
+### vs ServiceNow Build Agent
 
-**Quick checklist:**
-- ✅ Use `"environment"` (not `"env"`) in `snow-code-config.json`
-- ✅ Run `npm run build` to create `dist/` directory
-- ✅ Verify MCP servers load when SnowCode starts
-- ✅ Test tools actually execute (not just show code snippets)
+| | Snow-Flow | ServiceNow Build Agent |
+|---|---|---|
+| **Price** | **Free** (open source) | $100-200/user/month + Pro Plus license |
+| **AI Model** | **Any** - Claude, GPT-4, Gemini, Llama, Ollama | NowLLM only (locked in) |
+| **Development** | **Local IDE** - VS Code, Cursor, terminal | Browser-based Studio only |
+| **Enterprise Tools** | **Jira, Azure DevOps, Confluence** | ServiceNow ecosystem only |
+| **Open Source** | **Yes** | No |
 
-### Start Developing
+### What You Get
 
-```bash
-# Use Snow-Flow swarm for any ServiceNow task
-snow-flow swarm "create incident dashboard widget with real-time charts"
-
-# Or launch SnowCode with Snow-Flow tools pre-loaded
-snowcode
-```
+- **410+ MCP Tools** - Complete ServiceNow API coverage
+- **Any LLM Provider** - Claude, GPT-4, Gemini, Mistral, DeepSeek, Groq, or free local models
+- **Local Development** - Pull artifacts to local files, edit with your favorite IDE
+- **Enterprise Integrations** - Jira, Azure DevOps, Confluence (paid tier)
+- **ES5 Validation** - Catches Rhino engine errors before deployment
+- **Update Set Management** - Automatic change tracking
 
 ---
 
-## 💡 LLM Provider Options
-
-Snow-Flow works with **75+ LLM providers** through SnowCode and Models.dev. Choose ANY model that fits your needs!
+## How It Works
 
-### 🌟 Popular Providers
+Snow-Flow uses the Model Context Protocol (MCP) to give AI models direct access to ServiceNow. When you say "create an incident dashboard", the AI:
 
-| Category | Providers | Cost | Best For |
-|----------|-----------|------|----------|
-| **🚀 Premium Cloud** | Claude (Anthropic), GPT-4o (OpenAI), Gemini (Google) | $10-100/mo | Best quality, production use |
-| **💰 Cost-Effective** | Claude Haiku, GPT-4o-mini, Gemini Flash | $1-20/mo | High volume, simple tasks |
-| **🆓 100% Free Local** | Ollama, LM Studio, Jan, LocalAI | $0 | Offline, privacy, unlimited use |
-| **⚡ Specialized** | DeepSeek (coding), Perplexity (research), Groq (speed) | $5-50/mo | Specific use cases |
-| **🏢 Enterprise** | Azure OpenAI, AWS Bedrock, GCP Vertex AI | Custom | Enterprise compliance |
+1. Creates an Update Set to track changes
+2. Builds the widget (HTML, client script, server script)
+3. Deploys to your ServiceNow instance
+4. Validates ES5 compliance and widget coherence
 
-### 🔓 Full Provider List (75+)
-
-**Via SnowCode + Models.dev:**
-- **Anthropic**: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.1
-- **OpenAI**: GPT-5, GPT-4o, GPT-4o-mini
-- **Google**: Gemini 2.0 Flash, Gemini 2.5 Pro, Gemini 2.5 Flash
-- **Meta**: Llama 3.3 (8B, 70B), Llama 3.2, Llama 3.1 (405B)
-- **Mistral AI**: Mistral Large, Mistral Medium, Mistral Small, Codestral
-- **Cohere**: Command R, Command R+
-- **DeepSeek**: DeepSeek Coder, DeepSeek Chat
-- **Groq**: Ultra-fast inference for Llama, Mixtral, Gemma
-- **Perplexity**: Web search-enabled models
-- **OpenRouter**: 200+ models aggregator
-- **Local Models**: Ollama, LM Studio, Jan, LocalAI, vLLM
-- **Enterprise**: Azure OpenAI, AWS Bedrock, GCP Vertex AI
-- **+ 60 more providers!** See [Models.dev](https://models.dev) for complete list
-
-### 💡 Quick Setup Examples
-
-**Claude Pro/Max (No API key needed):**
-```bash
-# .env
-DEFAULT_LLM_PROVIDER=anthropic
-ANTHROPIC_API_KEY=  # Leave empty!
-
-# Authenticate
-snow-flow auth login  # Opens browser automatically
-```
+All through natural conversation.
 
-**OpenAI GPT-4o:**
 ```bash
-# .env
-DEFAULT_LLM_PROVIDER=openai
-OPENAI_API_KEY=sk-...  # From platform.openai.com
-```
+# Create widgets
+snow-flow swarm "create incident dashboard with priority charts and SLA timers"
 
-**100% Free Local (Ollama):**
-```bash
-# Install Ollama
-curl -fsSL https://ollama.com/install.sh | sh
-ollama pull llama3.3
+# Build automation
+snow-flow swarm "create business rule to auto-assign incidents by category"
 
-# .env
-DEFAULT_LLM_PROVIDER=ollama
-OLLAMA_BASE_URL=http://localhost:11434
-```
+# Query data
+snow-flow swarm "show me all P1 incidents from last week"
 
-**Custom/Fine-tuned Models:**
-```bash
-# Any OpenAI-compatible endpoint works!
-DEFAULT_LLM_PROVIDER=openai-compatible
-OPENAI_BASE_URL=https://your-endpoint.com/v1
-OPENAI_API_KEY=your-key
+# Complex workflows
+snow-flow swarm "analyze incident patterns and create a knowledge article with recommendations"
 ```
 
-### 🎯 Recommendations by Use Case
-
-| Use Case | Recommended Provider | Why |
-|----------|---------------------|-----|
-| **Production ServiceNow Development** | Claude Sonnet 4.5 | Best reasoning, ServiceNow knowledge |
-| **Cost-Optimized Development** | GPT-4o-mini or Claude Haiku 4.5 | 10x cheaper, good quality |
-| **Offline/Private Development** | Ollama (Llama 3.3) | 100% free, runs locally |
-| **Code Generation Focus** | DeepSeek Coder | Specialized for coding |
-| **Large Context (200K+ tokens)** | Gemini 2.5 Pro | 2M token context |
-| **Ultra-Fast Prototyping** | Groq (Llama 3.3/Mixtral) | 800+ tokens/sec |
-
-**💡 Pro Tip:** Mix providers! Use cheap models for testing, expensive models for complex widgets.
-
 ---
 
-## 🎯 ServiceNow OAuth Setup
-
-Snow-Flow uses OAuth 2.0 with localhost callback for secure ServiceNow access:
+## Configuration
 
-### Step 1: Create OAuth Application in ServiceNow
+### ServiceNow OAuth Setup
 
-1. **Log into ServiceNow** as administrator
-2. **Navigate to:** System OAuth → Application Registry
-3. **Click:** New → "Create an OAuth API endpoint for external clients"
-4. **Configure the following fields:**
-   - **Name:** `Snow-Flow Integration`
-   - **Redirect URL:** `http://localhost:3005/callback` ⚠️ **CRITICAL: Must be exactly this!**
-   - **Refresh Token Lifespan:** `0` (unlimited)
-   - **Access Token Lifespan:** `1800` (30 minutes)
-5. **Save** the application
-6. **Copy** the generated Client ID and Client Secret
-
-### Step 2: Add Credentials to Environment
-
-Add the credentials to your `.env` file:
+1. In ServiceNow: **System OAuth → Application Registry → New**
+2. Create OAuth endpoint with:
+   - **Redirect URL**: `http://localhost:3005/callback`
+   - **Refresh Token Lifespan**: `0` (unlimited)
+3. Copy Client ID and Secret to `.env`:
 
 ```bash
 SNOW_INSTANCE=your-instance.service-now.com
-SNOW_CLIENT_ID=your-client-id-from-step-1
-SNOW_CLIENT_SECRET=your-client-secret-from-step-1
-```
-
-### Step 3: Authenticate
-
-```bash
-snow-flow auth login
-```
-
-**What happens:**
-1. Snow-Flow starts a temporary localhost server on port 3005
-2. Your browser opens automatically to ServiceNow's OAuth page
-3. You click "Allow" to authorize Snow-Flow
-4. **Choose one option:**
-   - **Option A (Automatic):** Browser redirects back to localhost automatically
-   - **Option B (Manual):** Copy the callback URL from browser and paste it in the terminal
-5. Snow-Flow exchanges the code for access tokens
-6. Done! All MCP servers are now authenticated
-
-**Manual URL paste option:**
-If the browser doesn't redirect automatically, or you prefer manual control:
-1. After clicking "Allow" in ServiceNow, your browser redirects to a URL like:
-   ```
-   http://localhost:3005/callback?code=abc123&state=xyz789
-   ```
-2. Copy this ENTIRE URL from your browser address bar
-3. Paste it in the Snow-Flow terminal when prompted
-4. Snow-Flow will extract the code and complete authentication
-
-### ⚠️ Troubleshooting
-
-**Error: "Invalid redirect_uri"**
-
-This means the redirect URL in your ServiceNow OAuth application doesn't match. Fix it:
-
-1. Go to: System OAuth → Application Registry
-2. Find your Snow-Flow application (search for the Client ID)
-3. Edit the **Redirect URL** field
-4. Change it to: `http://localhost:3005/callback` (exactly this, no typos!)
-5. Save and try `snow-flow auth login` again
-
-**Error: "Port 3005 is already in use"**
-
-Another application is using port 3005. Fix it:
-
-1. Stop any application using port 3005
-2. Or change the port in `.env`:
-   ```bash
-   SNOW_OAUTH_REDIRECT_PORT=3006
-   ```
-3. Update the redirect URL in ServiceNow to match the new port
-
-**Using in GitHub Codespaces or Remote Environments**
-
-The localhost callback works automatically through port forwarding in:
-- ✅ GitHub Codespaces (automatic port forwarding)
-- ✅ VS Code Remote SSH (automatic port forwarding)
-- ✅ Local development (direct localhost access)
-
----
-
-## 🔥 Core Features
-
-### Conversational Development
-
-```bash
-# Create widgets through conversation
-snow-flow swarm "create incident dashboard with priority charts, SLA timers, and mobile-responsive design"
-
-# Automate data operations
-snow-flow swarm "create business rule to auto-assign incidents based on category and priority"
-
-# Train ML models conversationally
-snow-flow swarm "train incident classifier on last 6 months of data"
-```
-
-### 413 ServiceNow Tools (2 MCP Servers)
-
-**ServiceNow Unified Server (237+ tools):**
-- Complete CRUD operations on any table
-- Widget deployment & validation
-- UI Builder components
-- Business rules & client scripts
-- UI actions & policies
-- REST/SOAP integrations
-- Security & compliance
-- Native ServiceNow ML & predictive analytics integration
-- Local artifact development
-
-**Snow-Flow Orchestration (176+ tools):**
-- Multi-agent coordination
-- Local ML training (TensorFlow.js - runs on your machine)
-- Memory management
-- Performance tracking
-- Task orchestration
-
-### Local Development Bridge
-
-```bash
-# Pull ServiceNow artifacts to local files
-snow_pull_artifact({ sys_id: 'widget_sys_id', table: 'sp_widget' })
-
-# Edit locally with full AI coding assistant capabilities:
-# - Multi-file search & replace
-# - Advanced refactoring
-# - Git integration
-# - Native code navigation
-
-# Push back with validation
-snow_push_artifact({ sys_id: 'widget_sys_id' })
-```
-
-### Local ML Training (Alternative to ServiceNow PI)
-
-**⚠️ Important:** ML training runs **locally on your machine**, not in ServiceNow. This is an alternative to ServiceNow's Predictive Intelligence (PI) license.
-
-**How it works:**
-```
-1. Fetch data from ServiceNow via OAuth2 API
-2. Train TensorFlow.js models locally (Node.js)
-3. Models saved in .snow-flow/ml-models/
-4. Make predictions locally
-5. Write results back to ServiceNow via API
-```
-
-**Examples:**
-```bash
-# Incident classification with LSTM networks (fetches ~5000 incidents)
-snow-flow swarm "train incident classifier on description and short_description fields"
-
-# Change risk assessment (fetches historical changes)
-snow-flow swarm "predict change risk for upcoming releases"
-
-# Anomaly detection (fetches system metrics)
-snow-flow swarm "detect anomalies in incident patterns"
+SNOW_CLIENT_ID=your-client-id
+SNOW_CLIENT_SECRET=your-client-secret
 ```
 
-**Key Differences from ServiceNow PI:**
-
-| Feature | ServiceNow PI (Licensed) | Snow-Flow Local ML (Free) |
-|---------|--------------------------|----------------------------|
-| **Runs Where** | Inside ServiceNow | Locally on your machine |
-| **Cost** | $$$ License required | Free (no license) |
-| **Training** | Automatic in ServiceNow | Manual via CLI |
-| **Models** | Stored in ServiceNow | Stored in .snow-flow/ml-models |
-| **Predictions** | Native in ServiceNow | Via custom API calls |
-| **Import to PI** | N/A | ❌ Not possible |
-| **Auto-retrain** | ✅ Yes | ❌ Manual |
-| **Production Ready** | ✅ Yes | ⚠️ Experimental |
-
-**Best For:**
-- ✅ Development/testing without PI license
-- ✅ One-off analyses and predictions
-- ✅ Learning ML concepts with ServiceNow data
-- ❌ Production deployments (use ServiceNow PI instead)
-
----
+### LLM Provider
 
-### Native ServiceNow PI Solution Builder
+Choose any provider:
 
-**🆕 Build Predictive Intelligence solutions conversationally!** Create, train, and activate production-ready ML models directly in ServiceNow through natural language.
-
-**⚠️ Important:** These tools build **native ServiceNow PI solutions** that run INSIDE ServiceNow. Requires Predictive Intelligence license.
-
-**Complete Workflow:**
 ```bash
-# 1. Create PI solution definition
-snow-flow swarm "create predictive intelligence solution to predict incident category based on description"
-
-# 2. Train the model (runs in ServiceNow)
-snow-flow swarm "train the incident category predictor solution"
-
-# 3. Monitor training progress
-snow-flow swarm "check training status of incident category predictor"
-
-# 4. Activate for production use
-snow-flow swarm "activate incident category predictor solution"
-
-# 5. Make predictions
-snow-flow swarm "predict category for incident INC0010001"
-```
-
-**Available PI Tools:**
-- `snow_create_pi_solution` - Create solution definitions (classification, regression, similarity, clustering)
-- `snow_train_pi_solution` - Trigger training (10-30 min in ServiceNow)
-- `snow_monitor_pi_training` - Check training progress and metrics
-- `snow_activate_pi_solution` - Activate for production predictions
-- `snow_list_pi_solutions` - List all PI solutions with metrics
+# Claude (recommended)
+DEFAULT_LLM_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-...
 
-**Example Use Cases:**
-```bash
-# Incident auto-categorization
-snow-flow swarm "build PI solution to auto-categorize incidents based on short_description and description"
+# Or Claude Pro/Max subscription (no API key needed)
+DEFAULT_LLM_PROVIDER=anthropic
+ANTHROPIC_API_KEY=
+# Then run: snow-flow auth login (opens browser)
 
-# Change risk prediction
-snow-flow swarm "create regression model to predict change implementation duration"
+# GPT-4
+DEFAULT_LLM_PROVIDER=openai
+OPENAI_API_KEY=sk-...
 
-# Similar incident finder
-snow-flow swarm "build similarity solution to find related incidents for knowledge reuse"
+# Gemini
+DEFAULT_LLM_PROVIDER=google
+GOOGLE_API_KEY=...
 
-# Work assignment optimization
-snow-flow swarm "create PI solution to predict best assignment group for new incidents"
+# 100% Free - Local Ollama
+DEFAULT_LLM_PROVIDER=ollama
+OLLAMA_BASE_URL=http://localhost:11434
+DEFAULT_OLLAMA_MODEL=llama3.3
 ```
 
-**Key Benefits:**
-- ✅ **Native ServiceNow:** Models run directly in ServiceNow (no external dependencies)
-- ✅ **Production Ready:** Fully integrated with ServiceNow workflows
-- ✅ **Auto-retrain:** Automatic retraining on schedule
-- ✅ **High Performance:** Enterprise-grade ML infrastructure
-- ✅ **Conversational:** Build complex ML solutions through natural language
-
-**Comparison:**
-
-| Feature | Native PI Builder (NEW!) | Local ML Training |
-|---------|-------------------------|-------------------|
-| **Runs Where** | Inside ServiceNow | Locally on your machine |
-| **License** | PI license required | Free (no license) |
-| **Production** | ✅ Yes | ❌ Experimental only |
-| **Auto-retrain** | ✅ Yes | ❌ Manual |
-| **Integration** | ✅ Native | ⚠️ Via API |
-| **Performance** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
-| **Best For** | Production ML in ServiceNow | Dev/testing without license |
-
 ---
 
-## 🆚 Snow-Flow vs ServiceNow Build Agent
-
-See how Snow-Flow's open, flexible approach compares to ServiceNow's proprietary AI solution:
-
-| Feature | Snow-Flow / SnowCode | ServiceNow Build Agent |
-|---------|---------------------|------------------------|
-| **Pricing Model** | Open source + paid enterprise tiers | Proprietary, part of ServiceNow Pro Plus |
-| **Base Cost** | €0 (open source) or €99/dev/month (enterprise) | €100-200/user/month + implementation fees (€150k-€4.5M) |
-| **LLM Choice** | **Any LLM** (Claude, GPT-4, Gemini, Llama, Mistral, DeepSeek, local models) | NowLLM + optional Azure OpenAI |
-| **Development Environment** | **Local + native IDEs** (VS Code, Cursor, Windsurf, terminal) | ServiceNow Studio only (browser-based) |
-| **MCP Tools** | **439 tools** (395 open source + 44 enterprise) | N/A (proprietary API, no MCP) |
-| **Target Users** | Professional developers + technical users | Citizen developers + process owners |
-| **Enterprise Integrations** | **Jira, Azure DevOps, Confluence**, Process Mining, ML tools | ServiceNow ecosystem only |
-| **ML Capabilities** | **TensorFlow.js neural networks** (local training) + Predictive Intelligence integration | RAG-based AI only |
-| **Update Set Management** | **Automated tracking** with intelligent change detection | Manual/limited automated tracking |
-| **ES5 Validation** | **Real-time Rhino checks** (prevents ES6+ syntax errors) | No specific ES5 support |
-| **Open Source** | **Yes** (Elastic-2.0 license) | No (proprietary) |
-| **White-label** | **Yes** (Enterprise tier) | No |
-| **Multi-agent Orchestration** | **Yes** (Queen Agent + 6 specialized agents) | Limited agentic capabilities |
-| **Seat-based Licensing** | **Developer + Stakeholder** roles with granular permissions | Per-user licensing only |
-| **Deployment Options** | **Self-hosted** (local) or **Managed SaaS** (Cloud Run) | ServiceNow Cloud only |
-| **Local Development** | **Yes** (pull artifacts to local files, edit with native tools) | No (browser-only) |
-| **API Integration** | **REST, MCP, stdio** - works with any AI assistant | Proprietary ServiceNow APIs |
-| **Process Mining** | **Included** (enterprise tier) - $100k+/year value | Separate expensive add-on |
-| **Stakeholder Access** | **Free with developer seats** - read-only analytics & dashboards | Full developer license required for all users |
-
-### Why Choose Snow-Flow?
-
-- **Vendor Independence**: Not locked into ServiceNow's AI ecosystem - use any LLM provider
-- **Cost Efficiency**: Free open-source option + affordable enterprise pricing (10-20x cheaper than ServiceNow)
-- **Developer Experience**: Work in your preferred IDE with local development workflows
-- **Enterprise Grade**: 439 tools, seat management, integrations, 99.9% SLA on managed infrastructure
-- **Future-Proof**: Open standards (MCP), portable integrations, no vendor lock-in
+## Enterprise Features
 
----
+For teams that need external tool integrations:
 
-## 📋 Examples
+### Jira Integration
+- Sync stories/epics bidirectionally
+- JQL queries from your AI assistant
+- Automatic status updates
+- Full workflow automation
 
-### Widget Development
-```bash
-snow-flow swarm "create incident dashboard with:
-- Real-time counts by priority
-- ML-powered trend analysis
-- Interactive charts (Chart.js)
-- Mobile-responsive design
-- Dark mode support"
-```
+### Azure DevOps Integration
+- Work item sync (User Stories, Tasks, Bugs)
+- Pipeline status integration
+- Pull request tracking
 
-### Process Automation
-```bash
-snow-flow swarm "create business rule for incident auto-assignment with:
-- Auto-categorization based on description keywords
-- Priority-based assignment rules
-- Team workload balancing
-- Email notifications to assignees"
-```
+### Confluence Integration
+- Documentation sync
+- Knowledge article generation
+- Architecture diagram management
 
-### Security Automation
-```bash
-snow-flow swarm "perform SOX compliance audit on:
-- User access controls
-- Change management ACLs
-- Data encryption settings
-Generate remediation plan for any issues"
-```
+**Pricing:**
+- **Individual**: $99/month (1 developer)
+- **Teams**: $79/user/month (3+ users)
+- **Enterprise**: $49/seat/month (25+ seats, white-label available)
 
-### Data Analysis
-```bash
-snow-flow swarm "analyze incident management process and identify:
-- Bottlenecks
-- Resolution time trends
-- Common root causes
-Provide optimization recommendations"
-```
-
----
-
-## 🤖 Multi-Agent Coordination
-
-Snow-Flow uses SnowCode's native Task() system for intelligent agent teams:
-
-**Available Agent Types:**
-- `widget-creator` - Service Portal widget development
-- `security-specialist` - ACL and compliance validation
-- `ml-specialist` - Machine learning model training
-- `performance-optimizer` - Code and query optimization
-- `integration-specialist` - REST/SOAP integrations
-
-**Automatic coordination:**
-- **Solo Mode**: Simple tasks handled directly
-- **Team Mode**: Complex tasks spawn specialized agent teams
-- **Parallel Execution**: Multiple agents work simultaneously
+Start at [portal.snow-flow.dev](https://portal.snow-flow.dev)
 
 ---
 
-## 🔧 Using with Other AI Coding Assistants
+## Use With Any AI IDE
 
-Snow-Flow works with **any MCP-compatible AI coding assistant**:
+Snow-Flow works with any MCP-compatible tool:
 
-| AI Assistant | How to Connect |
-|-------------|----------------|
-| **Cursor** | Copy `.snow-code/config.json` → `.cursor/mcp.json` |
-| **Windsurf** | Copy `.snow-code/config.json` → `mcp_config.json` |
-| **Continue.dev** | Copy `.snow-code/config.json` → `.continue/mcpServers/snow-flow.json` |
-| **Cline** | Copy `.snow-code/config.json` → `.vscode/mcp.json` |
-| **GitHub Copilot** | Copy `.snow-code/config.json` → `.vscode/mcp.json` |
+| Tool | Setup |
+|------|-------|
+| **snow-code** (recommended) | Built-in, just run `snow-flow swarm` |
+| **Claude Desktop** | Copy config to `claude_desktop_config.json` |
+| **Cursor** | Copy config to `.cursor/mcp.json` |
+| **Windsurf** | Copy config to `mcp_config.json` |
+| **Continue.dev** | Copy config to `.continue/mcpServers/` |
 
-**Quick setup:**
 ```bash
-# After snow-flow init, copy MCP config to your AI assistant
-snow-flow init
-
-# For Cursor
-cp .snow-code/config.json .cursor/mcp.json
+# After snow-flow init, config is at:
+cat .snow-code/config.json
 
-# For Windsurf
-cp .snow-code/config.json mcp_config.json
-
-# Restart your AI assistant → 413 Snow-Flow tools available!
+# Copy to your AI tool's MCP config location
 ```
 
 ---
 
-## 📚 Advanced Configuration
-
-### Environment Variables
-
-See `.env.example` for all options. Key variables:
+## Commands
 
 ```bash
-# ServiceNow
-SNOW_INSTANCE=your-instance.service-now.com
-SNOW_CLIENT_ID=your-client-id
-SNOW_CLIENT_SECRET=your-client-secret
-
-# LLM Provider
-DEFAULT_LLM_PROVIDER=anthropic  # or openai, google, ollama
-
-# Provider-specific
-ANTHROPIC_API_KEY=  # Leave empty for Claude Pro/Max
-OPENAI_API_KEY=your-key
-GOOGLE_API_KEY=your-key
-OLLAMA_BASE_URL=http://localhost:11434
-OLLAMA_MODEL=llama3.3
-
-# Snow-Flow Features
-LOG_LEVEL=info
-ENABLE_PERFORMANCE_TRACKING=true
-ENABLE_MEMORY_SYSTEM=true
-```
-
-### Authentication Commands
+# Core workflow
+snow-flow init          # Initialize project
+snow-flow auth login    # Authenticate (ServiceNow + enterprise)
+snow-flow auth status   # Check authentication status
+snow-flow swarm "task"  # Execute any ServiceNow task
 
-```bash
-# Login (handles LLM + ServiceNow)
-snow-flow auth login
-
-# Check status
-snow-flow auth status
-
-# Logout
-snow-flow auth logout
+# Direct commands
+snow-flow deploy        # Deploy artifacts
+snow-flow status        # System status
 ```
 
-### Common Issues
-
-**"Could not find artifact with sys_id..."**
-- Cause: OAuth token expired
-- Solution: `snow-flow auth login`
-
-**"Invalid redirect_uri"**
-- Cause: Redirect URL mismatch in ServiceNow
-- Solution: Ensure redirect URL is exactly `http://localhost:3005/callback`
-
 ---
 
-## 🎓 Use Cases
+## Requirements
 
-### Development Teams
-- **Conversational development**: Build through natural language
-- **Multi-LLM flexibility**: Choose best provider per task
-- **Local tool integration**: Use familiar development environments
-- **Real-time validation**: Immediate feedback on artifacts
-
-### ServiceNow Administrators
-- **Universal operations**: Query and manage any table
-- **Automated analysis**: ML-powered insights
-- **Batch operations**: Large-scale changes efficiently
-- **Cost optimization**: Use local models for routine tasks
-
-### Solution Architects
-- **Pattern recognition**: Identify and apply best practices
-- **Cross-module integration**: Coordinate complex solutions
-- **Risk assessment**: Analyze impact before implementation
-- **Provider selection**: Choose optimal LLM per phase
+- **Node.js** 18+
+- **ServiceNow** instance with OAuth configured
+- **LLM Provider** - API key or Ollama for free local models
 
 ---
 
-## ⚙️ Requirements
+## Links
 
-- **Node.js**: 18.0.0 or higher
-- **ServiceNow**: Any supported version
-- **LLM Provider**: Any of the supported options above
-- **AI Coding Assistant**: SnowCode (auto-installed) or others
-- **Memory**: 4GB RAM recommended for ML training
-- **Storage**: 1GB free space for models and artifacts
+- **npm**: [npmjs.com/package/snow-flow](https://www.npmjs.com/package/snow-flow)
+- **GitHub**: [github.com/groeimetai/snow-flow](https://github.com/groeimetai/snow-flow)
+- **Enterprise Portal**: [portal.snow-flow.dev](https://portal.snow-flow.dev)
+- **Issues**: [GitHub Issues](https://github.com/groeimetai/snow-flow/issues)
 
 ---
 
-## 🆘 Support & Resources
-
-- **Documentation**: Generated during `snow-flow init`
-- **GitHub**: https://github.com/groeimetai/snow-flow
-- **NPM**: https://www.npmjs.com/package/snow-flow
-- **Issues**: Bug reports and feature requests welcome
-
----
-
-## 🏢 Open Source vs Enterprise Features
-
-Snow-Flow follows an **Open Core** business model. The core framework is 100% open source (Elastic License 2.0), with optional enterprise features available for organizations requiring advanced integrations and support.
-
-### Open Source (Elastic License 2.0) - 100% Free Forever
-
-The current Snow-Flow release includes:
+## License
 
-- ✅ **413 ServiceNow Tools** - Complete API coverage via 2 MCP servers
-- ✅ **75+ LLM Providers** - Claude, GPT-4o, Gemini, Llama, Ollama, Groq, Mistral, DeepSeek, etc.
-- ✅ **Conversational Development** - Build widgets, flows, workspaces through natural language
-- ✅ **Local Development Bridge** - Pull/push artifacts, edit with native tools
-- ✅ **Local ML Training** - TensorFlow.js neural networks (experimental, runs on your machine)
-- ✅ **Native ServiceNow ML** - Predictive Intelligence solution builder (create/train/activate/predict)
-- ✅ **Widget Deployment & Validation** - Coherence checking, ES5 validation
-- ✅ **UI Builder Integration** - Complete Now Experience Framework development
-- ✅ **Multi-Agent Orchestration** - SPARC methodology, swarm coordination
-- ✅ **Update Set Management** - Full lifecycle, auto-sync current update set
-- ✅ **Background Script Execution** - With output capture and auto-confirm mode
-- ✅ **Universal Compatibility** - Works with SnowCode, Claude Code, Cursor, Windsurf, Continue.dev, Cline
-
-**Use for:** Solo developers, small teams, learning, proof-of-concepts, community projects
-
-### Enterprise Features (Commercial License) 🔒
-
-Premium integrations for enterprise ServiceNow teams:
-
-- 🔒 **Jira Backlog Sync** - Bi-directional sync with AI-powered requirement parsing
-  - Auto-import stories/epics from Jira to ServiceNow tasks
-  - Real-time webhook updates (Jira ↔ ServiceNow)
-  - AI extracts acceptance criteria, technical requirements
-  - Developer workflow: `snow-flow dev start SNOW-456` loads full Jira context
-
-- 🔒 **Azure DevOps Integration** - Complete ALM integration
-  - Work item sync (User Stories, Tasks, Bugs)
-  - Pull request tracking to ServiceNow
-  - Build pipeline status integration
-  - Test results auto-documented
-
-- 🔒 **Confluence Documentation Sync** - Auto-sync technical documentation
-  - Confluence pages → ServiceNow knowledge articles
-  - Technical specs → Implementation guides
-  - Architecture diagrams → Attachment sync
-
-- 🔒 **Enterprise SSO/SAML** - Single sign-on integration (in development)
-  - SAML 2.0, OAuth 2.0, OIDC
-  - Active Directory/LDAP integration
-  - Role-based access control (RBAC) with read-only enforcement for stakeholders
-
-- 🔒 **Advanced Audit Logging** - Comprehensive activity tracking
-  - Every AI action logged with audit trail
-  - Compliance reporting (SOX, GDPR, HIPAA)
-  - Tamper-proof log storage
-
-- 🔒 **SLA-Backed Support** - Enterprise support agreements
-  - 24/7 support with 4-hour response SLA
-  - Dedicated technical account manager
-  - Priority feature requests
-  - Custom integration development
-
-- 🔒 **Advanced ML Features** - Enhanced predictive intelligence
-  - Auto-retrain on schedule
-  - A/B testing for ML models
-  - Multi-model ensembles
-  - Custom feature engineering
-
-**Use for:** Enterprise teams (20+ developers), consulting firms, ISVs, production deployments
-
-### Pricing (Coming Q2 2025)
-
-Enterprise features will be available via seat-based commercial license:
-
-**License Format:** `SNOW-[TIER]-[ORG]-[DEV_SEATS]/[STAKEHOLDER_SEATS]-[EXPIRY]-[CHECKSUM]`
-
-**Seat Types:**
-- **Developer Seats:** Full read/write access to all 413 MCP tools via CLI/TUI
-- **Stakeholder Seats:** Read-only CLI/TUI access for queries and analytics (no write operations)
-
-**Pricing Tiers:**
-- **Professional:** €499/month (5 developer seats + 2 stakeholder seats)
-- **Team:** €999/month (20 developer seats + 10 stakeholder seats)
-- **Enterprise:** €1,999/month (unlimited seats)
-
-All tiers include:
-- All open source features
-- Enterprise integrations (Jira/Azure DevOps/Confluence)
-- Enterprise SSO/SAML (in development)
-- Audit logging
-- Seat tracking and management
-- Email support (SLA varies by tier)
-
-**License Management:**
-- License parsing (developer/stakeholder seat counts)
-- Role assignment and tracking
-- Seat usage display in CLI
-- User management in enterprise portal
-
-**Role-Based Access Control:**
-- Stakeholder read-only enforcement (290/380 tools classified for permission control)
-- Seat limit enforcement at connection time
-- Active session tracking and monitoring
-- Role-based permission validation
-
-Contact [sales@snow-flow.dev](mailto:sales@snow-flow.dev) for enterprise license.
-
-**Strategic Partners:** Consulting firms and ISVs - contact us for partnership opportunities.
-
-### Why Open Core?
-
-1. **Community-Driven Innovation** - Core features benefit from community contributions
-2. **Transparent Development** - All core development happens in public
-3. **No Lock-In** - Open source core means you can self-host and modify
-4. **Sustainable Development** - Enterprise revenue funds ongoing development
-5. **Enterprise Confidence** - Commercial license provides support and guarantees
-
-### Features
-
-**Open Source**
-- Native ServiceNow Predictive Intelligence tools
-- UI Builder complete integration
-- 75+ LLM provider support
-- Local development bridge
-- Seat-based licensing infrastructure
-
-**Stakeholder Seats & RBAC**
-- Stakeholder read-only enforcement (290/380 tools classified as read/write)
-- Seat limit enforcement with active session tracking
-- Role-based access control (developer/stakeholder/admin)
-- Session management API endpoints
-
-**Enterprise (Commercial License)**
-- Jira, Azure DevOps, Confluence integrations (in development)
-- Enterprise SSO/SAML (in development)
-- Advanced audit logging
-- Multi-tenant architecture
-- White-label options
-- AI-powered code review
-- Automated testing frameworks
-
-See [MONETIZATION_STRATEGY.md](./MONETIZATION_STRATEGY.md) for complete business model details.
+Elastic License 2.0 - Free for commercial use, cannot resell as competing SaaS.
 
 ---
 
-## 💰 Pricing & Plans
-
-Snow-Flow offers a transparent 3-tier pricing model designed for individual developers, teams, and service integrators.
-
-### 🆓 Open Source (Free Forever)
-
-**350+ ServiceNow MCP Tools** - Zero cost, full access to core framework
-
-**What's Included:**
-- ✅ All 350+ ServiceNow tools (ITSM, CMDB, Flow Designer, UI Builder, etc.)
-- ✅ Local MCP servers (self-hosted)
-- ✅ Unlimited ServiceNow instances
-- ✅ Community support (GitHub Discussions)
-- ✅ Elastic License 2.0 (free commercial use)
-
-**Perfect for:** Individual developers, students, learning, open source projects
+**Snow-Flow** - The free, open-source ServiceNow Build Agent alternative. Built by developers, for developers.
 
 ```bash
-npm install -g snow-flow
-snow-flow init
-# Start building immediately - no credit card required!
-```
-
----
-
-### 👤 Individual Plan - $99/month
-
-**Everything in Open Source +** enterprise tools & managed SaaS infrastructure
-
-**What's Included:**
-- ✅ **40+ Enterprise MCP Tools:**
-  - 🔷 Azure DevOps (10 tools) - work items, pipelines, PRs
-  - 🟦 Jira (8 tools) - backlog sync, JQL queries, issue tracking
-  - 📚 Confluence (8 tools) - documentation sync, page management
-  - 🤖 ML & Analytics (15+ tools) - predictive intelligence, forecasting
-- ✅ **Fully Managed SaaS** - hosted on Google Cloud (europe-west4)
-- ✅ **Zero Maintenance** - automatic updates, no server management
-- ✅ **Email Support** - business hours support (24h response time)
-- ✅ **99.9% SLA** - enterprise-grade reliability
-
-**Perfect for:** Freelance consultants, solo practitioners, side projects
-
-**How it works:**
-1. Subscribe at [portal.snow-flow.dev](https://portal.snow-flow.dev)
-2. Receive enterprise license key
-3. Add key to Snow-Flow config - enterprise MCP servers auto-activate
-4. Start using Jira/Azure/Confluence tools immediately
-
----
-
-### 👥 Teams Plan - $79/user/month
-
-**Everything in Individual +** team collaboration & priority support
-
-**What's Included:**
-- ✅ All Individual plan features
-- ✅ **Team Dashboard** - centralized license management
-- ✅ **Usage Analytics** - track team tool usage and costs
-- ✅ **Priority Support** - 4-hour response time, Slack channel
-- ✅ **Team Onboarding** - setup session with solutions architect
-- ✅ **Volume Discount** - save 20% vs Individual ($79 vs $99/user)
-
-**Minimum:** 3 users
-**Perfect for:** Development teams, agencies, consulting firms
-
----
-
-### 🏢 Enterprise (Service Integrators)
-
-**Wholesale pricing** for service integrators and consulting firms
-
-**What's Included:**
-- ✅ All Teams plan features
-- ✅ **White-Label Portal** - branded customer experience
-- ✅ **Wholesale Pricing** - $49/seat/month (50+ seats)
-- ✅ **Partner Margins** - resell at $69-79/seat, keep 40-75% margin
-- ✅ **24/7 Priority Support** - dedicated support team
-- ✅ **Custom Integrations** - build custom MCP tools for your organization
-- ✅ **Deployment Flexibility** - cloud or on-premise options
-- ✅ **SOC 2 / ISO 27001** - enterprise compliance ready
-
-**Minimum:** 25 seats
-**Perfect for:** Service integrators, large consulting firms, managed service providers
-
-**ROI Example:**
-- Wholesale cost: $49/seat × 50 consultants = $2,450/month
-- Resell at: $69/seat × 50 consultants = $3,450/month
-- **Your margin: $1,000/month (41%)** + faster delivery = more projects
-
-**Contact:** [sales@snow-flow.dev](mailto:sales@snow-flow.dev) for custom enterprise pricing
-
----
-
-### 📊 Plan Comparison
-
-| Feature | Open Source | Individual | Teams | Enterprise |
-|---------|-------------|------------|-------|------------|
-| **ServiceNow Tools** | 350+ tools | 350+ tools | 350+ tools | 350+ tools |
-| **Enterprise Tools** | ❌ | 40+ tools | 40+ tools | 40+ tools |
-| **Jira/Azure/Confluence** | ❌ | ✅ | ✅ | ✅ |
-| **Managed SaaS** | ❌ Self-hosted | ✅ Cloud-hosted | ✅ Cloud-hosted | ✅ Cloud-hosted |
-| **Support** | Community | Email (24h) | Priority (4h) | 24/7 Dedicated |
-| **SLA** | None | 99.9% | 99.9% | 99.95% |
-| **White-Label** | ❌ | ❌ | ❌ | ✅ |
-| **Team Dashboard** | ❌ | ❌ | ✅ | ✅ |
-| **Custom Integrations** | ❌ | ❌ | ❌ | ✅ |
-| **Price** | **Free** | **$99/mo** | **$79/user/mo** | **$49/seat/mo** |
-
----
-
-### 🎯 Which Plan is Right for You?
-
-**Choose Open Source if:**
-- You're learning ServiceNow development
-- You're working on personal/open source projects
-- You only need ServiceNow tools (no Jira/Azure/Confluence)
-- You can self-host MCP servers locally
-
-**Choose Individual if:**
-- You're a freelance consultant or solo practitioner
-- You need Jira/Azure/Confluence integration
-- You want zero server maintenance (managed SaaS)
-- You bill clients and can expense the subscription
-
-**Choose Teams if:**
-- You're a development team (3-25 people)
-- You need team collaboration and analytics
-- You want priority support and onboarding
-- You want to save 20% vs Individual pricing
-
-**Choose Enterprise if:**
-- You're a service integrator or consulting firm
-- You have 25+ consultants using ServiceNow
-- You want to resell Snow-Flow to your customers
-- You need white-label branding and custom integrations
-
----
-
-### 💳 Payment & Billing
-
-- **Monthly billing** - cancel anytime, no annual commitment required
-- **Annual discount** - save 2 months (pay for 10, get 12)
-- **Payment methods** - credit card, wire transfer (Enterprise only)
-- **Invoicing** - automatic monthly invoices for accounting
-- **Tax** - prices exclude VAT/sales tax (added at checkout)
-
-**Start free trial:** 14-day free trial on Individual/Teams plans - no credit card required
-
-👉 **[Get Started](https://portal.snow-flow.dev/signup)** | **[Contact Sales](mailto:sales@snow-flow.dev)**
-
----
-
-## 📄 License
-
-**Core Framework:** Elastic License 2.0 - see [LICENSE](LICENSE) file for details.
-
-**What this means:**
-- ✅ **Free to use internally**: Companies can use Snow-Flow for their own ServiceNow development
-- ✅ **Commercial use allowed**: Use for commercial projects, consulting, client work
-- ✅ **Modify and redistribute**: Fork, modify, and share the source code
-- ✅ **Full source code access**: Complete transparency, no hidden code
-- ⚠️ **Cannot resell as SaaS**: You cannot offer "Snow-Flow-as-a-Service" to compete with our managed platform
-- ⚠️ **Keep attribution**: Cannot remove licensing/copyright notices
-
-**Examples:**
-- ✅ **OK**: Accenture uses Snow-Flow internally for ServiceNow projects
-- ✅ **OK**: Consultant shares Snow-Flow with client who self-hosts it
-- ✅ **OK**: Fork Snow-Flow and create custom version for your organization
-- ❌ **NOT OK**: Launch "MyCompany Snow-Flow Hosting" as a paid SaaS product
-
-**Trademark:** "Snow-Flow" name and logo are protected trademarks - see [TRADEMARK.md](./TRADEMARK.md).
-
-**Enterprise Features:** Commercial license required - contact [sales@snow-flow.dev](mailto:sales@snow-flow.dev).
-
----
-
-**Snow-Flow: Conversational ServiceNow Development**
-• 413 Tools • 2 MCP Servers • 75+ LLM Providers • Universal Compatibility
-
-**Get started in 3 minutes:**
-```bash
-npm install -g snow-flow
-snow-flow init
-snow-flow auth login
-snow-flow swarm "create incident dashboard"
+npm install -g snow-flow && snow-flow init && snow-flow auth login && snow-flow swarm "hello servicenow"
 ```