Update app.py

app.py

@@ -1,5 +1,6 @@
 # app.py
 # Author: Liam Grinstead
+# Purpose: Run agent simulations, mutations, and falsifiability checks with automatic logging
 
 from modules.agent_spawner import spawn_agent
 from modules.mutation_engine import mutate_agent
@@ -9,15 +10,32 @@ from modules.codex_logger import log_artifact
 from modules.codex_viewer import load_codex
 
 def run_simulation(agent_id, mutation_profile):
+    """
+    Run a full simulation cycle:
+    1. Spawn agent
+    2. Apply mutation profile
+    3. Render fields (optional)
+    4. Run falsifiability bench
+    5. Log artifact with SHA-512 seal
+    """
+    # Step 1: Spawn agent
     agent = spawn_agent(agent_id)
+
+    # Step 2: Mutate agent
     mutated = mutate_agent(agent, mutation_profile)
 
-    # optional visualization step
+    # Step 3: Optional visualization
     try:
         render_fields(mutated)
     except Exception:
+        # Visualization is non-critical, continue if it fails
         pass
 
+    # Step 4: Falsifiability scoring
     score, hash_val = run_falsifiability(mutated)
+
+    # Step 5: Log artifact (saved to JSON with timestamp + SHA-512 seal)
     log_artifact(mutated, score, hash_val)
+
+    # Return mutated agent and hash for downstream use
     return mutated, hash_val