Update README with simulation shields and integrate tool explanation into QA section

Author: DerekGooding

README.md

@@ -6,6 +6,8 @@
 ![Monoliths](https://img.shields.io/endpoint?url=https://DerekGooding.github.io/Mythril/health/shield_monoliths.json)
 ![Docs](https://img.shields.io/endpoint?url=https://DerekGooding.github.io/Mythril/health/shield_docs.json)
 ![UI Integrity](https://img.shields.io/endpoint?url=https://DerekGooding.github.io/Mythril/health/shield_ui.json)
+![Reachability](https://img.shields.io/endpoint?url=https://DerekGooding.github.io/Mythril/health/shield_simulation.json)
+![Optimal Completion](https://img.shields.io/endpoint?url=https://DerekGooding.github.io/Mythril/health/shield_game_time.json)
 
 [**Live Website**](https://DerekGooding.Github.io/Mythril) | [**How to Play**](docs/instructions.md)
 
@@ -46,6 +48,8 @@ Mythril is an RPG-inspired web application built with **.NET 10** and **Blazor W
 ## ⚖️ Quality Assurance & Health
 We maintain project health through a custom automated suite (`scripts/check_health.py`) which runs on every commit:
 - **Monolith Prevention**: Strict 250-line limit for source files (excluding tools).
+- **Game Graph Simulation**: Integrated Fixed-Point Iteration engine that mathematically verifies every quest and resource is attainable from a fresh start. Prevents "logic orphans" and provides estimated optimal completion times for the endgame.
+- **Automated Balancing**: The reachability simulation is part of the health suite. If a content change makes a quest mathematically impossible (e.g. required stat cannot be reached), the build fails.
 - **Coverage**: Mandatory 70% overall line coverage; 25% per-file minimum.
 - **Razor Integrity**: All interactive components must have bUnit tests, `@key` usage in loops, and `data-testid` anchors.
 - **Documentation Integrity**: Automated staleness tracking via local file modification times.

scripts/check_health.py

@@ -260,14 +260,22 @@ def check_reachability():
     print("--- Running Reachability Simulation ---")
     try:
         # Run the headless simulation
-        # Use shell=True for windows/powershell compatibility if needed, 
-        # but direct list is safer for argument passing.
         cmd = ["dotnet", "run", "--project", "Mythril.Headless", "--", "--run-sim"]
         subprocess.check_call(cmd)
-        return True
+        
+        # Parse the report for time estimate
+        report_path = Path("simulation_report.md")
+        game_time = "Unknown"
+        if report_path.exists():
+            content = report_path.read_text(encoding="utf-8")
+            match = re.search(r"- \*\*Rekindling the Spark\*\*: ([\d:]+)", content)
+            if match:
+                game_time = match.group(1)
+        
+        return {"passed": True, "time": game_time}
     except subprocess.CalledProcessError:
         record_failure("reachability", "Simulation failed: One or more quests are mathematically unreachable.")
-        return False
+        return {"passed": False, "time": "N/A"}
 
 # -----------------------
 # Feedback Check
@@ -335,6 +343,17 @@ def generate_shields(metrics):
     message = "passed" if ui_passed else "failed"
     write_shield("ui", "UI integrity", message, color)
 
+    # Simulation Shield
+    sim = metrics.get('reachability_passed', {})
+    sim_passed = sim.get('passed', False)
+    color = "brightgreen" if sim_passed else "red"
+    message = "passed" if sim_passed else "failed"
+    write_shield("simulation", "reachability", message, color)
+
+    # Game Time Shield
+    game_time = sim.get('time', "N/A")
+    write_shield("game_time", "optimal completion", game_time, "blue")
+
 # -----------------------
 # Export Results
 # -----------------------

scripts/data/health_summary.json

@@ -8,7 +8,10 @@
         "key_violations": 0,
         "testid_violations": 0,
         "stale_docs": 0,
-        "reachability_passed": true,
+        "reachability_passed": {
+            "passed": true,
+            "time": "00:13:47"
+        },
         "pending_feedback": 0,
         "test_passed": true
     },

scripts/data/shield_game_time.json

@@ -0,0 +1,6 @@
+{
+    "schemaVersion": 1,
+    "label": "optimal completion",
+    "message": "00:13:47",
+    "color": "blue"
+}

scripts/data/shield_simulation.json

@@ -0,0 +1,6 @@
+{
+    "schemaVersion": 1,
+    "label": "reachability",
+    "message": "passed",
+    "color": "brightgreen"
+}

simulation_report.md

@@ -1,5 +1,5 @@
 # Simulation Reachability Report
-Generated at: 2026-03-04 1:20:03 PM
+Generated at: 2026-03-04 1:24:03 PM
 
 ## ✅ All Content Reachable
 No orphaned or mathematically impossible quests detected.