docs update (wip)

simulation/workflow_sim.py

@@ -1,3 +1,44 @@
+"""
+Workflow Simulator - High-level GUI workflow automation for testing.
+
+This module provides the WorkflowSimulator class which orchestrates complex
+multi-step workflows through the GUI via the ApiHookClient. It is designed
+for integration testing and automated verification of GUI behavior.
+
+Key Capabilities:
+ - Project setup and configuration
+ - Discussion creation and switching
+ - AI turn execution with stall detection
+ - Context file management
+ - MMA (Multi-Model Agent) orchestration simulation
+
+Stall Detection:
+ The run_discussion_turn() method implements intelligent stall detection:
+ - Monitors ai_status for transitions from busy -> idle
+ - Detects stalled Tool results (non-busy state with Tool as last role)
+ - Automatically triggers btn_gen_send to recover from stalls
+
+Integration with UserSimAgent:
+ WorkflowSimulator delegates user simulation behavior (reading time, delays)
+ to UserSimAgent for realistic interaction patterns.
+
+Thread Safety:
+ This class is NOT thread-safe. All methods should be called from a single
+ thread (typically the main test thread).
+
+Example Usage:
+ client = ApiHookClient()
+ sim = WorkflowSimulator(client)
+ sim.setup_new_project("TestProject", "/path/to/git/dir")
+ sim.create_discussion("Feature A")
+ result = sim.run_discussion_turn("Please implement feature A")
+
+See Also:
+ - simulation/sim_base.py for BaseSimulation class
+ - simulation/user_agent.py for UserSimAgent
+ - api_hook_client.py for ApiHookClient
+ - docs/guide_simulations.md for full simulation documentation
+"""
 import time
 from api_hook_client import ApiHookClient
 from simulation.user_agent import UserSimAgent