docs: README updates in subfolders

data_preparation/README.md

@@ -1,9 +1,9 @@
 # data_preparation/
 
-Load and split the .npz data. Used by all training code and notebooks.
+Load, clean, split `.npz` data for training/notebooks. **Important:** recompute **head_deviation** from **clipped** yaw/pitch (see `prepare_dataset.py`). **10** features for `face_orientation`: `head_deviation`, `s_face`, `s_eye`, `h_gaze`, `pitch`, `ear_left`, `ear_avg`, `ear_right`, `gaze_offset`, `perclos`.
 
 **prepare_dataset.py:** `load_all_pooled()`, `load_per_person()` for LOPO, `get_numpy_splits()` (XGBoost), `get_dataloaders()` (MLP). Cleans yaw/pitch/roll and EAR to fixed ranges. Face_orientation uses 10 features: head_deviation, s_face, s_eye, h_gaze, pitch, ear_left, ear_avg, ear_right, gaze_offset, perclos.
 
 **data_exploration.ipynb:** EDA — stats, class balance, histograms, correlations.
 
-You don’t run prepare_dataset directly; import it from `models.mlp.train`, `models.xgboost.train`, or the notebooks.
+Import from `models.mlp.train` / `models.xgboost.train` / notebooks — don’t run this module standalone.

evaluation/README.md

@@ -1,6 +1,6 @@
 # evaluation/
 
-Training logs, threshold/weight analysis, and metrics.
+Training logs, threshold/weight analysis, metrics. **LOPO** (9 folds) + **Youden’s J** + weight grid search — see `justify_thresholds.py`.
 
 **Contents:** `logs/` (JSON from training runs), `plots/` (ROC, weight search, EAR/MAR), `justify_thresholds.py`, `feature_importance.py`, and the generated markdown reports.
 

models/L2CS-Net/README.md

@@ -1,5 +1,4 @@
-
-
+Bundled for FocusGuard (optional gaze veto, Gaze360 weights). See repo root `README.md`.
 
  <p align="center">
   <img src="https://github.com/Ahmednull/Storage/blob/main/gaze.gif" alt="animated" />

models/L2CS-Net/models/README.md

@@ -1 +1 @@
-# Path to pre-trained models
+# Path to pre-trained weights

models/README.md

@@ -1,6 +1,6 @@
 # models/
 
-Feature extraction + model training scripts for FocusGuard.
+Feature extraction + training for FocusGuard (17 features → 10 for MLP/XGB; geometric/hybrid/L2CS paths — see root `README.md`).
 
 ## What is here
 

notebooks/README.md

@@ -1,7 +1,5 @@
 # notebooks/
 
-MLP and XGBoost training + LOPO evaluation.
+`mlp.ipynb`, `xgboost.ipynb`: same flow as scripted trainers (config → `prepare_dataset` → 70/15/15 → metrics → checkpoint + log → **LOPO** over 9 people).
 
-**Files:** `mlp.ipynb`, `xgboost.ipynb`. Same flow: config → data from prepare_dataset → 70/15/15 train → loss curves → test metrics → save checkpoint + JSON log → LOPO over 9 participants.
-
-Run in Jupyter with the project venv; set kernel cwd to repo root or `notebooks/`.
+Jupyter + project venv; cwd = repo root or `notebooks/`.

ui/README.md

@@ -1,10 +1,10 @@
 # ui/
 
-Live OpenCV demo and inference pipelines used by the app.
+OpenCV demo + inference pipelines used by **`main.py`** (FastAPI WebSocket `/ws/video`, latest-frame buffer; React UI + SQLite sessions).
 
-**Files:** `pipeline.py` (FaceMesh, MLP, XGBoost, Hybrid pipelines), `live_demo.py` (webcam window with mesh + focus label).
+**Files:** `pipeline.py` (FaceMesh, MLP, XGBoost, Hybrid), `live_demo.py` (webcam + mesh + label).
 
-**Pipelines:** FaceMesh = rule-based head/eye; MLP = 10 features → PyTorch MLP (checkpoints/mlp_best.pt + scaler); XGBoost = same 10 features → xgboost_face_orientation_best.json. Hybrid combines ML/XGB with geometric scores.
+**Pipelines:** Geometric / MLP (`mlp_best.pt` + scaler) / XGBoost (`xgboost_face_orientation_best.json`) / hybrid + optional L2CS veto.
 
 **Run demo:**