cursorflow 1.3.1__tar.gz → 1.3.2__tar.gz

{cursorflow-1.3.1 → cursorflow-1.3.2}/MANIFEST.in

@@ -40,10 +40,14 @@ exclude __pycache__/*
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]
 
-# EXCLUDE: Configuration and rules (internal use)
+# INCLUDE: Cursor rules for AI integration
+include rules/cursorflow-installation.mdc
+include rules/cursorflow-usage.mdc
+
+# Rules installation script is now in cursorflow/ package
+
+# EXCLUDE: Configuration files
 exclude config/*
-exclude rules/*
-exclude install_cursorflow_rules.py
 exclude PERSISTENT_SESSION_SUMMARY.md
 
 # EXCLUDE: Artifacts and temporary files

{cursorflow-1.3.1 → cursorflow-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 1.3.1
+Version: 1.3.2
 Summary: Complete page intelligence for AI-driven development - captures DOM, network, console, and performance data
 Author-email: GeekWarrior Development <support@cursorflow.dev>
 License-Expression: MIT

cursorflow-1.3.2/cursorflow/install_cursorflow_rules.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""
+CursorFlow Rules Installation Script
+
+Installs CursorFlow usage rules into a user's project for Cursor AI.
+Run this in your project directory to enable CursorFlow integration.
+"""
+
+import os
+import shutil
+import json
+import datetime
+from pathlib import Path
+import argparse
+
+
+def install_cursorflow_rules(project_dir: str = "."):
+    """Install CursorFlow rules and configuration in user's project"""
+    
+    project_path = Path(project_dir).resolve()
+    print(f"🚀 Installing CursorFlow rules in: {project_path}")
+    
+    # Create .cursor directory if it doesn't exist
+    cursor_dir = project_path / ".cursor"
+    cursor_dir.mkdir(exist_ok=True)
+    
+    rules_dir = cursor_dir / "rules"
+    rules_dir.mkdir(exist_ok=True)
+    
+    print(f"📁 Created Cursor rules directory: {rules_dir}")
+    
+    # Find CursorFlow package location
+    try:
+        import cursorflow
+        package_dir = Path(cursorflow.__file__).parent.parent
+        rules_source_dir = package_dir / "rules"
+    except ImportError:
+        # Fallback: look for rules in current directory structure
+        current_dir = Path(__file__).parent
+        rules_source_dir = current_dir.parent / "rules"  # Go up one level from cursorflow/ to find rules/
+        
+    if not rules_source_dir.exists():
+        print(f"❌ Could not find CursorFlow rules directory at: {rules_source_dir}")
+        return False
+    
+    # Copy usage rules (not development rules)
+    usage_rules = [
+        "cursorflow-usage.mdc",
+        "cursorflow-installation.mdc"
+    ]
+    
+    copied_files = []
+    for rule_file in usage_rules:
+        source_file = rules_source_dir / rule_file
+        target_file = rules_dir / rule_file
+        
+        if source_file.exists():
+            shutil.copy2(source_file, target_file)
+            copied_files.append(rule_file)
+            print(f"✅ Installed: {rule_file}")
+        else:
+            print(f"⚠️  Rule file not found: {rule_file}")
+    
+    # Create project-specific .gitignore entries
+    create_gitignore_entries(project_path)
+    
+    # Create CursorFlow configuration template
+    create_config_template(project_path)
+    
+    print(f"\n🎉 CursorFlow rules installation complete!")
+    print(f"📋 Installed {len(copied_files)} rule files:")
+    for file in copied_files:
+        print(f"   - {file}")
+    
+    # Set up automatic update checking
+    setup_update_checking(project_path)
+    
+    print(f"\n📝 Next steps:")
+    print(f"   1. Review cursorflow-config.json and update for your project")
+    print(f"   2. Install CursorFlow: pip install cursorflow")
+    print(f"   3. Install Playwright: playwright install chromium")
+    print(f"   4. Start using CursorFlow for UI testing and CSS iteration!")
+    print(f"\n🔄 Update commands:")
+    print(f"   - Check for updates: python -m cursorflow check-updates")
+    print(f"   - Update CursorFlow: python -m cursorflow update")
+    print(f"   - Install dependencies: python -m cursorflow install-deps")
+    
+    return True
+
+
+def create_gitignore_entries(project_path: Path):
+    """Add CursorFlow artifacts to .gitignore"""
+    
+    gitignore_path = project_path / ".gitignore"
+    
+    cursorflow_entries = """
+# CursorFlow artifacts (UI testing framework)
+.cursorflow/
+*.cursorflow.log
+cursorflow_session_*.json
+"""
+    
+    # Check if entries already exist
+    existing_content = ""
+    if gitignore_path.exists():
+        existing_content = gitignore_path.read_text()
+    
+    if ".cursorflow/" not in existing_content:
+        with open(gitignore_path, "a") as f:
+            f.write(cursorflow_entries)
+        print("✅ Added CursorFlow entries to .gitignore")
+    else:
+        print("ℹ️  CursorFlow entries already in .gitignore")
+
+
+def create_config_template(project_path: Path):
+    """Create CursorFlow configuration template"""
+    
+    config_path = project_path / "cursorflow-config.json"
+    
+    if config_path.exists():
+        print("ℹ️  cursorflow-config.json already exists")
+        return
+    
+    # Auto-detect project type for better defaults
+    project_type = detect_project_type(project_path)
+    
+    config_template = {
+        "base_url": get_default_url(project_type),
+        "logs": get_default_log_config(project_type),
+        "auth": {
+            "method": "form",
+            "username_selector": "#username",
+            "password_selector": "#password", 
+            "submit_selector": "#login-button",
+            "session_storage": ".cursorflow/sessions/"
+        },
+        "browser": {
+            "headless": True,
+            "debug_mode": False
+        },
+        "_project_type": project_type,
+        "_cursorflow_version": "1.0.0"
+    }
+    
+    import json
+    with open(config_path, "w") as f:
+        json.dump(config_template, f, indent=2)
+    
+    print(f"✅ Created configuration template: cursorflow-config.json")
+    print(f"   Detected project type: {project_type}")
+
+
+def detect_project_type(project_path: Path) -> str:
+    """Detect project type for better defaults"""
+    
+    if (project_path / "package.json").exists():
+        package_json = project_path / "package.json"
+        try:
+            import json
+            with open(package_json) as f:
+                package_data = json.load(f)
+            
+            dependencies = package_data.get("dependencies", {})
+            dev_dependencies = package_data.get("devDependencies", {})
+            all_deps = {**dependencies, **dev_dependencies}
+            
+            if "next" in all_deps:
+                return "nextjs"
+            elif "react" in all_deps:
+                return "react"
+            elif "vue" in all_deps:
+                return "vue"
+            else:
+                return "nodejs"
+        except:
+            return "nodejs"
+    
+    elif (project_path / "manage.py").exists():
+        return "django"
+    
+    elif (project_path / "composer.json").exists():
+        return "php"
+    
+    elif (project_path / "Gemfile").exists():
+        return "rails"
+    
+    elif any((project_path / f).exists() for f in ["*.pl", "*.pm"]):
+        return "perl"
+    
+    else:
+        return "generic"
+
+
+def get_default_url(project_type: str) -> str:
+    """Get default development server URL"""
+    
+    defaults = {
+        "nextjs": "http://localhost:3000",
+        "react": "http://localhost:3000",
+        "vue": "http://localhost:8080",
+        "nodejs": "http://localhost:3000",
+        "django": "http://localhost:8000",
+        "php": "http://localhost:8080",
+        "rails": "http://localhost:3000",
+        "perl": "http://localhost:8080",
+        "generic": "http://localhost:3000"
+    }
+    
+    return defaults.get(project_type, "http://localhost:3000")
+
+
+def get_default_log_config(project_type: str) -> dict:
+    """Get default log configuration"""
+    
+    log_configs = {
+        "nextjs": {"source": "local", "paths": [".next/trace.log", "logs/app.log"]},
+        "react": {"source": "local", "paths": ["logs/app.log", "console.log"]},
+        "vue": {"source": "local", "paths": ["logs/app.log"]},
+        "nodejs": {"source": "local", "paths": ["logs/app.log", "npm-debug.log"]},
+        "django": {"source": "local", "paths": ["logs/django.log", "logs/debug.log"]},
+        "php": {"source": "local", "paths": ["storage/logs/laravel.log", "logs/error.log"]},
+        "rails": {"source": "local", "paths": ["log/development.log", "log/test.log"]},
+        "perl": {"source": "ssh", "host": "staging-server", "paths": ["/var/log/httpd/error_log"]},
+        "generic": {"source": "local", "paths": ["logs/app.log"]}
+    }
+    
+    return log_configs.get(project_type, {"source": "local", "paths": ["logs/app.log"]})
+
+
+def setup_update_checking(project_path: Path):
+    """Set up automatic update checking configuration"""
+    
+    cursorflow_dir = project_path / ".cursorflow"
+    cursorflow_dir.mkdir(exist_ok=True)
+    
+    # Create update preferences
+    update_prefs = {
+        "check_interval_hours": 24,
+        "auto_update": False,
+        "include_prereleases": False,
+        "backup_before_update": True,
+        "last_check": None
+    }
+    
+    prefs_file = cursorflow_dir / "update_preferences.json"
+    with open(prefs_file, 'w') as f:
+        json.dump(update_prefs, f, indent=2)
+    
+    # Create initial version tracking
+    version_info = {
+        "installed_version": "1.0.0",
+        "rules_version": "1.0.0",
+        "installation_date": str(datetime.datetime.now().isoformat())
+    }
+    
+    version_file = cursorflow_dir / "version_info.json"
+    with open(version_file, 'w') as f:
+        json.dump(version_info, f, indent=2)
+    
+    print("✅ Update checking configured")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Install CursorFlow rules in a project")
+    parser.add_argument("--project-dir", default=".", help="Project directory (default: current directory)")
+    
+    args = parser.parse_args()
+    
+    success = install_cursorflow_rules(args.project_dir)
+    exit(0 if success else 1)

{cursorflow-1.3.1 → cursorflow-1.3.2}/cursorflow.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ setup.py
 cursorflow/__init__.py
 cursorflow/auto_updater.py
 cursorflow/cli.py
+cursorflow/install_cursorflow_rules.py
 cursorflow/updater.py
 cursorflow/core/agent.py
 cursorflow/core/auth_handler.py
@@ -28,4 +29,6 @@ docs/USER_MANUAL.md
 examples/comprehensive_screenshot_example.py
 examples/mockup_comparison_example.py
 examples/opensas_example.py
-examples/react_example.py
+examples/react_example.py
+rules/cursorflow-installation.mdc
+rules/cursorflow-usage.mdc

{cursorflow-1.3.1 → cursorflow-1.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cursorflow"
-version = "1.3.1"
+version = "1.3.2"
 description = "Complete page intelligence for AI-driven development - captures DOM, network, console, and performance data"
 authors = [
     {name = "GeekWarrior Development", email = "support@cursorflow.dev"}

cursorflow-1.3.2/rules/cursorflow-installation.mdc

@@ -0,0 +1,297 @@
+---
+title: CursorFlow CLI Installation & Setup Guide for Cursor
+description: How to install and configure CursorFlow CLI in any project for autonomous UI testing
+---
+
+# CursorFlow CLI Installation & Setup Guide for Cursor
+
+## 🚀 **When to Install CursorFlow**
+
+### **Automatically Install When:**
+- User mentions UI testing, visual debugging, or layout issues
+- User asks to "test this component" or "check if this works"
+- User is working on CSS/layout modifications
+- User reports frontend bugs or authentication issues
+- New project setup where UI testing would be valuable
+
+### **Project Types That Benefit:**
+- Web applications (React, Vue, Angular, PHP, Django, Rails)
+- Component libraries and design systems
+- E-commerce sites with complex user flows
+- Admin dashboards and data visualization
+- Any project with user authentication
+
+## 📦 **Installation Steps**
+
+### **1. Install CursorFlow CLI:**
+```bash
+# Install the universal testing CLI
+pip install cursorflow
+
+# Install browser automation dependencies
+cursorflow install-deps
+
+# Verify installation
+cursorflow --version
+```
+
+### **2. Initialize Project:**
+```bash
+# Initialize CursorFlow in the project (creates config + installs rules)
+cursorflow init .
+
+# This automatically:
+# - Creates cursor-test-config.json with smart defaults
+# - Sets up .cursorflow/ directory structure
+# - Configures for your web technology
+```
+
+### **3. Verify Installation:**
+```bash
+# Test basic functionality
+cursorflow test --base-url http://localhost:3000 --path "/"
+
+# Check configuration
+cat cursor-test-config.json
+
+# Verify artifacts directory
+ls -la .cursorflow/
+```
+
+## ⚙️ **Auto-Generated Configuration**
+
+CursorFlow creates smart defaults based on your project:
+
+```json
+{
+  "environments": {
+    "local": {
+      "base_url": "http://localhost:3000",
+      "logs": "local",
+      "log_paths": {
+        "app": "logs/app.log"
+      }
+    },
+    "staging": {
+      "base_url": "https://staging.example.com",
+      "logs": "ssh",
+      "ssh_config": {
+        "hostname": "staging-server",
+        "username": "deploy"
+      },
+      "log_paths": {
+        "app_error": "/var/log/app/error.log"
+      }
+    }
+  }
+}
+```
+
+## 🎯 **Quick Start Examples**
+
+### **Test a Component:**
+```bash
+# Test any UI component
+cursorflow test dashboard --base-url http://localhost:3000
+
+# Results in structured JSON + artifacts:
+# - Browser interaction timeline
+# - Screenshots in .cursorflow/artifacts/
+# - Console logs and server logs
+# - Network requests and responses
+```
+
+### **Debug Authentication:**
+```bash
+# Test login flow
+cursorflow test login-form --base-url http://localhost:3000
+
+# Analyze output for:
+# - Authentication errors in timeline
+# - Session state issues
+# - Server response patterns
+```
+
+### **CSS Iteration:**
+```bash
+# Before: Test current state
+cursorflow test dashboard --base-url http://localhost:3000
+
+# Apply CSS changes to actual files
+# After: Test improved state  
+cursorflow test dashboard --base-url http://localhost:3000
+
+# Compare screenshots in .cursorflow/artifacts/
+```
+
+## 🌍 **Environment-Specific Setup**
+
+### **Local Development:**
+```json
+{
+  "local": {
+    "base_url": "http://localhost:3000",
+    "logs": "local",
+    "log_paths": {"app": "logs/app.log"}
+  }
+}
+```
+
+### **Staging/Production Testing:**
+```json
+{
+  "staging": {
+    "base_url": "https://staging.example.com", 
+    "logs": "ssh",
+    "ssh_config": {
+      "hostname": "staging-server",
+      "username": "deploy",
+      "key_file": "~/.ssh/staging_key"
+    },
+    "log_paths": {
+      "app_error": "/var/log/app/error.log",
+      "access_log": "/var/log/nginx/access.log"
+    }
+  }
+}
+```
+
+## 📋 **Verification Steps**
+
+### **Test CLI Installation:**
+```bash
+# Check version
+cursorflow --version
+
+# View available commands
+cursorflow --help
+
+# Test project initialization
+cursorflow init test-project
+
+# Verify config creation
+cat test-project/cursor-test-config.json
+```
+
+### **Test Component Testing:**
+```bash
+# Test any component (requires running dev server)
+cursorflow test component-name --base-url http://localhost:3000
+
+# Check artifacts were created
+ls -la .cursorflow/artifacts/sessions/
+
+# Verify JSON output structure
+# Should contain: timeline, artifacts, summary
+```
+
+## 🚨 **Troubleshooting Common Issues**
+
+### **Installation Problems:**
+```bash
+# If pip install fails
+pip install --upgrade pip
+pip install cursorflow --no-cache-dir
+
+# If browser dependencies missing
+cursorflow install-deps
+
+# If permission issues
+pip install --user cursorflow
+```
+
+### **Configuration Issues:**
+```bash
+# Re-initialize project
+rm cursor-test-config.json
+cursorflow init .
+
+# Check config validity
+cat cursor-test-config.json
+
+# Test with explicit URL
+cursorflow test homepage --base-url http://localhost:3000
+```
+
+### **Testing Issues:**
+```bash
+# Verify dev server is running
+curl http://localhost:3000
+
+# Check artifacts directory permissions
+ls -la .cursorflow/
+
+# View detailed help
+cursorflow test --help
+```
+
+## 💡 **Best Practices for Installation**
+
+### **1. Project-Specific Setup**
+- Always run `cursorflow init .` in each project
+- Customize cursor-test-config.json for your stack
+- Test locally before staging/production
+
+### **2. Team Setup**
+- Add cursor-test-config.json to version control
+- Document environment-specific settings
+- Share CLI commands for common workflows
+
+### **3. Maintenance**
+```bash
+# Check for updates
+cursorflow check-updates
+
+# Update CursorFlow and rules
+cursorflow update
+
+# Keep browser dependencies current
+cursorflow install-deps
+```
+
+## 🎪 **Essential CLI Commands**
+
+### **Setup:**
+```bash
+pip install cursorflow    # Install CLI
+cursorflow init .         # Initialize project
+cursorflow install-deps   # Install browser automation
+```
+
+### **Testing:**
+```bash
+cursorflow test component --base-url http://localhost:3000
+cursorflow auto-test      # Auto-detect and test
+```
+
+### **Maintenance:**
+```bash
+cursorflow check-updates  # Check for new versions
+cursorflow update        # Update package and rules
+cursorflow --help        # View all commands
+```
+
+## 🎯 **Success Criteria**
+
+### **Installation Complete When:**
+- `cursorflow --version` shows current version
+- `cursorflow init .` creates cursor-test-config.json
+- `cursorflow test component` returns structured JSON
+- `.cursorflow/artifacts/` directory contains test results
+
+### **Ready for Autonomous Operation When:**
+- All CLI commands work without errors
+- Configuration matches your development environment  
+- Test artifacts are created and organized properly
+- Cursor can use `cursorflow test` for any component
+
+## 🌟 **Result: Cursor Superpowers Activated!**
+
+Once installed, Cursor can autonomously:
+- Test any UI component with simple CLI commands
+- Collect comprehensive browser and server data
+- Analyze results and make informed decisions
+- Iterate on designs with visual feedback
+- Debug issues with complete visibility
+
+**Installation complete = Development superpowers activated!** 🚀

cursorflow-1.3.2/rules/cursorflow-usage.mdc

@@ -0,0 +1,423 @@
+# CursorFlow Usage Rules for Cursor AI
+
+## 🔥 **PRIMARY USE CASE: Hot Reload CSS Iteration**
+
+**ALWAYS USE `css_iteration_persistent()` for CSS/UI work** - this is CursorFlow's core strength:
+
+- 🚀 **3-5x faster** than normal testing with hot reload integration
+- 🎯 **Preserves application state** during CSS iterations  
+- 🔥 **Automatic hot reload detection** (Webpack HMR, Vite, Next.js, etc.)
+- ⚡ **Instant visual feedback** without page reloads
+- 🧠 **Intelligent session management** with automatic cleanup
+
+## When to Use CursorFlow
+
+### **CSS/UI Development (PRIORITY 1 - Use Persistent Sessions)**
+- CSS styling, layout adjustments, responsive design
+- Visual hierarchy improvements, spacing, typography
+- Component styling and design system work
+- UI bug fixes and visual improvements
+- Design iteration and rapid prototyping
+
+### **UI Testing & Debugging (Use CLI)**
+- Form submissions and user interactions  
+- Authentication flows and session handling
+- Frontend-backend interaction problems
+- Error reproduction and debugging
+- Cross-browser compatibility testing
+
+## 🔥 **Hot Reload CSS Iteration (PRIMARY METHOD)**
+
+### **Ultra-Fast CSS Iteration Pattern**
+```python
+from cursorflow import CursorFlow
+
+# Initialize with hot reload support
+flow = CursorFlow(
+    base_url="http://localhost:3000",  # Your dev server
+    log_config={"source": "local", "paths": ["logs/app.log"]},
+    browser_config={"hot_reload_enabled": True, "keep_alive": True}
+)
+
+# CSS changes to test rapidly
+css_changes = [
+    {
+        "name": "improve-spacing", 
+        "css": ".container { gap: 2rem; padding: 1.5rem; }",
+        "rationale": "Better visual hierarchy"
+    },
+    {
+        "name": "add-shadows",
+        "css": ".card { box-shadow: 0 4px 6px rgba(0,0,0,0.1); }",
+        "rationale": "Add depth and visual interest"
+    }
+]
+
+# Execute with persistent session - 3-5x faster!
+results = await flow.css_iteration_persistent(
+    base_actions=[{"navigate": "/dashboard"}, {"wait_for": "#main-content"}],
+    css_changes=css_changes,
+    session_options={"hot_reload": True, "keep_session_alive": True}
+)
+
+# Analyze results
+print(f"🔥 Hot reload used: {results.get('hot_reload_used')}")
+print(f"⚡ Iterations/min: {results.get('persistent_analysis', {}).get('iteration_speed_metrics', {}).get('iterations_per_minute', 0):.1f}")
+```
+
+### **Session Continuation (No Page Reload!)**
+```python
+# First iteration - sets up persistent session
+results1 = await flow.css_iteration_persistent(
+    base_actions=[{"navigate": "/page"}],
+    css_changes=[{"name": "initial", "css": ".container { display: flex; }"}],
+    session_options={"session_id": "my_session", "keep_session_alive": True}
+)
+
+# Continue with same session - INSTANT feedback!
+results2 = await flow.css_iteration_persistent(
+    base_actions=[],  # No base actions needed - session preserved!
+    css_changes=[{"name": "refine", "css": ".container { gap: 1rem; }"}],
+    session_options={"session_id": "my_session", "reuse_session": True}
+)
+```
+
+### **Hot Reload Decision Framework**
+1. **User mentions CSS/styling** → Use `css_iteration_persistent()`
+2. **User wants UI improvements** → Use persistent sessions  
+3. **User asks to "test this component"** → Use hot reload iteration
+4. **User reports layout issues** → Use CSS iteration with screenshots
+5. **User wants responsive testing** → Use persistent sessions with viewport changes
+
+## Basic CursorFlow CLI Usage
+
+### Simple Tests
+```bash
+# Test with inline actions
+cursorflow test \
+  --base-url http://localhost:3000 \
+  --actions '[
+    {"navigate": "/page"},
+    {"wait_for": "#element"},
+    {"screenshot": "state"}
+  ]'
+
+# Simple path test
+cursorflow test --base-url http://localhost:3000 --path "/dashboard"
+```
+
+### Complex Tests
+```bash
+# Create action file first
+cat > test-actions.json << 'EOF'
+[
+  {"navigate": "/login"},
+  {"fill": {"selector": "#username", "value": "test@example.com"}},
+  {"fill": {"selector": "#password", "value": "testpass"}},
+  {"click": "#login-button"},
+  {"wait_for": ".dashboard"},
+  {"screenshot": "logged-in"}
+]
+EOF
+
+# Run test
+cursorflow test --base-url http://localhost:3000 --actions test-actions.json
+```
+
+## Available Actions
+
+| Action | Syntax | Purpose |
+|--------|--------|---------|
+| `navigate` | `{"navigate": "/path"}` | Go to URL or path |
+| `click` | `{"click": "#selector"}` | Click element |
+| `fill` | `{"fill": {"selector": "#input", "value": "text"}}` | Fill form field |
+| `wait` | `{"wait": 2}` | Wait seconds |
+| `wait_for` | `{"wait_for": "#element"}` | Wait for element |
+| `screenshot` | `{"screenshot": "name"}` | Take screenshot |
+
+## Common Usage Patterns
+
+### Form Testing
+```bash
+cursorflow test \
+  --base-url http://localhost:3000 \
+  --actions '[
+    {"navigate": "/contact"},
+    {"wait_for": "form"},
+    {"fill": {"selector": "#name", "value": "John Doe"}},
+    {"fill": {"selector": "#email", "value": "john@example.com"}},
+    {"click": "#submit"},
+    {"wait_for": ".success, .error"},
+    {"screenshot": "result"}
+  ]'
+```
+
+### Login Flow Testing
+```bash
+cursorflow test \
+  --base-url http://localhost:3000 \
+  --actions '[
+    {"navigate": "/login"},
+    {"wait_for": "#login-form"},
+    {"fill": {"selector": "#username", "value": "testuser"}},
+    {"fill": {"selector": "#password", "value": "testpass"}},
+    {"click": "#login-button"},
+    {"wait_for": ".dashboard, .error-message"},
+    {"screenshot": "login-result"}
+  ]'
+```
+
+### Shopping Cart Testing
+```bash
+cursorflow test \
+  --base-url http://localhost:3000 \
+  --actions '[
+    {"navigate": "/products"},
+    {"click": ".product:first-child .add-to-cart"},
+    {"wait_for": ".cart-notification"},
+    {"click": "#cart-icon"},
+    {"screenshot": "cart-contents"}
+  ]'
+```
+
+## Analyzing Results
+
+### **Hot Reload CSS Iteration Results** 
+CursorFlow generates comprehensive analysis optimized for CSS decisions:
+
+```json
+{
+  "session_id": "css_session_123",
+  "hot_reload_used": true,
+  "execution_time": 4.2,
+  
+  "session_context": {
+    "session_persistent": true,
+    "hot_reload_available": true,
+    "iteration_count": 15
+  },
+  
+  "persistent_analysis": {
+    "hot_reload_effectiveness": {
+      "hot_reload_usage_rate": 0.95,
+      "time_saved_seconds": 45.2,
+      "quality": "excellent"
+    },
+    "iteration_speed_metrics": {
+      "iterations_per_minute": 12.5,
+      "average_iteration_time": 4.8
+    }
+  },
+  
+  "iterations": [
+    {
+      "name": "improve-spacing",
+      "hot_reload_used": true,
+      "screenshot": ".cursorflow/artifacts/improve-spacing.png",
+      "console_errors": [],
+      "performance_impact": {"render_time": 45}
+    }
+  ],
+  
+  "recommended_actions": [
+    {
+      "action": "implement_css_changes",
+      "css_to_apply": ".container { gap: 2rem; }",
+      "target_files": ["components/Dashboard.css"]
+    }
+  ]
+}
+```
+
+### **Key Analysis Points for CSS Iteration**
+
+1. **Hot Reload Effectiveness**: Check `hot_reload_used` and `time_saved_seconds`
+2. **Visual Quality**: Review screenshots for each iteration
+3. **Performance Impact**: Monitor `render_time` and console errors  
+4. **Session Health**: Evaluate `session_persistent` and `iteration_count`
+5. **Implementation Readiness**: Use `recommended_actions` for next steps
+
+### **Traditional Test Results**
+CLI tests generate `{test_name}_test_results.json` with:
+
+- **browser_events**: UI interactions and console errors
+- **server_logs**: Backend activity during the test
+- **organized_timeline**: Chronological correlation of all events
+- **artifacts**: Screenshots and network data
+
+## The Request → Test → Analyze → Adjust → Repeat Pattern
+
+### **🔥 HOT RELOAD CSS ITERATION PATTERN (PRIMARY)**
+
+#### 1. REQUEST Phase
+User mentions CSS, styling, layout, or visual improvements.
+
+#### 2. TEST Phase (Persistent Session)
+```python
+results = await flow.css_iteration_persistent(
+    base_actions=[{"navigate": "/component"}],
+    css_changes=[
+        {"name": "fix-spacing", "css": ".container { gap: 2rem; }"},
+        {"name": "improve-typography", "css": "h1 { font-size: 2.5rem; }"}
+    ],
+    session_options={"hot_reload": True, "keep_session_alive": True}
+)
+```
+
+#### 3. ANALYZE Phase
+Examine persistent session results:
+- Check `hot_reload_used` for speed optimization
+- Review screenshots for visual improvements  
+- Monitor `console_errors` for CSS issues
+- Evaluate `iteration_speed_metrics` for efficiency
+
+#### 4. ADJUST Phase
+Apply recommended CSS to actual files:
+```python
+css_to_apply = results["recommended_actions"][0]["css_to_apply"]
+target_files = results["recommended_actions"][0]["target_files"]
+# Apply to actual CSS files
+```
+
+#### 5. REPEAT Phase (Session Continuation)
+Continue with same session for additional refinements:
+```python
+results2 = await flow.css_iteration_persistent(
+    base_actions=[],  # No reload needed!
+    css_changes=[{"name": "polish", "css": "..."}],
+    session_options={"session_id": "same_session", "reuse_session": True}
+)
+```
+
+### **Traditional Test Pattern (For Non-CSS Work)**
+
+#### 1. REQUEST → 2. TEST → 3. ANALYZE → 4. ADJUST → 5. REPEAT
+```bash
+cursorflow test --base-url http://localhost:3000 --actions 'JSON_ACTIONS'
+# Examine results, make changes, re-test
+```
+
+## Common CLI Options
+
+| Option | Purpose | Example |
+|--------|---------|---------|
+| `--actions` | Test actions (JSON) | `--actions '[{"navigate": "/"}]'` |
+| `--base-url` | Target URL | `--base-url http://localhost:3000` |
+| `--verbose` | Detailed output | `--verbose` |
+| `--logs` | Log source | `--logs local` |
+
+## Error Handling
+
+When tests fail:
+1. Check the JSON results for error details
+2. Look at browser console errors
+3. Examine server log entries
+4. Review screenshots for visual clues
+5. Identify the correlation between browser and server events
+
+## CSS and Layout Testing
+
+### **🔥 Hot Reload CSS Testing (RECOMMENDED)**
+```python
+# Ultra-fast CSS iteration with persistent sessions
+css_changes = [
+    {"name": "spacing-fix", "css": ".dashboard { gap: 2rem; padding: 1.5rem; }"},
+    {"name": "responsive-grid", "css": ".grid { grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); }"}
+]
+
+results = await flow.css_iteration_persistent(
+    base_actions=[{"navigate": "/dashboard"}, {"screenshot": "baseline"}],
+    css_changes=css_changes,
+    session_options={"hot_reload": True, "keep_session_alive": True}
+)
+
+# Get instant visual feedback with preserved application state
+best_iteration = results["summary"]["recommended_iteration"]
+print(f"Best CSS approach: {best_iteration}")
+```
+
+### **Traditional CLI Testing (Legacy)**
+```bash
+# Before changes
+cursorflow test --base-url http://localhost:3000 --actions '[{"navigate": "/dashboard"}, {"screenshot": "before"}]'
+
+# After changes  
+cursorflow test --base-url http://localhost:3000 --actions '[{"navigate": "/dashboard"}, {"screenshot": "after"}]'
+```
+
+## Authentication Testing
+
+```bash
+cursorflow test \
+  --base-url http://localhost:3000 \
+  --actions '[
+    {"navigate": "/login"},
+    {"fill": {"selector": "#username", "value": "test@example.com"}},
+    {"fill": {"selector": "#password", "value": "testpass"}},
+    {"click": "#login-button"},
+    {"wait_for": ".dashboard"},
+    {"navigate": "/protected-page"},
+    {"wait_for": "#protected-content"},
+    {"screenshot": "authenticated"}
+  ]'
+```
+
+## Best Practices
+
+### **🔥 Hot Reload CSS Iteration Best Practices**
+1. **Always use `css_iteration_persistent()` for CSS work** - 3-5x faster than CLI
+2. **Keep sessions alive** - Set `keep_session_alive: True` for continued iteration
+3. **Use descriptive CSS change names** - "spacing-fix", "responsive-layout", "color-theme"
+4. **Test multiple approaches** - Include 2-3 CSS variations per iteration
+5. **Continue sessions** - Reuse session_id for related styling work
+6. **Monitor hot reload effectiveness** - Check `hot_reload_used` in results
+
+### **Traditional CLI Best Practices**
+1. **Use descriptive test names**: `login-flow`, `checkout-process`, `form-validation`
+2. **Take screenshots at key moments**: Before and after important actions
+3. **Wait for elements**: Use `wait_for` instead of arbitrary `wait` times
+4. **Test error scenarios**: Include invalid inputs to test error handling
+5. **Keep actions focused**: Test one specific flow per command
+6. **Use action files for complex tests**: Easier to maintain and reuse
+
+### **⚡ Performance Tips**
+- **Hot reload detected**: Expect 3-5x faster iterations
+- **Session continuation**: No page reloads = preserved application state
+- **File monitoring**: CursorFlow syncs with your file changes automatically
+- **Smart cleanup**: Sessions auto-optimize and clean up when needed
+
+## Installation Commands
+
+```bash
+# Initial setup
+pip install cursorflow
+cursorflow init .
+
+# Install Cursor rules  
+cursorflow install-rules
+
+# Update when needed
+cursorflow update
+```
+
+## 🎯 **CRITICAL REMINDERS FOR CURSOR AI**
+
+### **🔥 PRIMARY WORKFLOW: Hot Reload CSS Iteration**
+- **ALWAYS use `css_iteration_persistent()` for CSS/UI work** 
+- **3-5x faster than CLI** - enables rapid design exploration
+- **Preserves application state** - no lost context during iteration
+- **Auto-detects hot reload** - works with Webpack, Vite, Next.js, etc.
+
+### **Decision Framework:**
+- **User mentions CSS/styling/layout** → `css_iteration_persistent()`
+- **User wants UI improvements** → Persistent sessions with hot reload
+- **User asks to "test component"** → Hot reload CSS iteration
+- **User reports form/auth issues** → Traditional CLI testing
+
+### **Key Success Patterns:**
+1. **Start persistent session** → Test multiple CSS approaches → Continue session → Apply best result
+2. **Monitor `hot_reload_used`** → Expect 12+ iterations per minute when working
+3. **Use session continuation** → Avoid page reloads → Maintain complex application state
+4. **Apply recommended CSS** → Let CursorFlow identify target files → Implement changes
+
+Remember: **CursorFlow's persistent sessions with hot reload are 3-5x faster than traditional testing.** Always prioritize this workflow for CSS/UI development to maximize iteration speed and preserve application state.