docs update (wip)

simulation/sim_base.py

@@ -1,3 +1,45 @@
+"""
+Base Simulation Framework - Abstract base class for GUI automation tests.
+
+This module provides the foundation for all simulation-based tests in the
+Manual Slop test suite. Simulations act as external "puppeteers" that drive
+the GUI through the ApiHookClient HTTP interface.
+
+Architecture:
+ - BaseSimulation: Abstract base class with setup/teardown lifecycle
+ - WorkflowSimulator: High-level workflow operations (project setup, file mgmt)
+ - ApiHookClient: Low-level HTTP client for Hook API communication
+
+Typical Usage:
+ class MySimulation(BaseSimulation):
+  def run(self) -> None:
+   self.client.set_value('mma_epic_input', 'My epic description')
+   self.client.click('btn_mma_plan_epic')
+   # Poll for completion...
+   status = self.client.get_mma_status()
+   assert status['mma_status'] == 'done'
+
+ if __name__ == '__main__':
+  run_sim(MySimulation)
+
+Lifecycle:
+ 1. setup() - Connects to GUI, resets session, scaffolds temp project
+ 2. run() - Implemented by subclass with simulation logic
+ 3. teardown() - Cleanup (optional file retention for debugging)
+
+Prerequisites:
+ - GUI must be running with --enable-test-hooks flag
+ - HookServer must be listening on http://127.0.0.1:8999
+
+Thread Safety:
+ - Simulations are designed to run in the main thread
+ - ApiHookClient handles its own connection pooling
+
+See Also:
+ - simulation/workflow_sim.py for WorkflowSimulator
+ - tests/conftest.py for live_gui pytest fixture
+ - docs/guide_simulations.md for full simulation documentation
+"""
 import sys
 import os
 import time

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