docs: update README and RUN guides with engine auto-recompilation details

README.md

@@ -26,6 +26,8 @@ visual.
 configs/
   cameras/example_camera.yaml
   cycle7_batch.yaml
+  cycle7_batch_optimized.yaml
+  mortality_config.yaml
   trackers/botsort_chicken.yaml
 src/chicken_counter/
   batch_discovery.py
@@ -35,6 +37,8 @@ src/chicken_counter/
   compress.py
   config.py
   counting.py
+  engine_utils.py
+  mortality.py
   motion.py
   overlay.py
   pipeline.py
@@ -42,6 +46,9 @@ src/chicken_counter/
   tracking.py
   types.py
   video_writer.py
+dashboard.py
+export_engine.py
+export_excel_report.py
 ```
 
 ## Install
@@ -223,6 +230,20 @@ for tuning.
 - The optical-flow trigger is vision-first, though the config structure leaves room for
   a future controller/encoder integration path
 
+## Cross-Machine Portability & Self-Healing Engine Auto-Recompilation
+
+TensorRT `.engine` files are compiled specifically for the host GPU architecture and TensorRT version. When copying the project to a different machine (e.g. from Jetson to NUC or across different RTX GPUs):
+
+- **Automatic Compatibility Check**: `src/chicken_counter/engine_utils.py` runs a fast health check on the specified `.engine` before counting starts.
+- **Self-Healing Recompilation**: If an incompatibility (e.g. platform tag mismatch or different compute capability) is detected:
+  1. The system automatically searches `models/` for the matching base `.pt` model weights (stripping hardware prefixes like `NUC5070_` or `jetson_`).
+  2. Automatically compiles a new optimized `.engine` on the host machine using FP16 precision.
+  3. Updates `defaults.detection.model_path` in `configs/cycle7_batch_optimized.yaml` automatically.
+- **Manual Export Tool**: You can also compile engines manually anytime using `export_engine.py`:
+  ```bash
+  ./venv/bin/python export_engine.py models/chicken-detection-model-v26n-300e-best-2026-05-02-NEW.pt --half --workspace 4
+  ```
+
 ## Multi-Stage Growth Cycles & Day 0 Configuration
 
 The pipeline dynamically adjusts detection and ROI entry thresholds based on flock age (Days Old Chick / DOC vs Mid-Cycle):

RUN.md

@@ -42,11 +42,14 @@ chicken-counting-sukawarna-det/
 ├── db/
 │   └── chicken_counts.db             ← SQLite database (auto-created)
 ├── models/                           ← Place your .pt / .onnx / .engine files here
-│   ├── chicken-detection-model-v26n-300e-best-2026-05-02-NEW.onnx
+│   ├── chicken-detection-model-v26n-300e-best-2026-05-02-NEW.pt   ← Source PyTorch model
-│   └── chicken-detection-model-v26n-seg-300e-best-2026-04-18.pt  ← Used by mortality
+│   ├── chicken-detection-model-v26n-300e-best-2026-05-02-NEW.engine ← Hardware-tuned TensorRT
-├── src/chicken_counter/              ← Main Python package
+│   └── chicken-detection-model-v26n-seg-300e-best-2026-04-18.pt   ← Used by mortality
+├── src/chicken_counter/              ← Main Python package (counting, tracking, motion, engine_utils)
 ├── templates/                        ← Dashboard HTML
 ├── dashboard.py                      ← Live API + Dashboard server
+├── export_engine.py                  ← Manual TensorRT export utility
+├── export_excel_report.py            ← Excel reporting & analytics generator
 ├── start_dashboard.sh                ← Portable dashboard launcher ← USE THIS
 ├── test_run_mortality.sh             ← Run mortality detection
 ├── test_run.sh                       ← Run batch processing all dates
@@ -55,16 +58,17 @@ chicken-counting-sukawarna-det/
 
 ---
 
-## 4. Model Setup
+## 4. Model Setup & Auto-Recompilation
 
 Put your model files in the `models/` directory.
 
-| Purpose | File |
+| Purpose | File | Notes |
-| :--- | :--- |
+| :--- | :--- | :--- |
-| Batch video counting | `chicken-detection-model-v26n-300e-best-2026-05-02-NEW.onnx` (speed) or `.pt` (accuracy) |
+| Batch video counting (TensorRT) | `models/chicken-detection-model-v26n-300e-best-2026-05-02-NEW.engine` | Maximum GPU throughput |
-| Mortality detection | `chicken-detection-model-v26n-seg-300e-best-2026-04-18.pt` |
+| Base PyTorch weights | `models/chicken-detection-model-v26n-300e-best-2026-05-02-NEW.pt` | Used for portable runs and auto-recompiling engines |
+| Mortality detection | `models/chicken-detection-model-v26n-seg-300e-best-2026-04-18.pt` | 2-pass segmentation model |
 
-Update `configs/mortality_config.yaml` and `configs/cycle7_batch_optimized.yaml` if using different filenames.
+> **Self-Healing Recompilation on New Machines**: If you move the project to a new machine with a different GPU or OS, the pipeline will detect any incompatible `.engine`, automatically locate the matching `.pt` model, recompile a new `.engine` for the host machine, and update `configs/cycle7_batch_optimized.yaml` automatically.
 
 ---