From 775bd5c5d35098c0b7c7bf5b03c1c7265f00459a Mon Sep 17 00:00:00 2001
From: danielnovais-tech <daniel.novais@sempreceub.com>
Date: Sat, 7 Feb 2026 23:07:37 -0300
Subject: [PATCH] Docs: add GR801 demo run guide

---
 README.md                |  1 +
 docs/GR801_SIMULATION.md | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 docs/GR801_SIMULATION.md

diff --git a/README.md b/README.md
index 7070252..4c841e1 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,7 @@ Higher scores = more reliable data for decision-making.
 - **[Crowdsourcing Guide](docs/CROWDSOURCING.md)** - Community data collection
 - **[Developer Setup (Windows-first)](docs/DEV_SETUP.md)** - VS Code tasks, environment setup, and daily workflow
 - **[Simulation Pipeline Spec](docs/SIMULATION_PIPELINE.md)** - Research-grade direction + CLI scaffold
+- **[GR801 SoC Simulation (Standalone)](docs/GR801_SIMULATION.md)** - Run the GR801 demo without touching the main pipeline
 
 ## 🏗️ Architecture Overview
 
diff --git a/docs/GR801_SIMULATION.md b/docs/GR801_SIMULATION.md
new file mode 100644
index 0000000..44e1b6a
--- /dev/null
+++ b/docs/GR801_SIMULATION.md
@@ -0,0 +1,38 @@
+# GR801 Simulation (Standalone)
+
+This repo includes a lightweight simulation scaffold for a GR801 radiation-hardened AI SoC.
+
+It is **standalone** and does **not** run the Rural Mapper data pipeline, does **not** touch `data/`, and does **not** require any external credentials.
+
+## Run the demo
+
+From the repo root (Windows PowerShell):
+
+```powershell
+.\.venv\Scripts\python.exe gr801_simulation_framework.py
+```
+
+This runs a short “radiation tolerance” sanity pass and then a mission simulation using the toy models.
+
+## Use it from Python
+
+```python
+import numpy as np
+import gr801_simulation_framework as gr
+
+system = gr.GR801System(environment=gr.RadiationEnvironment.LEO)
+
+# Advance simulation time (does not affect the Rural Mapper pipeline)
+system.execute_timestep(dt=0.1)
+
+model = gr.NeuralNetworkModel.get_preset_model(gr.AIWorkload.IMAGE_CLASSIFICATION)
+input_data = np.random.standard_normal((1, *model.input_shape)).astype(np.float32)
+result = system.run_inference(gr.AIWorkload.IMAGE_CLASSIFICATION, input_data)
+print(result["estimated_accuracy"], result["result"].shape)
+```
+
+## Notes
+
+- The “4GB DDR” is modeled as a sparse paged address space to avoid allocating multi‑GB arrays.
+- CPU cycles and memory scrubbing are batched to keep the simulation fast in Python.
+- This is a simulation scaffold, not a hardware-accurate model.