docs: initialize replication guide and environment configuration

Summary:
Added comprehensive documentation and environment setup files to ensure
seamless project replication on different machines. This includes a
centralized README.md and standardized dependency manifests for both
pip and conda.

Changes:
- Created README.md: A complete source of truth for the Fox CARLA ADAS
  Simulation project, covering prerequisites, multi-stage pipeline
  architecture, and detailed installation steps.
- Created requirements.txt: A curated list of project dependencies
  (PyTorch, Flask, MCAP, OpenCV, etc.) extracted from the active
  carla312 environment.
- Created environment.yml: A Conda environment specification file
  for one-command environment replication including Python 3.12
  and the necessary scientific stack.
- Added Troubleshooting section to README covering GPU Idle Mode,
  stop.flag detection, and CARLA coordinate system conventions.

Technical Note:
The setup instructions explicitly detail the manual installation of the
CARLA 0.9.16 .whl file, as it is a local dependency relative to the
project root within the CARLA PythonAPI directory.

README.md

@@ -0,0 +1,110 @@
+# 🦊 Fox CARLA ADAS Simulation Project
+
+A modular, scenario-driven simulation framework built on **CARLA 0.9.16** for demonstrating structured ADAS driving scenarios with multi-modal sensor data and physics-based radar synthesis.
+
+---
+
+## 🚀 1. Prerequisites
+
+Before setting up the project, ensure you have the following installed:
+
+*   **Operating System**: Windows 10/11 (Required for CARLA 0.9.16 and Shenron synthesis).
+*   **CARLA Simulator**: Version **0.9.16** (Must be installed and reachable).
+*   **Miniconda/Anaconda**: For environment management.
+*   **NVIDIA GPU**: Required for high-fidelity radar synthesis and CARLA rendering.
+
+---
+
+## 🛠️ 2. Environment Setup
+
+### 1. Clone the Repository
+Clone this repository into your CARLA PythonAPI folder:
+```powershell
+cd C:\Path\To\CARLA_0.9.16\PythonAPI
+git clone <repository_url> Fox
+cd Fox
+```
+
+### 2. Create Conda Environment
+We use Python **3.12** for compatibility with modern libraries and CARLA 0.9.16.
+
+**Option A: Using environment.yml (Recommended)**
+```powershell
+conda env create -f environment.yml
+conda activate carla312
+```
+
+**Option B: Manual Setup**
+```powershell
+conda create -n carla312 python=3.12 -y
+conda activate carla312
+pip install -r requirements.txt
+```
+
+### 3. Install CARLA Python API
+Regardless of the option above, you must install the CARLA 0.9.16 wheel:
+```powershell
+pip install ..\carla\dist\carla-0.9.16-cp312-cp312-win_amd64.whl
+```
+
+---
+
+## 🖥️ 3. Usage & Execution
+
+### 🖱️ One-Click Dashboard (GUI)
+The easiest way to run the orchestrator is via the Flask dashboard:
+1.  Launch **CARLA** (e.g., `CarlaUE4.exe`).
+2.  Double-click `dashboard.bat` in the project root.
+3.  Navigate to `http://127.0.0.1:5000` to manage scenarios and view telemetry.
+
+### ⌨️ Command Line Interface (CLI)
+You can run scenarios directly via the `run.bat` wrapper:
+
+*   **List Scenarios**: `.\run.bat --list-scenarios`
+*   **Run Scenario**: `.\run.bat braking --frames 300`
+*   **With Parameters**: `.\run.bat cutin --params "TARGET_SPEED=40,CUTIN_DIST=15"`
+*   **Skip Processing**: `.\run.bat showcase --skip-shenron --skip-mcap`
+
+---
+
+## 🏗️ 4. Project Architecture
+
+*   **`src/`**: Core logic including `PipelineManager`, `SensorManager`, and `Recorder`.
+*   **`scenarios/`**: Modular scenario implementations (e.g., `braking.py`, `cutin.py`).
+*   **`scripts/`**: Data conversion tools (MCAP) and the **Shenron** radar synthesis engine.
+*   **`dashboard/`**: Flask-based web interface for the orchestrator.
+*   **`intel/`**: Deep-dive documentation, project history (CHRONICLES.md), and versioned changelogs.
+
+---
+
+## 🛰️ 5. The Data Pipeline
+
+The simulation follows a structured multi-stage pipeline:
+1.  **Simulation Stage**: Captures RGB, LiDAR, and raw Radar data from CARLA.
+2.  **Shenron Stage**: Synthesizes high-fidelity physics-based radar heatmaps.
+3.  **MCAP Stage**: Converts all data into a single `.mcap` file for **Foxglove** visualization.
+4.  **Video Stage**: Generates `.mp4` previews of the session.
+
+---
+
+## 📂 6. Replication Checklist for New PC
+
+If you are moving this project to another machine:
+1.  [ ] Install **CARLA 0.9.16**.
+2.  [ ] Verify **CUDA** drivers are up to date for Shenron synthesis.
+3.  [ ] Create `carla312` environment and install `requirements.txt`.
+4.  [ ] Ensure `run.bat` and `dashboard.bat` point to the correct `activate.bat` path (default: `C:\ProgramData\miniconda3\Scripts\activate.bat`).
+5.  [ ] Run `cmd /c "run.bat showcase --frames 50"` to verify the full pipeline end-to-end.
+
+---
+
+## 🛠️ 7. Troubleshooting & Tips
+
+*   **GPU Idle Mode**: If the simulator feels "frozen," check if **Idle Mode** is enabled in the Dashboard. This throttles CARLA to ~0 FPS to save GPU for Shenron processing.
+*   **Stop Flag**: If the simulation won't start, check for a `tmp/stop.flag` file and delete it.
+*   **Environment Activation**: If `run.bat` fails to find `conda`, edit the script to point to your `activate.bat` location (usually in `C:\miniconda3\Scripts` or `C:\Users\<User>\miniconda3\Scripts`).
+*   **Coordinate Systems**: Remember that CARLA uses a left-handed coordinate system (LHS), while Foxglove/ROS2 use right-handed (RHS). The MCAP converter handles this conversion automatically.
+
+---
+
+*Generated by Antigravity AI | Version 1.1 "Ares"*

environment.yml

@@ -0,0 +1,39 @@
+name: carla312
+channels:
+  - pytorch
+  - nvidia
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.12
+  - pip
+  - pip:
+    - numpy==2.4.3
+    - opencv-python==4.13.0.92
+    - scipy==1.17.1
+    - pandas==3.0.2
+    - pillow==12.1.1
+    - tqdm==4.67.3
+    - pygame==2.6.1
+    - matplotlib==3.10.8
+    - plotly==6.6.0
+    - open3d==0.19.0
+    - pyntcloud==0.3.1
+    - Flask==3.1.3
+    - Werkzeug==3.1.7
+    - itsdangerous==2.2.0
+    - Jinja2==3.1.6
+    - click==8.3.1
+    - blinker==1.9.0
+    - torch==2.5.1
+    - torchvision==0.20.1
+    - torchaudio==2.5.1
+    - PyYAML==6.0.3
+    - mcap==1.3.1
+    - mcap-ros2-support==0.5.7
+    - lz4==4.4.5
+    - zstandard==0.25.0
+    - psutil==7.2.2
+    - nvidia-ml-py==13.595.45
+    - requests==2.33.1
+    - certifi==2026.2.25

requirements.txt

@@ -0,0 +1,40 @@
+# Core Simulation & Data Processing
+numpy==2.4.3
+opencv-python==4.13.0.92
+scipy==1.17.1
+pandas==3.0.2
+pillow==12.1.1
+tqdm==4.67.3
+pygame==2.6.1
+
+# Visualization & Heatmaps
+matplotlib==3.10.8
+plotly==6.6.0
+open3d==0.19.0
+pyntcloud==0.3.1
+
+# Dashboards & GUI
+Flask==3.1.3
+Werkzeug==3.1.7
+itsdangerous==2.2.0
+Jinja2==3.1.6
+click==8.3.1
+blinker==1.9.0
+
+# Radar Synthesis (Shenron)
+torch==2.5.1
+torchvision==0.20.1
+torchaudio==2.5.1
+PyYAML==6.0.3
+
+# Foxglove & MCAP Serialization
+mcap==1.3.1
+mcap-ros2-support==0.5.7
+lz4==4.4.5
+zstandard==0.25.0
+
+# System Utilities
+psutil==7.2.2
+nvidia-ml-py==13.595.45
+requests==2.33.1
+certifi==2026.2.25

scratch/full_requirements.txt

@@ -0,0 +1,87 @@
+asttokens==3.0.1
+attrs==26.1.0
+blinker==1.9.0
+carla @ file:///D:/CARLA/CARLA_0.9.16/PythonAPI/carla/dist/carla-0.9.16-cp312-cp312-win_amd64.whl#sha256=b4700a1cfff8a9bda1018a233b25045ce6e00a7b180b8bd0edea6366c3f7c9eb
+certifi==2026.2.25
+charset-normalizer==3.4.6
+click==8.3.1
+colorama==0.4.6
+comm==0.2.3
+ConfigArgParse==1.7.5
+contourpy==1.3.3
+cycler==0.12.1
+dash==4.1.0
+decorator==5.2.1
+executing==2.2.1
+fastjsonschema==2.21.2
+filelock==3.25.2
+Flask==3.1.3
+fonttools==4.62.1
+fsspec==2026.3.0
+idna==3.11
+importlib_metadata==9.0.0
+ipython==9.12.0
+ipython_pygments_lexers==1.1.1
+ipywidgets==8.1.8
+itsdangerous==2.2.0
+jedi==0.19.2
+Jinja2==3.1.6
+jsonschema==4.26.0
+jsonschema-specifications==2025.9.1
+jupyter_core==5.9.1
+jupyterlab_widgets==3.0.16
+kiwisolver==1.5.0
+lz4==4.4.5
+MarkupSafe==3.0.3
+mat4py==0.6.0
+matplotlib==3.10.8
+matplotlib-inline==0.2.1
+mcap==1.3.1
+mcap-ros2-support==0.5.7
+mpmath==1.3.0
+narwhals==2.18.1
+nbformat==5.10.4
+nest-asyncio==1.6.0
+networkx==3.6.1
+numpy==2.4.3
+nvidia-ml-py==13.595.45
+open3d==0.19.0
+opencv-python==4.13.0.92
+packaging @ file:///C:/miniconda3/conda-bld/packaging_1761049137378/work
+pandas==3.0.2
+parso==0.8.6
+pillow==12.1.1
+platformdirs==4.9.4
+plotly==6.6.0
+prompt_toolkit==3.0.52
+psutil==7.2.2
+pure_eval==0.2.3
+pygame==2.6.1
+Pygments==2.20.0
+pyntcloud==0.3.1
+pyparsing==3.3.2
+python-dateutil==2.9.0.post0
+PyYAML==6.0.3
+referencing==0.37.0
+requests==2.33.1
+retrying==1.4.2
+rpds-py==0.30.0
+scipy==1.17.1
+setuptools==80.10.2
+six==1.17.0
+stack-data==0.6.3
+sympy==1.13.1
+torch==2.5.1+cu121
+torchaudio==2.5.1+cu121
+torchvision==0.20.1+cu121
+tqdm==4.67.3
+traitlets==5.14.3
+typing_extensions==4.15.0
+tzdata==2025.3
+urllib3==2.6.3
+wcwidth==0.6.0
+Werkzeug==3.1.7
+wheel==0.46.3
+widgetsnbextension==4.0.15
+zipp==3.23.0
+zstandard==0.25.0