cursorflow 2.7.1__tar.gz → 2.7.3__tar.gz

{cursorflow-2.7.1 → cursorflow-2.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 2.7.1
+Version: 2.7.3
 Summary: 🔥 Complete page intelligence for AI-driven development with Hot Reload Intelligence - captures DOM, network, console, performance, HMR events, and comprehensive page analysis
 Author-email: GeekWarrior Development <rbush@cooltheory.com>
 License-Expression: MIT
@@ -256,6 +256,77 @@ cursorflow query session_A --compare-with session_B --errors
 
 ---
 
+## 🤖 **For AI Agents: Start Here**
+
+### 3-Second Decision Guide
+
+| User Says | Command | What You Get |
+|-----------|---------|--------------|
+| "Debug this error" | `cursorflow test` → `query session_X --errors --with-network` | Error + network + server logs correlated |
+| "Fix this CSS" | Python: `css_iteration_persistent()` | Visual comparison of CSS variations |
+| "Why is this slow?" | `query session_X --network --over 500ms` | Slow requests identified |
+| "Test login flow" | `cursorflow test --actions '[...]'` | Complete flow with server correlation |
+
+### Complete Debugging Example
+
+```bash
+# User: "There's a JavaScript error on the dashboard"
+
+# 1. Capture (5 seconds)
+cursorflow test --base-url http://localhost:3000 --path /dashboard
+
+# 2. Diagnose (10 seconds)
+cat .cursorflow/artifacts/sessions/session_XXX/data_digest.md
+cursorflow query session_XXX --errors
+
+# 3. Get context (5 seconds)
+cursorflow query session_XXX --context-for-error 0 --export markdown
+
+# 4. Fix based on correlated data
+# (You now have: error message, stack trace, network requests, server logs)
+```
+
+**Total time: 20 seconds from problem to actionable diagnosis**
+
+### When User Mentions...
+
+**"Error", "Broken", "Not working"**
+1. `cursorflow test` to capture
+2. `query --errors` to identify
+3. `query --context-for-error` to understand
+4. Fix based on correlated data
+
+**"Slow", "Performance", "Takes forever"**
+1. `cursorflow test` to baseline
+2. `query --network --over 500ms` to find bottlenecks
+3. `query --performance` for metrics
+4. Optimize slow requests
+
+**"CSS", "Styling", "Layout", "Spacing"**
+1. Python API: `css_iteration_persistent()`
+2. Test 2-3 CSS approaches
+3. Compare screenshots
+4. Apply best result
+
+**"Login", "Auth", "Session"**
+1. `cursorflow test --actions '[...]'` with login flow
+2. `--save-session` to preserve auth
+3. `--use-session` for subsequent tests
+4. Check auth errors with `query --errors --contains "auth"`
+
+**"Responsive", "Mobile", "Tablet"**
+1. `cursorflow test --responsive`
+2. `query --responsive --viewport mobile`
+3. Compare viewport results
+4. Fix mobile-specific issues
+
+**"Compare", "Regression", "What changed"**
+1. `query session_before --compare-with session_after`
+2. Focus on `new_errors` and `timing_changes`
+3. Investigate specific regressions
+
+---
+
 ## 🚀 Quick Start
 
 ### Step 1: Install CursorFlow Package

{cursorflow-2.7.1 → cursorflow-2.7.3}/README.md

@@ -211,6 +211,77 @@ cursorflow query session_A --compare-with session_B --errors
 
 ---
 
+## 🤖 **For AI Agents: Start Here**
+
+### 3-Second Decision Guide
+
+| User Says | Command | What You Get |
+|-----------|---------|--------------|
+| "Debug this error" | `cursorflow test` → `query session_X --errors --with-network` | Error + network + server logs correlated |
+| "Fix this CSS" | Python: `css_iteration_persistent()` | Visual comparison of CSS variations |
+| "Why is this slow?" | `query session_X --network --over 500ms` | Slow requests identified |
+| "Test login flow" | `cursorflow test --actions '[...]'` | Complete flow with server correlation |
+
+### Complete Debugging Example
+
+```bash
+# User: "There's a JavaScript error on the dashboard"
+
+# 1. Capture (5 seconds)
+cursorflow test --base-url http://localhost:3000 --path /dashboard
+
+# 2. Diagnose (10 seconds)
+cat .cursorflow/artifacts/sessions/session_XXX/data_digest.md
+cursorflow query session_XXX --errors
+
+# 3. Get context (5 seconds)
+cursorflow query session_XXX --context-for-error 0 --export markdown
+
+# 4. Fix based on correlated data
+# (You now have: error message, stack trace, network requests, server logs)
+```
+
+**Total time: 20 seconds from problem to actionable diagnosis**
+
+### When User Mentions...
+
+**"Error", "Broken", "Not working"**
+1. `cursorflow test` to capture
+2. `query --errors` to identify
+3. `query --context-for-error` to understand
+4. Fix based on correlated data
+
+**"Slow", "Performance", "Takes forever"**
+1. `cursorflow test` to baseline
+2. `query --network --over 500ms` to find bottlenecks
+3. `query --performance` for metrics
+4. Optimize slow requests
+
+**"CSS", "Styling", "Layout", "Spacing"**
+1. Python API: `css_iteration_persistent()`
+2. Test 2-3 CSS approaches
+3. Compare screenshots
+4. Apply best result
+
+**"Login", "Auth", "Session"**
+1. `cursorflow test --actions '[...]'` with login flow
+2. `--save-session` to preserve auth
+3. `--use-session` for subsequent tests
+4. Check auth errors with `query --errors --contains "auth"`
+
+**"Responsive", "Mobile", "Tablet"**
+1. `cursorflow test --responsive`
+2. `query --responsive --viewport mobile`
+3. Compare viewport results
+4. Fix mobile-specific issues
+
+**"Compare", "Regression", "What changed"**
+1. `query session_before --compare-with session_after`
+2. Focus on `new_errors` and `timing_changes`
+3. Investigate specific regressions
+
+---
+
 ## 🚀 Quick Start
 
 ### Step 1: Install CursorFlow Package

{cursorflow-2.7.1 → cursorflow-2.7.3}/cursorflow/cli.py

@@ -337,9 +337,6 @@ def test(base_url, path, actions, output, logs, config, verbose, headless, timeo
         with open(last_test_file, 'w') as f:
             json.dump(last_test_data, f, indent=2, default=str)
         
-        console.print(f"💾 Full results saved to: [cyan]{output}[/cyan]")
-        console.print(f"📁 Artifacts stored in: [cyan].cursorflow/artifacts/[/cyan]")
-        
         # Phase 3.4: Auto-open trace
         if open_trace and 'artifacts' in results and 'trace' in results['artifacts']:
             trace_path = results['artifacts']['trace']
@@ -1151,6 +1148,8 @@ def inspect(base_url, path, selector, verbose):
         results = asyncio.run(flow.execute_and_collect([
             {"navigate": path},
             {"wait_for_selector": "body"},
+            {"wait_for_load_state": "networkidle"},  # Wait for dynamic content
+            {"wait_for_timeout": 1000},  # Additional buffer for JS rendering (1s)
             {"screenshot": "inspection"}
         ]))
         
@@ -1200,7 +1199,7 @@ def inspect(base_url, path, selector, verbose):
                 console.print(f"Classes:   [blue].{classes}[/blue]")
             
             # Selectors
-            unique_selector = element.get('uniqueSelector', 'N/A')
+            unique_selector = escape(str(element.get('uniqueSelector', 'N/A')))
             console.print(f"Unique:    [cyan]{unique_selector}[/cyan]")
             
             # Dimensions
@@ -1216,20 +1215,22 @@ def inspect(base_url, path, selector, verbose):
                 console.print(f"\n🎨 Key CSS Properties:")
                 
                 # Layout
-                display = computed.get('display', 'N/A')
-                position = computed.get('position', 'N/A')
+                display = escape(str(computed.get('display', 'N/A')))
+                position = escape(str(computed.get('position', 'N/A')))
                 console.print(f"   display:   {display}")
                 console.print(f"   position:  {position}")
                 
                 # Flexbox
                 if 'flex' in computed:
-                    console.print(f"   flex:      {computed.get('flex', 'N/A')}")
+                    flex_value = escape(str(computed.get('flex', 'N/A')))
+                    console.print(f"   flex:      {flex_value}")
                 if 'flexBasis' in computed:
-                    console.print(f"   flex-basis: {computed.get('flexBasis', 'N/A')}")
+                    flex_basis = escape(str(computed.get('flexBasis', 'N/A')))
+                    console.print(f"   flex-basis: {flex_basis}")
                 
                 # Dimensions
-                width = computed.get('width', 'N/A')
-                height = computed.get('height', 'N/A')
+                width = escape(str(computed.get('width', 'N/A')))
+                height = escape(str(computed.get('height', 'N/A')))
                 console.print(f"   width:     {width}")
                 console.print(f"   height:    {height}")
                 
@@ -1237,20 +1238,23 @@ def inspect(base_url, path, selector, verbose):
                 margin = computed.get('margin', 'N/A')
                 padding = computed.get('padding', 'N/A')
                 if margin != 'N/A':
+                    margin = escape(str(margin))
                     console.print(f"   margin:    {margin}")
                 if padding != 'N/A':
+                    padding = escape(str(padding))
                     console.print(f"   padding:   {padding}")
                 
                 # Show all styles in verbose mode
                 if verbose:
                     console.print(f"\n📋 All Computed Styles:")
                     for prop, value in sorted(computed.items())[:30]:  # Limit to 30
-                        console.print(f"   {prop}: {value}")
+                        safe_value = escape(str(value))
+                        console.print(f"   {prop}: {safe_value}")
             
             # Accessibility info
             accessibility = element.get('accessibility', {})
             if accessibility:
-                role = accessibility.get('role', 'N/A')
+                role = escape(str(accessibility.get('role', 'N/A')))
                 is_interactive = accessibility.get('isInteractive', False)
                 console.print(f"\n♿ Accessibility:")
                 console.print(f"   Role:         {role}")
@@ -1293,8 +1297,9 @@ def inspect(base_url, path, selector, verbose):
         
     except Exception as e:
         console.print(f"[red]❌ Inspection failed: {escape(str(e))}[/red]")
-        import traceback
-        console.print(traceback.format_exc())
+        if verbose:
+            import traceback
+            console.print(escape(traceback.format_exc()))
 
 def _element_matches_selector(element: Dict, selector: str) -> bool:
     """Check if element matches the given selector"""

{cursorflow-2.7.1 → cursorflow-2.7.3}/cursorflow/core/output_manager.py

@@ -146,31 +146,28 @@ class OutputManager:
     
     def _extract_summary(self, results: Dict) -> Dict:
         """Extract high-level summary data"""
-        comprehensive = results.get('comprehensive_data', {})
+        # Load comprehensive data from disk if available
+        comprehensive = self._load_comprehensive_data(results)
         artifacts = results.get('artifacts', {})
         
-        # Count errors
+        # Count errors from comprehensive_data
         error_count = 0
         warning_count = 0
-        console_screenshots = artifacts.get('console_errors', [])
-        for screenshot in console_screenshots:
-            if isinstance(screenshot, dict):
-                console_data = screenshot.get('console_data', {})
-                errors = console_data.get('errors', {})
-                error_count += len(errors.get('logs', []))
-                warnings = console_data.get('warnings', {})
-                warning_count += len(warnings.get('logs', []))
+        if comprehensive:
+            console_data = comprehensive.get('console_data', {})
+            all_console_logs = console_data.get('all_console_logs', [])
+            error_count = len([log for log in all_console_logs if log.get('type') == 'error'])
+            warning_count = len([log for log in all_console_logs if log.get('type') == 'warning'])
         
-        # Count network requests
+        # Count network requests from comprehensive_data
         network_count = 0
         failed_network_count = 0
-        for screenshot in artifacts.get('screenshots', []):
-            if isinstance(screenshot, dict):
-                network_data = screenshot.get('network_data', {})
-                requests = network_data.get('requests', [])
-                network_count += len(requests)
-                failed_requests = network_data.get('failed_requests', {})
-                failed_network_count += len(failed_requests.get('requests', []))
+        if comprehensive:
+            network_data = comprehensive.get('network_data', {})
+            all_network_events = network_data.get('all_network_events', [])
+            network_count = len(all_network_events)
+            # Count failures (4xx, 5xx)
+            failed_network_count = len([req for req in all_network_events if req.get('status', 0) >= 400])
         
         # Count DOM elements
         dom_element_count = 0
@@ -202,26 +199,50 @@ class OutputManager:
     
     def _extract_errors(self, results: Dict) -> Dict:
         """Extract all error data with context"""
-        artifacts = results.get('artifacts', {})
         errors = []
         
-        # Collect errors from all screenshots
-        for screenshot in artifacts.get('screenshots', []):
-            if isinstance(screenshot, dict):
-                console_data = screenshot.get('console_data', {})
-                error_logs = console_data.get('errors', {}).get('logs', [])
-                
-                for error in error_logs:
+        # Load comprehensive data from disk if available
+        comprehensive_data = self._load_comprehensive_data(results)
+        
+        if comprehensive_data:
+            console_data = comprehensive_data.get('console_data', {})
+            all_console_logs = console_data.get('all_console_logs', [])
+            
+            # Filter for errors
+            for log in all_console_logs:
+                if log.get('type') == 'error':
+                    # Extract location info if present
+                    location = log.get('location', {})
                     errors.append({
-                        "message": error.get('message', ''),
-                        "source": error.get('source', ''),
-                        "line": error.get('line', 0),
-                        "column": error.get('column', 0),
-                        "stack_trace": error.get('stack_trace', ''),
-                        "timestamp": screenshot.get('timestamp', 0),
-                        "screenshot_name": screenshot.get('name', 'unknown'),
-                        "url": screenshot.get('url', '')
+                        "message": log.get('text', ''),
+                        "source": location.get('url', ''),
+                        "line": location.get('lineNumber', 0),
+                        "column": location.get('columnNumber', 0),
+                        "stack_trace": log.get('stackTrace', {}).get('callFrames', []),
+                        "timestamp": log.get('timestamp', 0),
+                        "screenshot_name": 'comprehensive',
+                        "url": location.get('url', '')
                     })
+        else:
+            # Fallback: Collect errors from screenshot artifacts (old structure)
+            # Only if comprehensive_data not available
+            artifacts = results.get('artifacts', {})
+            for screenshot in artifacts.get('screenshots', []):
+                if isinstance(screenshot, dict):
+                    console_data = screenshot.get('console_data', {})
+                    error_logs = console_data.get('errors', {}).get('logs', [])
+                    
+                    for error in error_logs:
+                        errors.append({
+                            "message": error.get('message', ''),
+                            "source": error.get('source', ''),
+                            "line": error.get('line', 0),
+                            "column": error.get('column', 0),
+                            "stack_trace": error.get('stack_trace', ''),
+                            "timestamp": screenshot.get('timestamp', 0),
+                            "screenshot_name": screenshot.get('name', 'unknown'),
+                            "url": screenshot.get('url', '')
+                        })
         
         # Organize by error type
         error_types = {}
@@ -243,29 +264,55 @@ class OutputManager:
     
     def _extract_network(self, results: Dict) -> Dict:
         """Extract network request/response data"""
-        artifacts = results.get('artifacts', {})
         all_requests = []
         failed_requests = []
         
-        for screenshot in artifacts.get('screenshots', []):
-            if isinstance(screenshot, dict):
-                network_data = screenshot.get('network_data', {})
-                requests = network_data.get('requests', [])
-                
-                for request in requests:
-                    all_requests.append({
-                        **request,
-                        "screenshot_name": screenshot.get('name', 'unknown'),
-                        "timestamp": screenshot.get('timestamp', 0)
-                    })
+        # Load comprehensive data from disk if available
+        comprehensive_data = self._load_comprehensive_data(results)
+        
+        if comprehensive_data:
+            network_data = comprehensive_data.get('network_data', {})
+            all_network_events = network_data.get('all_network_events', [])
+            
+            # Add all network events and identify failures
+            for event in all_network_events:
+                request_data = {
+                    "url": event.get('url', ''),
+                    "method": event.get('method', 'GET'),
+                    "status_code": event.get('status', 0),
+                    "timestamp": event.get('timestamp', 0),
+                    "timing": event.get('timing', {}),
+                    "screenshot_name": 'comprehensive'
+                }
+                all_requests.append(request_data)
                 
-                failed = network_data.get('failed_requests', {}).get('requests', [])
-                for request in failed:
-                    failed_requests.append({
-                        **request,
-                        "screenshot_name": screenshot.get('name', 'unknown'),
-                        "timestamp": screenshot.get('timestamp', 0)
-                    })
+                # Identify failed requests (4xx, 5xx status codes)
+                status = event.get('status', 0)
+                if status >= 400:
+                    failed_requests.append(request_data)
+        else:
+            # Fallback: Collect from screenshot artifacts (old structure)
+            # Only if comprehensive_data not available
+            artifacts = results.get('artifacts', {})
+            for screenshot in artifacts.get('screenshots', []):
+                if isinstance(screenshot, dict):
+                    network_data = screenshot.get('network_data', {})
+                    requests = network_data.get('requests', [])
+                    
+                    for request in requests:
+                        all_requests.append({
+                            **request,
+                            "screenshot_name": screenshot.get('name', 'unknown'),
+                            "timestamp": screenshot.get('timestamp', 0)
+                        })
+                    
+                    failed = network_data.get('failed_requests', {}).get('requests', [])
+                    for request in failed:
+                        failed_requests.append({
+                            **request,
+                            "screenshot_name": screenshot.get('name', 'unknown'),
+                            "timestamp": screenshot.get('timestamp', 0)
+                        })
         
         # Organize by status code
         by_status_code = {}
@@ -288,24 +335,42 @@ class OutputManager:
     
     def _extract_console(self, results: Dict) -> Dict:
         """Extract all console messages"""
-        artifacts = results.get('artifacts', {})
         all_messages = []
         
-        for screenshot in artifacts.get('screenshots', []):
-            if isinstance(screenshot, dict):
-                console_data = screenshot.get('console_data', {})
-                
-                # Collect all message types
-                for msg_type in ['errors', 'warnings', 'logs', 'info']:
-                    messages = console_data.get(msg_type, {}).get('logs', [])
-                    for msg in messages:
-                        all_messages.append({
-                            "type": msg_type,
-                            "message": msg.get('message', ''),
-                            "source": msg.get('source', ''),
-                            "timestamp": screenshot.get('timestamp', 0),
-                            "screenshot_name": screenshot.get('name', 'unknown')
-                        })
+        # Load comprehensive data from disk if available
+        comprehensive_data = self._load_comprehensive_data(results)
+        
+        if comprehensive_data:
+            console_data = comprehensive_data.get('console_data', {})
+            all_console_logs = console_data.get('all_console_logs', [])
+            
+            for log in all_console_logs:
+                all_messages.append({
+                    "type": log.get('type', 'log'),
+                    "message": log.get('text', ''),
+                    "source": log.get('location', {}).get('url', ''),
+                    "timestamp": log.get('timestamp', 0),
+                    "screenshot_name": 'comprehensive'
+                })
+        else:
+            # Fallback: Collect from screenshot artifacts (old structure)
+            # Only if comprehensive_data not available
+            artifacts = results.get('artifacts', {})
+            for screenshot in artifacts.get('screenshots', []):
+                if isinstance(screenshot, dict):
+                    console_data = screenshot.get('console_data', {})
+                    
+                    # Collect all message types
+                    for msg_type in ['errors', 'warnings', 'logs', 'info']:
+                        messages = console_data.get(msg_type, {}).get('logs', [])
+                        for msg in messages:
+                            all_messages.append({
+                                "type": msg_type,
+                                "message": msg.get('message', ''),
+                                "source": msg.get('source', ''),
+                                "timestamp": screenshot.get('timestamp', 0),
+                                "screenshot_name": screenshot.get('name', 'unknown')
+                            })
         
         # Organize by type
         by_type = {}
@@ -335,9 +400,22 @@ class OutputManager:
     
     def _extract_performance(self, results: Dict) -> Dict:
         """Extract performance metrics"""
-        artifacts = results.get('artifacts', {})
         performance_data = []
         
+        # Load comprehensive data from disk if available
+        comprehensive = self._load_comprehensive_data(results)
+        
+        if comprehensive and 'performance_data' in comprehensive:
+            perf = comprehensive.get('performance_data', {})
+            if perf:
+                performance_data.append({
+                    "screenshot_name": 'comprehensive',
+                    "timestamp": results.get('execution_time', 0),
+                    "metrics": perf
+                })
+        
+        # Fallback: from screenshot artifacts
+        artifacts = results.get('artifacts', {})
         for screenshot in artifacts.get('screenshots', []):
             if isinstance(screenshot, dict):
                 perf = screenshot.get('performance_data', {})
@@ -512,6 +590,44 @@ class OutputManager:
             "min_memory_usage": min(memory_usage) if memory_usage else 0
         }
     
+    def _load_comprehensive_data(self, results: Dict) -> Dict:
+        """Load comprehensive data from disk or from results dict"""
+        # First try to get from results (if already loaded)
+        comprehensive = results.get('comprehensive_data', {})
+        if comprehensive:
+            return comprehensive
+        
+        # Try to load from disk via screenshot artifacts
+        artifacts = results.get('artifacts', {})
+        screenshots = artifacts.get('screenshots', [])
+        
+        if screenshots:
+            last_screenshot = screenshots[-1]
+            # Check if comprehensive_data_path is set
+            if isinstance(last_screenshot, dict) and 'comprehensive_data_path' in last_screenshot:
+                comp_path = Path(last_screenshot['comprehensive_data_path'])
+                if comp_path.exists():
+                    try:
+                        with open(comp_path, 'r', encoding='utf-8') as f:
+                            return json.load(f)
+                    except Exception as e:
+                        self.logger.warning(f"Could not load comprehensive data from {comp_path}: {e}")
+            
+            # Try to find comprehensive data file by naming convention
+            if isinstance(last_screenshot, dict) and 'path' in last_screenshot:
+                screenshot_path = Path(last_screenshot['path'])
+                if screenshot_path.exists():
+                    # Look for companion comprehensive data file
+                    comp_path = screenshot_path.parent / f"{screenshot_path.stem}_comprehensive_data.json"
+                    if comp_path.exists():
+                        try:
+                            with open(comp_path, 'r', encoding='utf-8') as f:
+                                return json.load(f)
+                        except Exception as e:
+                            self.logger.warning(f"Could not load comprehensive data from {comp_path}: {e}")
+        
+        return {}
+    
     def _write_json(self, path: Path, data: Dict):
         """Write JSON data to file with proper formatting"""
         with open(path, 'w', encoding='utf-8') as f:

{cursorflow-2.7.1 → cursorflow-2.7.3}/cursorflow/core/query_engine.py

@@ -317,11 +317,8 @@ class QueryEngine:
         
         # Filter failed requests only
         if 'failed' in filters and filters['failed']:
-            failed_reqs = network.get('failed_requests', [])
-            filtered_requests = [
-                req for req in all_requests
-                if req.get('url') in [f.get('url') for f in failed_reqs]
-            ]
+            # Use failed_requests array directly (already filtered)
+            filtered_requests = network.get('failed_requests', [])
         
         # Phase 1: Enhanced network filtering
         

{cursorflow-2.7.1 → cursorflow-2.7.3}/cursorflow/rules/cursorflow-usage.mdc

@@ -6,6 +6,115 @@ alwaysApply: true
 
 # CursorFlow Usage Rules for Cursor AI
 
+## 🎯 **AI AGENT QUICK START - Read This First**
+
+### Instant Decision Tree
+
+**User reports error?**
+→ `cursorflow test --base-url URL --path /page`
+→ `cat .cursorflow/artifacts/sessions/session_XXX/data_digest.md`
+→ `cursorflow query session_XXX --errors --with-server-logs --with-network`
+→ Analyze correlated data, make fix
+
+**User wants CSS/styling change?**
+→ Python API: `css_iteration_persistent()`
+→ Test 2-3 CSS variations
+→ Apply best result
+
+**User reports slow page?**
+→ `cursorflow query session_XXX --network --over 500ms`
+→ `cursorflow query session_XXX --performance`
+→ Identify bottlenecks
+
+**User debugging network failure?**
+→ `cursorflow query session_XXX --network --failed --with-errors`
+→ See errors that happened around network failure
+→ `cursorflow query session_XXX --server-logs --pattern "api"`
+
+---
+
+## 🔍 **Common Debugging Patterns - Copy These**
+
+### Pattern 1: "Page has JavaScript error"
+```bash
+# 1. Capture current state
+cursorflow test --base-url http://localhost:3000 --path /page
+
+# 2. Get error context
+cursorflow query session_XXX --errors --export markdown
+
+# 3. Find what triggered it
+cursorflow query session_XXX --context-for-error 0 --window 10
+
+# 4. Check server logs
+cursorflow query session_XXX --server-logs --level error
+```
+
+### Pattern 2: "API call failing"
+```bash
+# 1. Find failed request
+cursorflow query session_XXX --network --failed
+
+# 2. Get full context
+cursorflow query session_XXX --network --url-contains "/api/" --with-errors
+
+# 3. Check server side
+cursorflow query session_XXX --server-logs --pattern "api" --level error
+```
+
+### Pattern 3: "Feature broken after deployment"
+```bash
+# 1. Test current version
+cursorflow test --base-url https://staging.com --path /feature
+
+# 2. Compare with baseline
+cursorflow query session_new --compare-with session_baseline --errors
+cursorflow query session_new --compare-with session_baseline --network
+
+# 3. Identify regressions
+# Shows: new_errors, fixed_errors, timing_changes
+```
+
+### Pattern 4: "Element not visible/clickable"
+```bash
+# 1. Inspect element
+cursorflow inspect --base-url URL --path /page --selector ".element"
+
+# 2. Query DOM
+cursorflow query session_XXX --dom --selector ".element"
+
+# 3. Check if hidden
+cursorflow query session_XXX --dom --visible
+```
+
+### Pattern 5: "Slow page load"
+```bash
+# 1. Find slow requests
+cursorflow query session_XXX --network --over 1000ms
+
+# 2. Group by URL
+cursorflow query session_XXX --group-by-url "/api/slow"
+
+# 3. Check performance
+cursorflow query session_XXX --performance
+```
+
+---
+
+## 💡 **What Each Query Reveals - AI Agent Guide**
+
+**`--errors`** → Error message, source file, line number, stack trace  
+**`--errors --with-network`** → Errors + network requests within ±5s (find API failures)  
+**`--errors --with-server-logs`** → Errors + backend logs (complete picture)  
+**`--network --failed`** → All 4xx/5xx responses with headers and timing  
+**`--network --over 500ms`** → Slow requests (bottleneck identification)  
+**`--server-logs --level error`** → Backend errors with timestamps  
+**`--context-for-error 0`** → Everything within ±5s of error (deep debugging)  
+**`--group-by-url "/api/X"`** → All data for specific endpoint  
+**`session_A --compare-with session_B`** → New/fixed errors, timing changes
+
+---
+
 ## 🔥 **CursorFlow: AI-Native Testing with Optimized Output**
 
 **CursorFlow v2.7.0 provides comprehensive data collection + AI-optimized output:**

{cursorflow-2.7.1 → cursorflow-2.7.3}/docs/user/USAGE_GUIDE.md

@@ -197,6 +197,102 @@ cursorflow query session_A --compare-with session_B --network
 
 ---
 
+## 📖 **Query Cookbook - Real-World Scenarios**
+
+### Scenario 1: Finding the Root Cause of an Error
+
+```bash
+# You have an error, need to understand what caused it
+
+# Step 1: Get the error details
+cursorflow query session_XXX --errors
+# Returns: Error message, source file, line number
+
+# Step 2: Get full context (what happened around it)
+cursorflow query session_XXX --context-for-error 0 --window 10
+# Returns: Network requests, console logs, server logs ±10s
+
+# Step 3: Check if network failure caused it
+cursorflow query session_XXX --errors --with-network
+# Returns: Errors with related network requests
+
+# Step 4: Export for documentation
+cursorflow query session_XXX --context-for-error 0 --export markdown > error_report.md
+```
+
+### Scenario 2: Debugging Slow Performance
+
+```bash
+# User reports "page is slow"
+
+# Step 1: Find slow network requests
+cursorflow query session_XXX --network --over 1000ms
+
+# Step 2: Group by API endpoint
+cursorflow query session_XXX --group-by-url "/api/data"
+# Returns: All requests to that endpoint + related errors
+
+# Step 3: Check server side
+cursorflow query session_XXX --server-logs --pattern "slow query"
+
+# Step 4: Compare with fast version
+cursorflow query session_slow --compare-with session_fast --network
+# Returns: timing_changes showing which requests got slower
+```
+
+### Scenario 3: Regression Detection
+
+```bash
+# Feature worked yesterday, broken today
+
+# Step 1: Compare sessions
+cursorflow query session_today --compare-with session_yesterday --errors
+# Returns: new_errors, fixed_errors, frequency_changes
+
+# Step 2: Check network changes
+cursorflow query session_today --compare-with session_yesterday --network
+# Returns: new_urls, removed_urls, status_changes
+
+# Step 3: Find specific regression
+cursorflow query session_today --errors --from-file "feature.js"
+```
+
+### Scenario 4: API Debugging
+
+```bash
+# API endpoint returning errors
+
+# Step 1: Find all requests to endpoint
+cursorflow query session_XXX --network --url-contains "/api/users"
+
+# Step 2: Find failed ones
+cursorflow query session_XXX --network --url-contains "/api/users" --status 4xx,5xx
+
+# Step 3: Get errors that happened at same time
+cursorflow query session_XXX --network --failed --with-errors
+
+# Step 4: Check server logs
+cursorflow query session_XXX --server-logs --pattern "api/users"
+```
+
+### Scenario 5: Complete Frontend + Backend Correlation
+
+```bash
+# Complex issue needs full picture
+
+# Step 1: Get error with all related data
+cursorflow query session_XXX --context-for-error 0 --window 10
+# Returns: error, network, console, server logs, timeline
+
+# Step 2: Export as markdown report
+cursorflow query session_XXX --context-for-error 0 --export markdown > investigation.md
+
+# Step 3: Share with team or use for documentation
+# investigation.md has complete formatted context
+```
+
+---
+
 ## 📊 **Server Log Configuration**
 
 CursorFlow can monitor server logs from multiple sources during testing:

{cursorflow-2.7.1 → cursorflow-2.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cursorflow"
-version = "2.7.1"
+version = "2.7.3"
 description = "🔥 Complete page intelligence for AI-driven development with Hot Reload Intelligence - captures DOM, network, console, performance, HMR events, and comprehensive page analysis"
 authors = [
     {name = "GeekWarrior Development", email = "rbush@cooltheory.com"}