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