cursorflow 2.7.2__tar.gz → 2.7.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 2.7.2
+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.2 → 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.2 → 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']

{cursorflow-2.7.2 → 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.2 → 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.2 → cursorflow-2.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cursorflow"
-version = "2.7.2"
+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"}