From 1e0a91f1b8eb963ff88868c79c812fe4cb30cb92 Mon Sep 17 00:00:00 2001
From: Michael Katsoulis <michael.katsoulis@kyburz-switzerland.ch>
Date: Mon, 12 Jan 2026 09:33:44 +0100
Subject: [PATCH] Update and polish Readme

---
 README.md | 74 ++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 52 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 877fe78..74762ac 100644
--- a/README.md
+++ b/README.md
@@ -1,34 +1,64 @@
-# Build the docker image
-```bash
-docker build -t exwayz_test:v1.0 -f exwayz_test.dockerfile .
+# **Project Overview**
+
+This repository contains the container and supporting files used by the LENA autonomous vehicle project. It packages the Exwayz 3D Mapping / SLAM executables into a Docker image that can run as part of the vehicle microservices stack.
+
+**Repository Contents**
+
+- **`exwayz_test.dockerfile`**: Dockerfile used to build the container image for testing and integration.
+- **`src/**`: all code that we have written which runs on the container.
+- **`tmp/data/`**: sample data including `exwayz_sample_data_slam_01.bag` used for demonstrations and tests. Download this from the link to their google drive on [the Exwayz docs site](https://exwayz.notion.site/Exwayz-3D-Mapping-v1-latest-1ea57c917367810ea1e9f8bf83e2e9d4)
+- **`media/`**: screenshots and demos (GIFs) used in documentation.
+- **`licenses/`**: licensing information for included components.
+
+**Contributing**
+
+Please open issues or PRs for fixes and improvements. If you work on vehicle deployment or CI, include small, testable changes and document any required secrets or hardware assumptions.
+
+
+# **Quick Start**
+
+Build the image (from the repository root):
+
+```powershell
+docker build -f exwayz_test.dockerfile -t exwayz_test:latest .
 ```
-## TODO Building with docker secrets
-We need to improve our handling of secrets and figure out a safer way to include them in the docker file/image
 
+Run the container (example; adjust mounts and environment for your platform):
 
-
-# To run the docker file:
-1. We need to enable the use of the display
-2. Share the volume with our current code so we can access it in the container
-3. start a shell 
-
-```bash
-docker run -it \
-    --env="DISPLAY=$DISPLAY" \
+```powershell
+# Example (PowerShell on systems with X11 forwarding available)
+docker run -it --rm \
+    --env="DISPLAY=$env:DISPLAY" \
     --env="QT_X11_NO_MITSHM=1" \
     --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \
-    -v "$(pwd):/app" \
-    exwayz_test
+    -v "${PWD}:/app" \
+    exwayz_test:latest
 ```
 
+On POSIX shells use `$DISPLAY` and `$(pwd)` as usual.
 
-Then, run the exways slam on a bag to test everything is workign correctly.
+Run the Exwayz SLAM pipeline against the sample bag inside the container (example):
 
-```bash 
-exwayz_slam --bag data/exwayz_sample_data_slam_01.bag --bag-hesai /hesai/pandar_packets --hesai-model PandarXT-32 --d-write 0.1 -o ./slam_session_tutorial --no-date
+```bash
+exwayz_slam --bag tmp/data/exwayz_sample_data_slam_01.bag \
+    --bag-hesai /hesai/pandar_packets \
+    --hesai-model PandarXT-32 \
+    --d-write 0.1 -o ./slam_session_tutorial --no-date
 ```
 
-Naturally, change the path to the bagfile for the parameter '--bag'
+Adjust paths and model names to match your sensor and bag file layout.
 
-Hopefully, you will see something like this:
-![Working Exwayz Demo¨¨](media/Exwayz_slam_demo_working.gif)
+# **Status**
+
+- Docker image: mostly working for local testing.
+- Secrets: currently not included in the image; build-time and runtime secrets need secure handling (see TODOs).
+- Target: this repo should evolve into the deploy-and-run repo for vehicle microservices.
+
+# **Todos**
+- [x] **Prototype Docker Image**: Get a prototype docker image working and run their demos.
+- [x] **Refine README**: polish documentation and examples (in progress).
+- [ ] **Secrets Handling**: implement secure secret injection for builds and runtime (Docker BuildKit, secret manager, or CI secrets).
+- [ ] **Standardized Scripts**: add `build_image.ps1` and `run_container.ps1` (and POSIX equivalents) to standardize workflows.
+- [ ] **CI Build**: add GitHub Actions workflow equivalent to Gitea to build (and optionally scan) images on push/PR.
+- [ ] **Vehicle Deployment Guide**: document runtime flags, service templates, and health-checks for deployment on the vehicle.
+- [ ] **Integration Test**: add tests that run the pipeline against `tmp/data/exwayz_sample_data_slam_01.bag` to detect regressions.